summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2012-12-07 17:29:51 -0600
committerRichard Purdie <richard.purdie@linuxfoundation.org>2012-12-11 16:17:56 +0000
commit73ffb8298b545a1a1fb96bc5952b7365c4c43bfd (patch)
tree9c6473cb4e3c5dd8370c2d417c304e1a302fa643
parentacb3f72afaa28ba5d23ca6e5cdf9f1162ea656a3 (diff)
downloadpoky-73ffb8298b545a1a1fb96bc5952b7365c4c43bfd.tar.gz
Documentation: poky-ref-manual - Removed all trailing whitespace.
(From yocto-docs rev: 564a28c2501034ea7e2eb16afc43dfaf931b6f6f) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
-rw-r--r--documentation/poky-ref-manual/faq.xml181
-rw-r--r--documentation/poky-ref-manual/introduction.xml100
-rw-r--r--documentation/poky-ref-manual/migration.xml148
-rw-r--r--documentation/poky-ref-manual/poky-ref-manual.xml18
-rw-r--r--documentation/poky-ref-manual/ref-bitbake.xml272
-rw-r--r--documentation/poky-ref-manual/ref-classes.xml346
-rw-r--r--documentation/poky-ref-manual/ref-features.xml124
-rw-r--r--documentation/poky-ref-manual/ref-images.xml66
-rw-r--r--documentation/poky-ref-manual/ref-structure.xml260
-rw-r--r--documentation/poky-ref-manual/ref-variables.xml1292
-rw-r--r--documentation/poky-ref-manual/ref-varlocality.xml8
-rw-r--r--documentation/poky-ref-manual/resources.xml18
-rw-r--r--documentation/poky-ref-manual/technical-details.xml434
-rw-r--r--documentation/poky-ref-manual/usingpoky.xml264
14 files changed, 1765 insertions, 1766 deletions
diff --git a/documentation/poky-ref-manual/faq.xml b/documentation/poky-ref-manual/faq.xml
index 945c7f19af..176573de28 100644
--- a/documentation/poky-ref-manual/faq.xml
+++ b/documentation/poky-ref-manual/faq.xml
@@ -19,11 +19,11 @@
19 and BitBake. 19 and BitBake.
20 Thus, the generic term used here for the build system is 20 Thus, the generic term used here for the build system is
21 the "OpenEmbedded build system." 21 the "OpenEmbedded build system."
22 Development in the Yocto Project using Poky is closely tied to OpenEmbedded, with 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 23 changes always being merged to OE-Core or BitBake first before being pulled back
24 into Poky. 24 into Poky.
25 This practice benefits both projects immediately. 25 This practice benefits both projects immediately.
26 For a fuller description of the term "Poky", see the 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 27 <ulink url='&YOCTO_DOCS_DEV_URL;#poky'>poky</ulink> term in the Yocto Project
28 Development Manual. 28 Development Manual.
29 </para> 29 </para>
@@ -47,9 +47,9 @@
47 </itemizedlist> 47 </itemizedlist>
48 </para> 48 </para>
49 <para> 49 <para>
50 These tarballs are self-contained with all required libraries and should work 50 These tarballs are self-contained with all required libraries and should work
51 on most Linux systems. 51 on most Linux systems.
52 To use the tarballs extract them into the root 52 To use the tarballs extract them into the root
53 directory and run the appropriate command: 53 directory and run the appropriate command:
54 <literallayout class='monospaced'> 54 <literallayout class='monospaced'>
55 $ export PATH=/opt/poky/sysroots/i586-pokysdk-linux/usr/bin/:$PATH 55 $ export PATH=/opt/poky/sysroots/i586-pokysdk-linux/usr/bin/:$PATH
@@ -72,12 +72,12 @@
72 <para> 72 <para>
73 There are three areas that help with stability; 73 There are three areas that help with stability;
74 <itemizedlist> 74 <itemizedlist>
75 <listitem><para>The Yocto Project team keeps 75 <listitem><para>The Yocto Project team keeps
76 <ulink url='&YOCTO_DOCS_DEV_URL;#oe-core'>OE-Core</ulink> small 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 77 and focused, containing around 830 recipes as opposed to the thousands
78 available in other OpenEmbedded community layers. 78 available in other OpenEmbedded community layers.
79 Keeping it small makes it easy to test and maintain.</para></listitem> 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 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 81 using a small, fixed set of reference hardware as well as emulated
82 targets.</para></listitem> 82 targets.</para></listitem>
83 <listitem><para>The Yocto Project uses an an autobuilder, 83 <listitem><para>The Yocto Project uses an an autobuilder,
@@ -100,7 +100,7 @@
100 <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>. 100 <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>.
101 </para> 101 </para>
102 <para> 102 <para>
103 Usually, if the board is not completely exotic, adding support in 103 Usually, if the board is not completely exotic, adding support in
104 the Yocto Project is fairly straightforward. 104 the Yocto Project is fairly straightforward.
105 </para> 105 </para>
106 </answer> 106 </answer>
@@ -115,10 +115,10 @@
115 <answer> 115 <answer>
116 <para> 116 <para>
117 The software running on the <ulink url='http://vernier.com/labquest/'>Vernier LabQuest</ulink> 117 The software running on the <ulink url='http://vernier.com/labquest/'>Vernier LabQuest</ulink>
118 is built using the OpenEmbedded build system. 118 is built using the OpenEmbedded build system.
119 See the <ulink url='http://www.vernier.com/products/interfaces/labq/'>Vernier LabQuest</ulink> 119 See the <ulink url='http://www.vernier.com/products/interfaces/labq/'>Vernier LabQuest</ulink>
120 website for more information. 120 website for more information.
121 There are a number of pre-production devices using the OpenEmbedded build system 121 There are a number of pre-production devices using the OpenEmbedded build system
122 and the Yocto Project team 122 and the Yocto Project team
123 announces them as soon as they are released. 123 announces them as soon as they are released.
124 </para> 124 </para>
@@ -133,8 +133,8 @@
133 </question> 133 </question>
134 <answer> 134 <answer>
135 <para> 135 <para>
136 Because the same set of recipes can be used to create output of various formats, the 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. 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. 138 Usually, the output is a flashable image ready for the target device.
139 </para> 139 </para>
140 </answer> 140 </answer>
@@ -150,7 +150,7 @@
150 <para> 150 <para>
151 To add a package, you need to create a BitBake recipe. 151 To add a package, you need to create a BitBake recipe.
152 For information on how to add a package, see the section 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>" 153 "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-extend-addpkg'>Adding a Package</ulink>"
154 in the Yocto Project Development Manual. 154 in the Yocto Project Development Manual.
155 </para> 155 </para>
156 </answer> 156 </answer>
@@ -159,16 +159,16 @@
159 <qandaentry> 159 <qandaentry>
160 <question> 160 <question>
161 <para> 161 <para>
162 Do I have to reflash my entire board with a new Yocto Project image when recompiling 162 Do I have to reflash my entire board with a new Yocto Project image when recompiling
163 a package? 163 a package?
164 </para> 164 </para>
165 </question> 165 </question>
166 <answer> 166 <answer>
167 <para> 167 <para>
168 The OpenEmbedded build system can build packages in various formats such as 168 The OpenEmbedded build system can build packages in various formats such as
169 <filename>ipk</filename> for <filename>opkg</filename>, 169 <filename>ipk</filename> for <filename>opkg</filename>,
170 Debian package (<filename>.deb</filename>), or RPM. 170 Debian package (<filename>.deb</filename>), or RPM.
171 The packages can then be upgraded using the package tools on the device, much like 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. 172 on a desktop distribution such as Ubuntu or Fedora.
173 </para> 173 </para>
174 </answer> 174 </answer>
@@ -182,11 +182,11 @@
182 </question> 182 </question>
183 <answer> 183 <answer>
184 <para> 184 <para>
185 GNOME Mobile is a subset of the <ulink url='http://www.gnome.org'>GNOME</ulink> 185 GNOME Mobile is a subset of the <ulink url='http://www.gnome.org'>GNOME</ulink>
186 platform targeted at mobile and embedded devices. 186 platform targeted at mobile and embedded devices.
187 The the main difference between GNOME Mobile and standard GNOME is that 187 The the main difference between GNOME Mobile and standard GNOME is that
188 desktop-orientated libraries have been removed, along with deprecated libraries, 188 desktop-orientated libraries have been removed, along with deprecated libraries,
189 creating a much smaller footprint. 189 creating a much smaller footprint.
190 </para> 190 </para>
191 </answer> 191 </answer>
192 </qandaentry> 192 </qandaentry>
@@ -200,7 +200,7 @@
200 </question> 200 </question>
201 <answer> 201 <answer>
202 <para> 202 <para>
203 You are probably running the build on an NTFS filesystem. 203 You are probably running the build on an NTFS filesystem.
204 Use <filename>ext2</filename>, <filename>ext3</filename>, or <filename>ext4</filename> instead. 204 Use <filename>ext2</filename>, <filename>ext3</filename>, or <filename>ext4</filename> instead.
205 </para> 205 </para>
206 </answer> 206 </answer>
@@ -214,8 +214,8 @@
214 </question> 214 </question>
215 <answer> 215 <answer>
216 <para> 216 <para>
217 To get the Yocto Project working under RHEL/CentOS 5.1 you need to first 217 To get the Yocto Project working under RHEL/CentOS 5.1 you need to first
218 install some required packages. 218 install some required packages.
219 The standard CentOS packages needed are: 219 The standard CentOS packages needed are:
220 <itemizedlist> 220 <itemizedlist>
221 <listitem><para>"Development tools" (selected during installation)</para></listitem> 221 <listitem><para>"Development tools" (selected during installation)</para></listitem>
@@ -224,19 +224,19 @@
224 </itemizedlist> 224 </itemizedlist>
225 On top of these, you need the following external packages: 225 On top of these, you need the following external packages:
226 <itemizedlist> 226 <itemizedlist>
227 <listitem><para><filename>python-sqlite2</filename> from 227 <listitem><para><filename>python-sqlite2</filename> from
228 <ulink url='http://dag.wieers.com/rpm/packages/python-sqlite2/'>DAG repository</ulink> 228 <ulink url='http://dag.wieers.com/rpm/packages/python-sqlite2/'>DAG repository</ulink>
229 </para></listitem> 229 </para></listitem>
230 <listitem><para><filename>help2man</filename> from 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> 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> 232 </itemizedlist>
233 </para> 233 </para>
234 234
235 <para> 235 <para>
236 Once these packages are installed, the OpenEmbedded build system will be able 236 Once these packages are installed, the OpenEmbedded build system will be able
237 to build standard images. 237 to build standard images.
238 However, there might be a problem with the QEMU emulator segfaulting. 238 However, there might be a problem with the QEMU emulator segfaulting.
239 You can either disable the generation of binary locales by setting 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> 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> 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. 242 from the kernel and rebuilding it since that is the patch that causes the problems with QEMU.
@@ -247,22 +247,22 @@
247 <qandaentry> 247 <qandaentry>
248 <question> 248 <question>
249 <para> 249 <para>
250 I see lots of 404 responses for files on 250 I see lots of 404 responses for files on
251 <filename>http://www.yoctoproject.org/sources/*</filename>. Is something wrong? 251 <filename>http://www.yoctoproject.org/sources/*</filename>. Is something wrong?
252 </para> 252 </para>
253 </question> 253 </question>
254 <answer> 254 <answer>
255 <para> 255 <para>
256 Nothing is wrong. 256 Nothing is wrong.
257 The OpenEmbedded build system checks any configured source mirrors before downloading 257 The OpenEmbedded build system checks any configured source mirrors before downloading
258 from the upstream sources. 258 from the upstream sources.
259 The build system does this searching for both source archives and 259 The build system does this searching for both source archives and
260 pre-checked out versions of SCM managed software. 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 261 These checks help in large installations because it can reduce load on the SCM servers
262 themselves. 262 themselves.
263 The address above is one of the default mirrors configured into the 263 The address above is one of the default mirrors configured into the
264 build system. 264 build system.
265 Consequently, if an upstream source disappears, the team 265 Consequently, if an upstream source disappears, the team
266 can place sources there so builds continue to work. 266 can place sources there so builds continue to work.
267 </para> 267 </para>
268 </answer> 268 </answer>
@@ -271,16 +271,16 @@
271 <qandaentry> 271 <qandaentry>
272 <question> 272 <question>
273 <para> 273 <para>
274 I have machine-specific data in a package for one machine only but the package is 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? 275 being marked as machine-specific in all cases, how do I prevent this?
276 </para> 276 </para>
277 </question> 277 </question>
278 <answer> 278 <answer>
279 <para> 279 <para>
280 Set <filename><link linkend='var-SRC_URI_OVERRIDES_PACKAGE_ARCH'>SRC_URI_OVERRIDES_PACKAGE_ARCH</link> 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 281 </filename> = "0" in the <filename>.bb</filename> file but make sure the package is
282 manually marked as 282 manually marked as
283 machine-specific in the case that needs it. 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>. 284 The code that handles <filename>SRC_URI_OVERRIDES_PACKAGE_ARCH</filename> is in <filename>base.bbclass</filename>.
285 </para> 285 </para>
286 </answer> 286 </answer>
@@ -295,9 +295,9 @@
295 <answer> 295 <answer>
296 <para> 296 <para>
297 Most source fetching by the OpenEmbedded build system is done by <filename>wget</filename> 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 298 and you therefore need to specify the proxy settings in a
299 <filename>.wgetrc</filename> file in your home directory. 299 <filename>.wgetrc</filename> file in your home directory.
300 Example settings in that file would be 300 Example settings in that file would be
301 <literallayout class='monospaced'> 301 <literallayout class='monospaced'>
302 http_proxy = http://proxy.yoyodyne.com:18023/ 302 http_proxy = http://proxy.yoyodyne.com:18023/
303 ftp_proxy = http://proxy.yoyodyne.com:18023/ 303 ftp_proxy = http://proxy.yoyodyne.com:18023/
@@ -317,10 +317,10 @@
317 </question> 317 </question>
318 <answer> 318 <answer>
319 <para> 319 <para>
320 The <filename>*-native</filename> targets are designed to run on the system 320 The <filename>*-native</filename> targets are designed to run on the system
321 being used for the build. 321 being used for the build.
322 These are usually tools that are needed to assist the build in some way such as 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. 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. 324 The non-native version is the one that runs on the target device.
325 </para> 325 </para>
326 </answer> 326 </answer>
@@ -335,11 +335,11 @@
335 <answer> 335 <answer>
336 <para> 336 <para>
337 If the same build is failing in totally different and random ways, 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 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, 339 build on has some problem, or, if you are running the build under virtualisation,
340 the virtualisation probably has bugs. 340 the virtualisation probably has bugs.
341 The OpenEmbedded build system processes a massive amount of data causing lots of network, disk and 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. 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. 343 True random failures have always been traced back to hardware or virtualisation issues.
344 </para> 344 </para>
345 </answer> 345 </answer>
@@ -356,8 +356,8 @@
356 This is a difficult question and you need to consult your lawyer for the answer 356 This is a difficult question and you need to consult your lawyer for the answer
357 for your specific case. 357 for your specific case.
358 It is worth bearing in mind that for GPL compliance there needs to be enough 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 359 information shipped to allow someone else to rebuild the same end result
360 you are shipping. 360 you are shipping.
361 This means sharing the source code, any patches applied to it, and also any 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. 362 configuration information about how that package was configured and built.
363 </para> 363 </para>
@@ -390,9 +390,9 @@
390 </question> 390 </question>
391 <answer> 391 <answer>
392 <para> 392 <para>
393 The default interfaces file provided by the netbase recipe does not 393 The default interfaces file provided by the netbase recipe does not
394 automatically bring up network interfaces. 394 automatically bring up network interfaces.
395 Therefore, you will need to add a BSP-specific netbase that includes an interfaces 395 Therefore, you will need to add a BSP-specific netbase that includes an interfaces
396 file. 396 file.
397 See the "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-filelayout-misc-recipes'>Miscellaneous Recipe Files</ulink>" 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. 398 section for information on creating these types of miscellaneous recipe files.
@@ -415,11 +415,11 @@
415 </question> 415 </question>
416 <answer> 416 <answer>
417 <para> 417 <para>
418 Images are created to be 1.2 times the size of the populated root filesystem. 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 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>. 420 set the configuration value <filename>IMAGE_OVERHEAD_FACTOR</filename>.
421 For example, setting <filename>IMAGE_OVERHEAD_FACTOR</filename> to 1.5 sets 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 422 the image size ratio to one and a half times the size of the populated
423 root filesystem. 423 root filesystem.
424 <literallayout class='monospaced'> 424 <literallayout class='monospaced'>
425 IMAGE_OVERHEAD_FACTOR = "1.5" 425 IMAGE_OVERHEAD_FACTOR = "1.5"
@@ -436,9 +436,9 @@
436 </question> 436 </question>
437 <answer> 437 <answer>
438 <para> 438 <para>
439 The Yocto Project team has tried to do this before but too many of the tools 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> 440 the OpenEmbedded build system depends on such as <filename>autoconf</filename>
441 break when they find spaces in pathnames. 441 break when they find spaces in pathnames.
442 Until that situation changes, the team will not support spaces in pathnames. 442 Until that situation changes, the team will not support spaces in pathnames.
443 </para> 443 </para>
444 </answer> 444 </answer>
@@ -453,10 +453,10 @@
453 <answer> 453 <answer>
454 <para> 454 <para>
455 The toolchain configuration is very flexible and customizable. 455 The toolchain configuration is very flexible and customizable.
456 It is primarily controlled with the 456 It is primarily controlled with the
457 <filename><link linkend='var-TCMODE'>TCMODE</link></filename> variable. 457 <filename><link linkend='var-TCMODE'>TCMODE</link></filename> variable.
458 This variable controls which <filename>tcmode-*.inc</filename> file to include 458 This variable controls which <filename>tcmode-*.inc</filename> file to include
459 from the <filename>meta/conf/distro/include</filename> directory within the 459 from the <filename>meta/conf/distro/include</filename> directory within the
460 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>source directory</ulink>. 460 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>source directory</ulink>.
461 </para> 461 </para>
462 462
@@ -466,15 +466,15 @@
466 However, other patterns are accepted. 466 However, other patterns are accepted.
467 In particular, "external-*" refers to external toolchains of which there are some 467 In particular, "external-*" refers to external toolchains of which there are some
468 basic examples included in the OpenEmbedded Core (<filename>meta</filename>). 468 basic examples included in the OpenEmbedded Core (<filename>meta</filename>).
469 You can use your own custom toolchain definition in your own layer 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 470 (or as defined in the <filename>local.conf</filename> file) at the location
471 <filename>conf/distro/include/tcmode-*.inc</filename>. 471 <filename>conf/distro/include/tcmode-*.inc</filename>.
472 </para> 472 </para>
473 473
474 <para> 474 <para>
475 In addition to the toolchain configuration, you also need a corresponding toolchain recipe file. 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 476 This recipe file needs to package up any pre-built objects in the toolchain such as
477 <filename>libgcc</filename>, <filename>libstdcc++</filename>, 477 <filename>libgcc</filename>, <filename>libstdcc++</filename>,
478 any locales, and <filename>libc</filename>. 478 any locales, and <filename>libc</filename>.
479 An example is the <filename>external-sourcery-toolchain.bb</filename>, which is located 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. 480 in <filename>meta/recipes-core/meta/</filename> within the source directory.
@@ -485,7 +485,7 @@
485 <qandaentry> 485 <qandaentry>
486 <question> 486 <question>
487 <para id='how-does-the-yocto-project-obtain-source-code-and-will-it-work-behind-my-firewall-or-proxy-server'> 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 488 How does the OpenEmbedded build system obtain source code and will it work behind my
489 firewall or proxy server? 489 firewall or proxy server?
490 </para> 490 </para>
491 </question> 491 </question>
@@ -497,13 +497,13 @@
497 </para> 497 </para>
498 <para> 498 <para>
499 When the build system searches for source code, it first tries the local download directory. 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, 500 If that location fails, Poky tries PREMIRRORS, the upstream source,
501 and then MIRRORS in that order. 501 and then MIRRORS in that order.
502 </para> 502 </para>
503 <para> 503 <para>
504 By default, the OpenEmbedded build system uses the Yocto Project source PREMIRRORS 504 By default, the OpenEmbedded build system uses the Yocto Project source PREMIRRORS
505 for SCM-based sources, 505 for SCM-based sources,
506 upstreams for normal tarballs, and then falls back to a number of other mirrors 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. 507 including the Yocto Project source mirror if those fail.
508 </para> 508 </para>
509 <para> 509 <para>
@@ -521,7 +521,7 @@
521 <para> 521 <para>
522 These changes cause Poky to intercept Git, FTP, HTTP, and HTTPS 522 These changes cause Poky to intercept Git, FTP, HTTP, and HTTPS
523 requests and direct them to the <filename>http://</filename> sources mirror. 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 524 You can use <filename>file://</filename> URLs to point to local directories
525 or network shares as well. 525 or network shares as well.
526 </para> 526 </para>
527 <para> 527 <para>
@@ -529,7 +529,7 @@
529 <literallayout class='monospaced'> 529 <literallayout class='monospaced'>
530 BB_NO_NETWORK = "1" 530 BB_NO_NETWORK = "1"
531 </literallayout> 531 </literallayout>
532 This statement tells BitBake to throw an error instead of trying to access the 532 This statement tells BitBake to throw an error instead of trying to access the
533 Internet. 533 Internet.
534 This technique is useful if you want to ensure code builds only from local sources. 534 This technique is useful if you want to ensure code builds only from local sources.
535 </para> 535 </para>
@@ -559,14 +559,14 @@
559 ftp://.*/.* http://www.yoctoproject.org/sources/ \n \ 559 ftp://.*/.* http://www.yoctoproject.org/sources/ \n \
560 http://.*/.* http://www.yoctoproject.org/sources/ \n \ 560 http://.*/.* http://www.yoctoproject.org/sources/ \n \
561 https://.*/.* http://www.yoctoproject.org/sources/ \n" 561 https://.*/.* http://www.yoctoproject.org/sources/ \n"
562 BB_FETCH_PREMIRRORONLY = "1" 562 BB_FETCH_PREMIRRORONLY = "1"
563 </literallayout> 563 </literallayout>
564 These changes would cause Poky to successfully fetch source over HTTP and 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. 565 any network accesses to anything other than the PREMIRROR would fail.
566 </para> 566 </para>
567 <para> 567 <para>
568 The build system also honors the standard shell environment variables 568 The build system also honors the standard shell environment variables
569 <filename>http_proxy</filename>, <filename>ftp_proxy</filename>, 569 <filename>http_proxy</filename>, <filename>ftp_proxy</filename>,
570 <filename>https_proxy</filename>, and <filename>all_proxy</filename> 570 <filename>https_proxy</filename>, and <filename>all_proxy</filename>
571 to redirect requests through proxy servers. 571 to redirect requests through proxy servers.
572 </para> 572 </para>
@@ -582,16 +582,16 @@
582 <answer> 582 <answer>
583 <para> 583 <para>
584 Yes - you can easily do this. 584 Yes - you can easily do this.
585 When you use BitBake to build an image, all the build output goes into the 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> 586 directory created when you source the <filename>oe-init-build-env</filename>
587 setup file. 587 setup file.
588 By default, this <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>build directory</ulink> 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 589 is named <filename>build</filename> but can be named
590 anything you want. 590 anything you want.
591 </para> 591 </para>
592 592
593 <para> 593 <para>
594 Within the build directory is the <filename>tmp</filename> directory. 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 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. 596 from previous builds, simply remove the <filename>tmp</filename> directory.
597 </para> 597 </para>
@@ -601,7 +601,6 @@
601 601
602</qandaset> 602</qandaset>
603</chapter> 603</chapter>
604<!-- 604<!--
605vim: expandtab tw=80 ts=4 605vim: expandtab tw=80 ts=4
606--> 606-->
607
diff --git a/documentation/poky-ref-manual/introduction.xml b/documentation/poky-ref-manual/introduction.xml
index ab2e7d0f31..38c58da262 100644
--- a/documentation/poky-ref-manual/introduction.xml
+++ b/documentation/poky-ref-manual/introduction.xml
@@ -12,14 +12,14 @@
12 This manual provides reference information for the current release of the Yocto Project. 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 13 The Yocto Project is an open-source collaboration project focused on embedded Linux
14 developers. 14 developers.
15 Amongst other things, the Yocto Project uses the OpenEmbedded build system, which 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. 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 17 You can find complete introductory and getting started information on the Yocto Project
18 by reading the 18 by reading the
19 <ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink>. 19 <ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink>.
20 For task-based information using the Yocto Project, see the 20 For task-based information using the Yocto Project, see the
21 <ulink url='&YOCTO_DOCS_DEV_URL;'>Yocto Project Development Manual</ulink>. 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 22 You can also find lots of information on the Yocto Project on the
23 <ulink url="&YOCTO_HOME_URL;">Yocto Project website</ulink>. 23 <ulink url="&YOCTO_HOME_URL;">Yocto Project website</ulink>.
24 </para> 24 </para>
25</section> 25</section>
@@ -31,53 +31,53 @@
31 <itemizedlist> 31 <itemizedlist>
32 <listitem><para><emphasis> 32 <listitem><para><emphasis>
33 <link linkend='usingpoky'>Using the Yocto Project</link>:</emphasis> This chapter 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 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. 35 followed by information about debugging images created in the Yocto Project.
36 </para></listitem> 36 </para></listitem>
37 <listitem><para><emphasis> 37 <listitem><para><emphasis>
38 <link linkend='technical-details'>Technical Details</link>:</emphasis> 38 <link linkend='technical-details'>Technical Details</link>:</emphasis>
39 This chapter describes fundamental Yocto Project components as well as an explanation 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. 40 behind how the Yocto Project uses shared state (sstate) cache to speed build time.
41 </para></listitem> 41 </para></listitem>
42 <listitem><para><emphasis> 42 <listitem><para><emphasis>
43 <link linkend='ref-structure'>Directory Structure</link>:</emphasis> 43 <link linkend='ref-structure'>Directory Structure</link>:</emphasis>
44 This chapter describes the 44 This chapter describes the
45 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>source directory</ulink> created 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, 46 either by unpacking a released Yocto Project tarball on your host development system,
47 or by cloning the upstream 47 or by cloning the upstream
48 <ulink url='&YOCTO_DOCS_DEV_URL;#poky'>Poky</ulink> Git repository. 48 <ulink url='&YOCTO_DOCS_DEV_URL;#poky'>Poky</ulink> Git repository.
49 </para></listitem> 49 </para></listitem>
50 <listitem><para><emphasis> 50 <listitem><para><emphasis>
51 <link linkend='ref-bitbake'>BitBake</link>:</emphasis> 51 <link linkend='ref-bitbake'>BitBake</link>:</emphasis>
52 This chapter provides an overview of the BitBake tool and its role within 52 This chapter provides an overview of the BitBake tool and its role within
53 the Yocto Project.</para></listitem> 53 the Yocto Project.</para></listitem>
54 <listitem><para><emphasis> 54 <listitem><para><emphasis>
55 <link linkend='ref-classes'>Classes</link>:</emphasis> 55 <link linkend='ref-classes'>Classes</link>:</emphasis>
56 This chapter describes the classes used in the Yocto Project.</para></listitem> 56 This chapter describes the classes used in the Yocto Project.</para></listitem>
57 <listitem><para><emphasis> 57 <listitem><para><emphasis>
58 <link linkend='ref-images'>Images</link>:</emphasis> 58 <link linkend='ref-images'>Images</link>:</emphasis>
59 This chapter describes the standard images that the Yocto Project supports. 59 This chapter describes the standard images that the Yocto Project supports.
60 </para></listitem> 60 </para></listitem>
61 <listitem><para><emphasis> 61 <listitem><para><emphasis>
62 <link linkend='ref-features'>Features</link>:</emphasis> 62 <link linkend='ref-features'>Features</link>:</emphasis>
63 This chapter describes mechanisms for creating distribution, machine, and image 63 This chapter describes mechanisms for creating distribution, machine, and image
64 features during the build process using the OpenEmbedded build system.</para></listitem> 64 features during the build process using the OpenEmbedded build system.</para></listitem>
65 <listitem><para><emphasis> 65 <listitem><para><emphasis>
66 <link linkend='ref-variables-glos'>Variables Glossary</link>:</emphasis> 66 <link linkend='ref-variables-glos'>Variables Glossary</link>:</emphasis>
67 This chapter presents most variables used by the OpenEmbedded build system, which 67 This chapter presents most variables used by the OpenEmbedded build system, which
68 using BitBake. 68 using BitBake.
69 Entries describe the function of the variable and how to apply them. 69 Entries describe the function of the variable and how to apply them.
70 </para></listitem> 70 </para></listitem>
71 <listitem><para><emphasis> 71 <listitem><para><emphasis>
72 <link linkend='ref-varlocality'>Variable Context</link>:</emphasis> 72 <link linkend='ref-varlocality'>Variable Context</link>:</emphasis>
73 This chapter provides variable locality or context.</para></listitem> 73 This chapter provides variable locality or context.</para></listitem>
74 <listitem><para><emphasis> 74 <listitem><para><emphasis>
75 <link linkend='faq'>FAQ</link>:</emphasis> 75 <link linkend='faq'>FAQ</link>:</emphasis>
76 This chapter provides answers for commonly asked questions in the Yocto Project 76 This chapter provides answers for commonly asked questions in the Yocto Project
77 development environment.</para></listitem> 77 development environment.</para></listitem>
78 <listitem><para><emphasis> 78 <listitem><para><emphasis>
79 <link linkend='resources'>Contributing to the Yocto Project</link>:</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 80 This chapter provides guidance on how you can contribute back to the Yocto
81 Project.</para></listitem> 81 Project.</para></listitem>
82 </itemizedlist> 82 </itemizedlist>
83 </para> 83 </para>
@@ -88,7 +88,7 @@
88<title>System Requirements</title> 88<title>System Requirements</title>
89 <para> 89 <para>
90 For general Yocto Project system requirements, see the 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 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. 92 in the Yocto Project Quick Start.
93 The remainder of this section provides details on system requirements 93 The remainder of this section provides details on system requirements
94 not covered in the Yocto Project Quick Start. 94 not covered in the Yocto Project Quick Start.
@@ -120,8 +120,8 @@
120 </para> 120 </para>
121 121
122 <note> 122 <note>
123 For additional information on distributions that support the 123 For additional information on distributions that support the
124 Yocto Project, see the 124 Yocto Project, see the
125 <ulink url='&YOCTO_WIKI_URL;/wiki/Distribution_Support'>Distribution Support</ulink> wiki page. 125 <ulink url='&YOCTO_WIKI_URL;/wiki/Distribution_Support'>Distribution Support</ulink> wiki page.
126 </note> 126 </note>
127 </section> 127 </section>
@@ -130,9 +130,9 @@
130 <title>Required Packages for the Host Development System</title> 130 <title>Required Packages for the Host Development System</title>
131 131
132 <para> 132 <para>
133 The list of packages you need on the host development system can 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. 134 be large when covering all build scenarios using the Yocto Project.
135 This section provides required packages by Linux distribution and 135 This section provides required packages by Linux distribution and
136 further categorized by function. 136 further categorized by function.
137 </para> 137 </para>
138 138
@@ -144,7 +144,7 @@
144 given a supported Ubuntu Linux distribution: 144 given a supported Ubuntu Linux distribution:
145 <itemizedlist> 145 <itemizedlist>
146 <listitem><para><emphasis>Essentials:</emphasis> 146 <listitem><para><emphasis>Essentials:</emphasis>
147 Packages needed to build an image on a headless 147 Packages needed to build an image on a headless
148 system: 148 system:
149 <literallayout class='monospaced'> 149 <literallayout class='monospaced'>
150 $ sudo apt-get install &UBUNTU_HOST_PACKAGES_ESSENTIAL; 150 $ sudo apt-get install &UBUNTU_HOST_PACKAGES_ESSENTIAL;
@@ -155,13 +155,13 @@
155 $ sudo apt-get install libsdl1.2-dev xterm 155 $ sudo apt-get install libsdl1.2-dev xterm
156 </literallayout></para></listitem> 156 </literallayout></para></listitem>
157 <listitem><para><emphasis>Documentation:</emphasis> 157 <listitem><para><emphasis>Documentation:</emphasis>
158 Packages needed if you are going to build out the 158 Packages needed if you are going to build out the
159 Yocto Project documentation manuals: 159 Yocto Project documentation manuals:
160 <literallayout class='monospaced'> 160 <literallayout class='monospaced'>
161 $ sudo apt-get install make xsltproc docbook-utils fop 161 $ sudo apt-get install make xsltproc docbook-utils fop
162 </literallayout></para></listitem> 162 </literallayout></para></listitem>
163 <listitem><para><emphasis>ADT Installer Extras:</emphasis> 163 <listitem><para><emphasis>ADT Installer Extras:</emphasis>
164 Packages needed if you are going to be using the 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>: 165 <ulink url='&YOCTO_DOCS_ADT_URL;#using-the-adt-installer'>Application Development Toolkit (ADT) Installer</ulink>:
166 <literallayout class='monospaced'> 166 <literallayout class='monospaced'>
167 $ sudo apt-get install autoconf automake libtool libglib2.0-dev 167 $ sudo apt-get install autoconf automake libtool libglib2.0-dev
@@ -178,7 +178,7 @@
178 given a supported Fedora Linux distribution: 178 given a supported Fedora Linux distribution:
179 <itemizedlist> 179 <itemizedlist>
180 <listitem><para><emphasis>Essentials:</emphasis> 180 <listitem><para><emphasis>Essentials:</emphasis>
181 Packages needed to build an image for a headless 181 Packages needed to build an image for a headless
182 system: 182 system:
183 <literallayout class='monospaced'> 183 <literallayout class='monospaced'>
184 $ sudo yum install &FEDORA_HOST_PACKAGES_ESSENTIAL; 184 $ sudo yum install &FEDORA_HOST_PACKAGES_ESSENTIAL;
@@ -189,14 +189,14 @@
189 $ sudo yum install SDL-devel xterm 189 $ sudo yum install SDL-devel xterm
190 </literallayout></para></listitem> 190 </literallayout></para></listitem>
191 <listitem><para><emphasis>Documentation:</emphasis> 191 <listitem><para><emphasis>Documentation:</emphasis>
192 Packages needed if you are going to build out the 192 Packages needed if you are going to build out the
193 Yocto Project documentation manuals: 193 Yocto Project documentation manuals:
194 <literallayout class='monospaced'> 194 <literallayout class='monospaced'>
195 $ sudo yum install make docbook-style-dsssl docbook-style-xsl \ 195 $ sudo yum install make docbook-style-dsssl docbook-style-xsl \
196 docbook-dtds docbook-utils fop libxslt 196 docbook-dtds docbook-utils fop libxslt
197 </literallayout></para></listitem> 197 </literallayout></para></listitem>
198 <listitem><para><emphasis>ADT Installer Extras:</emphasis> 198 <listitem><para><emphasis>ADT Installer Extras:</emphasis>
199 Packages needed if you are going to be using the 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>: 200 <ulink url='&YOCTO_DOCS_ADT_URL;#using-the-adt-installer'>Application Development Toolkit (ADT) Installer</ulink>:
201 <literallayout class='monospaced'> 201 <literallayout class='monospaced'>
202 $ sudo yum install autoconf automake libtool glib2-devel 202 $ sudo yum install autoconf automake libtool glib2-devel
@@ -213,7 +213,7 @@
213 given a supported OpenSUSE Linux distribution: 213 given a supported OpenSUSE Linux distribution:
214 <itemizedlist> 214 <itemizedlist>
215 <listitem><para><emphasis>Essentials:</emphasis> 215 <listitem><para><emphasis>Essentials:</emphasis>
216 Packages needed to build an image for a headless 216 Packages needed to build an image for a headless
217 system: 217 system:
218 <literallayout class='monospaced'> 218 <literallayout class='monospaced'>
219 $ sudo zypper install &OPENSUSE_HOST_PACKAGES_ESSENTIAL; 219 $ sudo zypper install &OPENSUSE_HOST_PACKAGES_ESSENTIAL;
@@ -224,13 +224,13 @@
224 $ sudo zypper install libSDL-devel xterm 224 $ sudo zypper install libSDL-devel xterm
225 </literallayout></para></listitem> 225 </literallayout></para></listitem>
226 <listitem><para><emphasis>Documentation:</emphasis> 226 <listitem><para><emphasis>Documentation:</emphasis>
227 Packages needed if you are going to build out the 227 Packages needed if you are going to build out the
228 Yocto Project documentation manuals: 228 Yocto Project documentation manuals:
229 <literallayout class='monospaced'> 229 <literallayout class='monospaced'>
230 $ sudo zypper install make fop xsltproc 230 $ sudo zypper install make fop xsltproc
231 </literallayout></para></listitem> 231 </literallayout></para></listitem>
232 <listitem><para><emphasis>ADT Installer Extras:</emphasis> 232 <listitem><para><emphasis>ADT Installer Extras:</emphasis>
233 Packages needed if you are going to be using the 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>: 234 <ulink url='&YOCTO_DOCS_ADT_URL;#using-the-adt-installer'>Application Development Toolkit (ADT) Installer</ulink>:
235 <literallayout class='monospaced'> 235 <literallayout class='monospaced'>
236 $ sudo zypper install autoconf automake libtool glib2-devel 236 $ sudo zypper install autoconf automake libtool glib2-devel
@@ -247,7 +247,7 @@
247 given a supported CentOS Linux distribution: 247 given a supported CentOS Linux distribution:
248 <itemizedlist> 248 <itemizedlist>
249 <listitem><para><emphasis>Essentials:</emphasis> 249 <listitem><para><emphasis>Essentials:</emphasis>
250 Packages needed to build an image for a headless 250 Packages needed to build an image for a headless
251 system: 251 system:
252 <literallayout class='monospaced'> 252 <literallayout class='monospaced'>
253 $ sudo yum -y install &CENTOS_HOST_PACKAGES_ESSENTIAL; 253 $ sudo yum -y install &CENTOS_HOST_PACKAGES_ESSENTIAL;
@@ -258,22 +258,22 @@
258 $ sudo yum -y install SDL-devel xterm 258 $ sudo yum -y install SDL-devel xterm
259 </literallayout></para></listitem> 259 </literallayout></para></listitem>
260 <listitem><para><emphasis>Documentation:</emphasis> 260 <listitem><para><emphasis>Documentation:</emphasis>
261 Packages needed if you are going to build out the 261 Packages needed if you are going to build out the
262 Yocto Project documentation manuals: 262 Yocto Project documentation manuals:
263 <literallayout class='monospaced'> 263 <literallayout class='monospaced'>
264 $ sudo yum -y install make docbook-style-dsssl docbook-style-xsl \ 264 $ sudo yum -y install make docbook-style-dsssl docbook-style-xsl \
265 docbook-dtds docbook-utils fop libxslt 265 docbook-dtds docbook-utils fop libxslt
266 </literallayout></para></listitem> 266 </literallayout></para></listitem>
267 <listitem><para><emphasis>ADT Installer Extras:</emphasis> 267 <listitem><para><emphasis>ADT Installer Extras:</emphasis>
268 Packages needed if you are going to be using the 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>: 269 <ulink url='&YOCTO_DOCS_ADT_URL;#using-the-adt-installer'>Application Development Toolkit (ADT) Installer</ulink>:
270 <literallayout class='monospaced'> 270 <literallayout class='monospaced'>
271 $ sudo yum -y install autoconf automake libtool glib2-devel 271 $ sudo yum -y install autoconf automake libtool glib2-devel
272 </literallayout></para></listitem> 272 </literallayout></para></listitem>
273 </itemizedlist> 273 </itemizedlist>
274 <note>Depending on the CentOS version you are using, other requirements 274 <note>Depending on the CentOS version you are using, other requirements
275 and dependencies might exist. 275 and dependencies might exist.
276 For details, you should look at the CentOS sections on the 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> 277 <ulink url='https://wiki.yoctoproject.org/wiki/Poky/GettingStarted/Dependencies'>Poky/GettingStarted/Dependencies</ulink>
278 wiki page.</note> 278 wiki page.</note>
279 </para> 279 </para>
@@ -284,19 +284,19 @@
284<section id='intro-getit'> 284<section id='intro-getit'>
285 <title>Obtaining the Yocto Project</title> 285 <title>Obtaining the Yocto Project</title>
286 <para> 286 <para>
287 The Yocto Project development team makes the Yocto Project available through a number 287 The Yocto Project development team makes the Yocto Project available through a number
288 of methods: 288 of methods:
289 <itemizedlist> 289 <itemizedlist>
290 <listitem><para><emphasis>Releases:</emphasis> Stable, tested releases are available through 290 <listitem><para><emphasis>Releases:</emphasis> Stable, tested releases are available through
291 <ulink url='&YOCTO_DL_URL;/releases/yocto/'/>.</para></listitem> 291 <ulink url='&YOCTO_DL_URL;/releases/yocto/'/>.</para></listitem>
292 <listitem><para><emphasis>Nightly Builds:</emphasis> These releases are available at 292 <listitem><para><emphasis>Nightly Builds:</emphasis> These releases are available at
293 <ulink url='http://autobuilder.yoctoproject.org/nightly'/>. 293 <ulink url='http://autobuilder.yoctoproject.org/nightly'/>.
294 These builds include Yocto Project releases, meta-toolchain tarball installation scripts, and 294 These builds include Yocto Project releases, meta-toolchain tarball installation scripts, and
295 experimental builds.</para></listitem> 295 experimental builds.</para></listitem>
296 <listitem><para><emphasis>Yocto Project Website:</emphasis> You can find releases 296 <listitem><para><emphasis>Yocto Project Website:</emphasis> You can find releases
297 of the Yocto Project and supported BSPs at the 297 of the Yocto Project and supported BSPs at the
298 <ulink url='&YOCTO_HOME_URL;'>Yocto Project website</ulink>. 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. 299 Along with these downloads, you can find lots of other information at this site.
300 </para></listitem> 300 </para></listitem>
301 </itemizedlist> 301 </itemizedlist>
302 </para> 302 </para>
@@ -305,13 +305,13 @@
305<section id='intro-getit-dev'> 305<section id='intro-getit-dev'>
306 <title>Development Checkouts</title> 306 <title>Development Checkouts</title>
307 <para> 307 <para>
308 Development using the Yocto Project requires a local 308 Development using the Yocto Project requires a local
309 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. 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, 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 311 or by cloning a copy of the upstream
312 <ulink url='&YOCTO_DOCS_DEV_URL;#poky'>Poky</ulink> Git repository. 312 <ulink url='&YOCTO_DOCS_DEV_URL;#poky'>Poky</ulink> Git repository.
313 For information on both these methods, see the 313 For information on both these methods, see the
314 "<ulink url='&YOCTO_DOCS_DEV_URL;#getting-setup'>Getting Setup</ulink>" 314 "<ulink url='&YOCTO_DOCS_DEV_URL;#getting-setup'>Getting Setup</ulink>"
315 section in the Yocto Project Development Manual. 315 section in the Yocto Project Development Manual.
316 </para> 316 </para>
317</section> 317</section>
diff --git a/documentation/poky-ref-manual/migration.xml b/documentation/poky-ref-manual/migration.xml
index b311da65c5..40c570f8ca 100644
--- a/documentation/poky-ref-manual/migration.xml
+++ b/documentation/poky-ref-manual/migration.xml
@@ -6,8 +6,8 @@
6<title>Migrating to a Newer Yocto Project Release</title> 6<title>Migrating to a Newer Yocto Project Release</title>
7 7
8 <para> 8 <para>
9 This chapter provides information you can use to migrate work to a 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 10 newer Yocto Project release. You can find the same information in the
11 release notes for a given release. 11 release notes for a given release.
12 </para> 12 </para>
13 13
@@ -15,7 +15,7 @@
15 <title>Moving to the Yocto Project 1.3 Release</title> 15 <title>Moving to the Yocto Project 1.3 Release</title>
16 16
17 <para> 17 <para>
18 This section provides migration information for moving to the 18 This section provides migration information for moving to the
19 Yocto Project 1.3 Release. 19 Yocto Project 1.3 Release.
20 </para> 20 </para>
21 21
@@ -23,7 +23,7 @@
23 <title>Local Configuration</title> 23 <title>Local Configuration</title>
24 24
25 <para> 25 <para>
26 Differences include changes for 26 Differences include changes for
27 <link linkend='var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></link> 27 <link linkend='var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></link>
28 and <filename>bblayers.conf</filename>. 28 and <filename>bblayers.conf</filename>.
29 </para> 29 </para>
@@ -32,18 +32,18 @@
32 <title>SSTATE_MIRRORS</title> 32 <title>SSTATE_MIRRORS</title>
33 33
34 <para> 34 <para>
35 The shared state cache (sstate-cache) as pointed to by 35 The shared state cache (sstate-cache) as pointed to by
36 <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link> by default 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 37 now has two-character subdirectories to prevent there being an issue with too
38 many files in the same directory. 38 many files in the same directory.
39 Also, native sstate-cache packages will go into a subdirectory named using 39 Also, native sstate-cache packages will go into a subdirectory named using
40 the distro ID string. 40 the distro ID string.
41 If you copy the newly structured sstate-cache to a mirror location 41 If you copy the newly structured sstate-cache to a mirror location
42 (either local or remote) and then point to it in 42 (either local or remote) and then point to it in
43 <link linkend='var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></link>, 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 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 45 the path used by BitBake before the mirror substitution is
46 appended to the path used to access the mirror. 46 appended to the path used to access the mirror.
47 Here is an example: 47 Here is an example:
48 <literallayout class='monospaced'> 48 <literallayout class='monospaced'>
49 SSTATE_MIRRORS = "file://.* http://someserver.tld/share/sstate/PATH" 49 SSTATE_MIRRORS = "file://.* http://someserver.tld/share/sstate/PATH"
@@ -55,14 +55,14 @@
55 <title>bblayers.conf</title> 55 <title>bblayers.conf</title>
56 56
57 <para> 57 <para>
58 The <filename>meta-yocto</filename> layer has been split into 58 The <filename>meta-yocto</filename> layer has been split into
59 two parts: <filename>meta-yocto</filename> and 59 two parts: <filename>meta-yocto</filename> and
60 <filename>meta-yocto-bsp</filename>, corresponding to the 60 <filename>meta-yocto-bsp</filename>, corresponding to the
61 Poky reference distro configuration and the reference 61 Poky reference distro configuration and the reference
62 hardware Board Support Packages (BSPs), respectively. 62 hardware Board Support Packages (BSPs), respectively.
63 When running BitBake or Hob for the first time after upgrading, 63 When running BitBake or Hob for the first time after upgrading,
64 your <filename>conf/bblayers.conf</filename> file will be 64 your <filename>conf/bblayers.conf</filename> file will be
65 updated to handle this change and you will be asked to 65 updated to handle this change and you will be asked to
66 re-run/restart for the changes to take effect. 66 re-run/restart for the changes to take effect.
67 </para> 67 </para>
68 </section> 68 </section>
@@ -87,16 +87,16 @@
87 <title>Python Function Whitespace</title> 87 <title>Python Function Whitespace</title>
88 88
89 <para> 89 <para>
90 All Python functions must now use four spaces for indentation. 90 All Python functions must now use four spaces for indentation.
91 Previously, an inconsistent mix of spaces and tabs existed, 91 Previously, an inconsistent mix of spaces and tabs existed,
92 which made extending these functions using 92 which made extending these functions using
93 <filename>_append</filename> or <filename>_prepend</filename> 93 <filename>_append</filename> or <filename>_prepend</filename>
94 complicated given that Python treats whitespace as 94 complicated given that Python treats whitespace as
95 syntactically significant. 95 syntactically significant.
96 If you are defining or extending any Python functions (e.g. 96 If you are defining or extending any Python functions (e.g.
97 <filename>populate_packages</filename>, <filename>do_unpack</filename>, 97 <filename>populate_packages</filename>, <filename>do_unpack</filename>,
98 <filename>do_patch</filename> and so forth) in custom recipes 98 <filename>do_patch</filename> and so forth) in custom recipes
99 or classes, you need to ensure you are using consistent 99 or classes, you need to ensure you are using consistent
100 four-space indentation. 100 four-space indentation.
101 </para> 101 </para>
102 </section> 102 </section>
@@ -105,7 +105,7 @@
105 <title>proto= in SRC_URI</title> 105 <title>proto= in SRC_URI</title>
106 106
107 <para> 107 <para>
108 Any use of <filename>proto=</filename> in 108 Any use of <filename>proto=</filename> in
109 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link> 109 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
110 needs to be changed to <filename>protocol=</filename>. 110 needs to be changed to <filename>protocol=</filename>.
111 In particular, this applies to the following URIs: 111 In particular, this applies to the following URIs:
@@ -125,11 +125,11 @@
125 125
126 <para> 126 <para>
127 The suffix <filename>nativesdk</filename> is now implemented 127 The suffix <filename>nativesdk</filename> is now implemented
128 as a prefix, which simplifies a lot of the packaging code for 128 as a prefix, which simplifies a lot of the packaging code for
129 <filename>nativesdk</filename> recipes. 129 <filename>nativesdk</filename> recipes.
130 All custom <filename>nativesdk</filename> recipes and any 130 All custom <filename>nativesdk</filename> recipes and any
131 references need to be updated to use 131 references need to be updated to use
132 <filename>nativesdk-*</filename> instead of 132 <filename>nativesdk-*</filename> instead of
133 <filename>*-nativesdk</filename>. 133 <filename>*-nativesdk</filename>.
134 </para> 134 </para>
135 </section> 135 </section>
@@ -138,25 +138,25 @@
138 <title>Task Recipes</title> 138 <title>Task Recipes</title>
139 139
140 <para> 140 <para>
141 "Task" recipes are now known as "Package groups" and have 141 "Task" recipes are now known as "Package groups" and have
142 been renamed from <filename>task-*.bb</filename> to 142 been renamed from <filename>task-*.bb</filename> to
143 <filename>packagegroup-*.bb</filename>. 143 <filename>packagegroup-*.bb</filename>.
144 Existing references to the previous <filename>task-*</filename> 144 Existing references to the previous <filename>task-*</filename>
145 names should work in most cases as there is an automatic 145 names should work in most cases as there is an automatic
146 upgrade path for most packages. 146 upgrade path for most packages.
147 However, you should update references in your own recipes and 147 However, you should update references in your own recipes and
148 configurations as they could be removed in future releases. 148 configurations as they could be removed in future releases.
149 You should also rename any custom <filename>task-*</filename> 149 You should also rename any custom <filename>task-*</filename>
150 recipes to <filename>packagegroup-*</filename>, and change 150 recipes to <filename>packagegroup-*</filename>, and change
151 them to inherit <filename>packagegroup</filename> instead of 151 them to inherit <filename>packagegroup</filename> instead of
152 <filename>task</filename>, as well as taking the opportunity 152 <filename>task</filename>, as well as taking the opportunity
153 to remove anything now handled by 153 to remove anything now handled by
154 <filename>packagegroup.bbclass</filename>, such as providing 154 <filename>packagegroup.bbclass</filename>, such as providing
155 <filename>-dev</filename> and <filename>-dbg</filename> 155 <filename>-dev</filename> and <filename>-dbg</filename>
156 packages, setting 156 packages, setting
157 <link linkend='var-LIC_FILES_CHKSUM'><filename>LIC_FILES_CHKSUM</filename></link>, 157 <link linkend='var-LIC_FILES_CHKSUM'><filename>LIC_FILES_CHKSUM</filename></link>,
158 and so forth. 158 and so forth.
159 See the 159 See the
160 "<link linkend='ref-classes-packagegroup'>Package Groups - packagegroup.bbclass</link>" 160 "<link linkend='ref-classes-packagegroup'>Package Groups - packagegroup.bbclass</link>"
161 section for further details. 161 section for further details.
162 </para> 162 </para>
@@ -166,13 +166,13 @@
166 <title>IMAGE_FEATURES</title> 166 <title>IMAGE_FEATURES</title>
167 167
168 <para> 168 <para>
169 Image recipes that previously included "apps-console-core" 169 Image recipes that previously included "apps-console-core"
170 in <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link> 170 in <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>
171 should now include "splash" instead to enable the boot-up 171 should now include "splash" instead to enable the boot-up
172 splash screen. 172 splash screen.
173 Retaining "apps-console-core" will still include the splash 173 Retaining "apps-console-core" will still include the splash
174 screen generates a warning. 174 screen generates a warning.
175 The "apps-x11-core" and "apps-x11-games" 175 The "apps-x11-core" and "apps-x11-games"
176 <filename>IMAGE_FEATURES</filename> features have been removed. 176 <filename>IMAGE_FEATURES</filename> features have been removed.
177 </para> 177 </para>
178 </section> 178 </section>
@@ -181,55 +181,55 @@
181 <title>Removed Recipes</title> 181 <title>Removed Recipes</title>
182 182
183 <para> 183 <para>
184 The following recipes have been removed. 184 The following recipes have been removed.
185 For most of them, it is unlikely that you would have any 185 For most of them, it is unlikely that you would have any
186 references to them in your own metadata. 186 references to them in your own metadata.
187 However, you should check your metadata against this list to be sure: 187 However, you should check your metadata against this list to be sure:
188 <itemizedlist> 188 <itemizedlist>
189 <listitem><para><emphasis><filename>libx11-trim</filename></emphasis>: 189 <listitem><para><emphasis><filename>libx11-trim</filename></emphasis>:
190 Replaced by <filename>libx11</filename>, which has a negligible 190 Replaced by <filename>libx11</filename>, which has a negligible
191 size difference with modern Xorg.</para></listitem> 191 size difference with modern Xorg.</para></listitem>
192 <listitem><para><emphasis><filename>xserver-xorg-lite</filename></emphasis>: 192 <listitem><para><emphasis><filename>xserver-xorg-lite</filename></emphasis>:
193 Use <filename>xserver-xorg</filename>, which has a negligible 193 Use <filename>xserver-xorg</filename>, which has a negligible
194 size difference when DRI and GLX modules are not installed.</para></listitem> 194 size difference when DRI and GLX modules are not installed.</para></listitem>
195 <listitem><para><emphasis><filename>xserver-kdrive</filename></emphasis>: 195 <listitem><para><emphasis><filename>xserver-kdrive</filename></emphasis>:
196 Effectively unmaintained for many years.</para></listitem> 196 Effectively unmaintained for many years.</para></listitem>
197 <listitem><para><emphasis><filename>mesa-xlib</filename></emphasis>: 197 <listitem><para><emphasis><filename>mesa-xlib</filename></emphasis>:
198 No longer serves any purpose.</para></listitem> 198 No longer serves any purpose.</para></listitem>
199 <listitem><para><emphasis><filename>galago</filename></emphasis>: 199 <listitem><para><emphasis><filename>galago</filename></emphasis>:
200 Replaced by telepathy.</para></listitem> 200 Replaced by telepathy.</para></listitem>
201 <listitem><para><emphasis><filename>gail</filename></emphasis>: 201 <listitem><para><emphasis><filename>gail</filename></emphasis>:
202 Functionality was integrated into GTK+ 2.13.</para></listitem> 202 Functionality was integrated into GTK+ 2.13.</para></listitem>
203 <listitem><para><emphasis><filename>eggdbus</filename></emphasis>: 203 <listitem><para><emphasis><filename>eggdbus</filename></emphasis>:
204 No longer needed.</para></listitem> 204 No longer needed.</para></listitem>
205 <listitem><para><emphasis><filename>gcc-*-intermediate</filename></emphasis>: 205 <listitem><para><emphasis><filename>gcc-*-intermediate</filename></emphasis>:
206 The build has been restructured to avoid the need for 206 The build has been restructured to avoid the need for
207 this step.</para></listitem> 207 this step.</para></listitem>
208 <listitem><para><emphasis><filename>libgsmd</filename></emphasis>: 208 <listitem><para><emphasis><filename>libgsmd</filename></emphasis>:
209 Unmaintained for many years. 209 Unmaintained for many years.
210 Functionality now provided by 210 Functionality now provided by
211 <filename>ofono</filename> instead.</para></listitem> 211 <filename>ofono</filename> instead.</para></listitem>
212 <listitem><para><emphasis>contacts, dates, tasks, eds-tools</emphasis>: 212 <listitem><para><emphasis>contacts, dates, tasks, eds-tools</emphasis>:
213 Largely unmaintained PIM application suite. 213 Largely unmaintained PIM application suite.
214 It has been moved to <filename>meta-gnome</filename> 214 It has been moved to <filename>meta-gnome</filename>
215 in <filename>meta-openembedded</filename>.</para></listitem> 215 in <filename>meta-openembedded</filename>.</para></listitem>
216 </itemizedlist> 216 </itemizedlist>
217 In addition to the previously listed changes, the 217 In addition to the previously listed changes, the
218 <filename>meta-demoapps</filename> directory has also been removed 218 <filename>meta-demoapps</filename> directory has also been removed
219 because the recipes in it were not being maintained and many 219 because the recipes in it were not being maintained and many
220 had become obsolete or broken. 220 had become obsolete or broken.
221 Additionally, these recipes were not parsed in the default configuration. 221 Additionally, these recipes were not parsed in the default configuration.
222 Many of these recipes are already provided in an updated and 222 Many of these recipes are already provided in an updated and
223 maintained form within OpenEmbedded community layers such as 223 maintained form within OpenEmbedded community layers such as
224 <filename>meta-oe</filename> and <filename>meta-gnome</filename>. 224 <filename>meta-oe</filename> and <filename>meta-gnome</filename>.
225 For the remainder, you can now find them in the 225 For the remainder, you can now find them in the
226 <filename>meta-extras</filename> repository, which is in the 226 <filename>meta-extras</filename> repository, which is in the
227 Yocto Project source repositories. 227 Yocto Project source repositories.
228 </para> 228 </para>
229 </section> 229 </section>
230 </section> 230 </section>
231</section> 231</section>
232</chapter> 232</chapter>
233<!-- 233<!--
234vim: expandtab tw=80 ts=4 234vim: expandtab tw=80 ts=4
235--> 235-->
diff --git a/documentation/poky-ref-manual/poky-ref-manual.xml b/documentation/poky-ref-manual/poky-ref-manual.xml
index 51f5e2d9f4..2fcc68d88c 100644
--- a/documentation/poky-ref-manual/poky-ref-manual.xml
+++ b/documentation/poky-ref-manual/poky-ref-manual.xml
@@ -2,18 +2,18 @@
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" 2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > 3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4 4
5<book id='poky-ref-manual' lang='en' 5<book id='poky-ref-manual' lang='en'
6 xmlns:xi="http://www.w3.org/2003/XInclude" 6 xmlns:xi="http://www.w3.org/2003/XInclude"
7 xmlns="http://docbook.org/ns/docbook" 7 xmlns="http://docbook.org/ns/docbook"
8 > 8 >
9 <bookinfo> 9 <bookinfo>
10 10
11 <mediaobject> 11 <mediaobject>
12 <imageobject> 12 <imageobject>
13 <imagedata fileref='figures/poky-title.png' 13 <imagedata fileref='figures/poky-title.png'
14 format='SVG' 14 format='SVG'
15 align='left' scalefit='1' width='100%'/> 15 align='left' scalefit='1' width='100%'/>
16 </imageobject> 16 </imageobject>
17 </mediaobject> 17 </mediaobject>
18 18
19 <title></title> 19 <title></title>
@@ -74,7 +74,7 @@
74 74
75 <legalnotice> 75 <legalnotice>
76 <para> 76 <para>
77 Permission is granted to copy, distribute and/or modify this document under 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. 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> 79 </para>
80 <note> 80 <note>
@@ -116,10 +116,10 @@
116 116
117<!-- <index id='index'> 117<!-- <index id='index'>
118 <title>Index</title> 118 <title>Index</title>
119 </index> 119 </index>
120--> 120-->
121 121
122</book> 122</book>
123<!-- 123<!--
124vim: expandtab tw=80 ts=4 124vim: expandtab tw=80 ts=4
125--> 125-->
diff --git a/documentation/poky-ref-manual/ref-bitbake.xml b/documentation/poky-ref-manual/ref-bitbake.xml
index b81f12fb7a..b641d5cff9 100644
--- a/documentation/poky-ref-manual/ref-bitbake.xml
+++ b/documentation/poky-ref-manual/ref-bitbake.xml
@@ -14,15 +14,15 @@
14 $ bitbake core-image-sato 14 $ bitbake core-image-sato
15 </literallayout> 15 </literallayout>
16 </para> 16 </para>
17 17
18 <para> 18 <para>
19 This chapter provides an overview of what happens behind the scenes from BitBake's perspective. 19 This chapter provides an overview of what happens behind the scenes from BitBake's perspective.
20 </para> 20 </para>
21 21
22 <note> 22 <note>
23 BitBake strives to be a generic "task" executor that is capable of handling complex dependency relationships. 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. 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 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. 26 that consists of variables in a certain format that get passed to the tasks.
27 </note> 27 </note>
28 28
@@ -30,85 +30,85 @@
30 <title>Parsing</title> 30 <title>Parsing</title>
31 31
32 <para> 32 <para>
33 BitBake parses configuration files, classes, and <filename>.bb</filename> files. 33 BitBake parses configuration files, classes, and <filename>.bb</filename> files.
34 </para> 34 </para>
35 35
36 <para> 36 <para>
37 The first thing BitBake does is look for the <filename>bitbake.conf</filename> file. 37 The first thing BitBake does is look for the <filename>bitbake.conf</filename> file.
38 This file resides in the 38 This file resides in the
39 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> 39 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
40 within the <filename>meta/conf/</filename> directory. 40 within the <filename>meta/conf/</filename> directory.
41 BitBake finds it by examining its 41 BitBake finds it by examining its
42 <link linkend='var-BBPATH'><filename>BBPATH</filename></link> environment 42 <link linkend='var-BBPATH'><filename>BBPATH</filename></link> environment
43 variable and looking for the <filename>meta/conf/</filename> 43 variable and looking for the <filename>meta/conf/</filename>
44 directory. 44 directory.
45 </para> 45 </para>
46 46
47 <para> 47 <para>
48 The <filename>bitbake.conf</filename> file lists other configuration 48 The <filename>bitbake.conf</filename> file lists other configuration
49 files to include from a <filename>conf/</filename> 49 files to include from a <filename>conf/</filename>
50 directory below the directories listed in <filename>BBPATH</filename>. 50 directory below the directories listed in <filename>BBPATH</filename>.
51 In general, the most important configuration file from a user's perspective 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 52 is <filename>local.conf</filename>, which contains a user's customized
53 settings for the OpenEmbedded build environment. 53 settings for the OpenEmbedded build environment.
54 Other notable configuration files are the distribution 54 Other notable configuration files are the distribution
55 configuration file (set by the 55 configuration file (set by the
56 <filename><link linkend='var-DISTRO'>DISTRO</link></filename> variable) 56 <filename><link linkend='var-DISTRO'>DISTRO</link></filename> variable)
57 and the machine configuration file 57 and the machine configuration file
58 (set by the 58 (set by the
59 <filename><link linkend='var-MACHINE'>MACHINE</link></filename> variable). 59 <filename><link linkend='var-MACHINE'>MACHINE</link></filename> variable).
60 The <filename>DISTRO</filename> and <filename>MACHINE</filename> BitBake environment 60 The <filename>DISTRO</filename> and <filename>MACHINE</filename> BitBake environment
61 variables are both usually set in 61 variables are both usually set in
62 the <filename>local.conf</filename> file. 62 the <filename>local.conf</filename> file.
63 Valid distribution 63 Valid distribution
64 configuration files are available in the <filename>meta/conf/distro/</filename> directory 64 configuration files are available in the <filename>meta/conf/distro/</filename> directory
65 and valid machine configuration 65 and valid machine configuration
66 files in the <filename>meta/conf/machine/</filename> directory. 66 files in the <filename>meta/conf/machine/</filename> directory.
67 Within the <filename>meta/conf/machine/include/</filename> 67 Within the <filename>meta/conf/machine/include/</filename>
68 directory are various <filename>tune-*.inc</filename> configuration files that provide common 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. 69 "tuning" settings specific to and shared between particular architectures and machines.
70 </para> 70 </para>
71 71
72 <para> 72 <para>
73 After the parsing of the configuration files, some standard classes are included. 73 After the parsing of the configuration files, some standard classes are included.
74 The <filename>base.bbclass</filename> file is always included. 74 The <filename>base.bbclass</filename> file is always included.
75 Other classes that are specified in the configuration using the 75 Other classes that are specified in the configuration using the
76 <filename><link linkend='var-INHERIT'>INHERIT</link></filename> 76 <filename><link linkend='var-INHERIT'>INHERIT</link></filename>
77 variable are also included. 77 variable are also included.
78 Class files are searched for in a <filename>classes</filename> subdirectory 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 79 under the paths in <filename>BBPATH</filename> in the same way as
80 configuration files. 80 configuration files.
81 </para> 81 </para>
82 82
83 <para> 83 <para>
84 After classes are included, the variable 84 After classes are included, the variable
85 <filename><link linkend='var-BBFILES'>BBFILES</link></filename> 85 <filename><link linkend='var-BBFILES'>BBFILES</link></filename>
86 is set, usually in 86 is set, usually in
87 <filename>local.conf</filename>, and defines the list of places to search for 87 <filename>local.conf</filename>, and defines the list of places to search for
88 <filename>.bb</filename> files. 88 <filename>.bb</filename> files.
89 By default, the <filename>BBFILES</filename> variable specifies the 89 By default, the <filename>BBFILES</filename> variable specifies the
90 <filename>meta/recipes-*/</filename> directory within Poky. 90 <filename>meta/recipes-*/</filename> directory within Poky.
91 Adding extra content to <filename>BBFILES</filename> is best achieved through the use of 91 Adding extra content to <filename>BBFILES</filename> is best achieved through the use of
92 BitBake layers as described in the 92 BitBake layers as described in the
93 "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and 93 "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and
94 Creating Layers</ulink>" section of the Yocto Project Development Manual. 94 Creating Layers</ulink>" section of the Yocto Project Development Manual.
95 </para> 95 </para>
96 96
97 <para> 97 <para>
98 BitBake parses each <filename>.bb</filename> file in <filename>BBFILES</filename> and 98 BitBake parses each <filename>.bb</filename> file in <filename>BBFILES</filename> and
99 stores the values of various variables. 99 stores the values of various variables.
100 In summary, for each <filename>.bb</filename> 100 In summary, for each <filename>.bb</filename>
101 file the configuration plus the base class of variables are set, followed 101 file the configuration plus the base class of variables are set, followed
102 by the data in the <filename>.bb</filename> file 102 by the data in the <filename>.bb</filename> file
103 itself, followed by any inherit commands that 103 itself, followed by any inherit commands that
104 <filename>.bb</filename> file might contain. 104 <filename>.bb</filename> file might contain.
105 </para> 105 </para>
106 106
107 <para> 107 <para>
108 Because parsing <filename>.bb</filename> files is a time 108 Because parsing <filename>.bb</filename> files is a time
109 consuming process, a cache is kept to speed up subsequent parsing. 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> 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, 111 file itself changes, or if the timestamps of any of the include,
112 configuration or class files the <filename>.bb</filename> 112 configuration or class files the <filename>.bb</filename>
113 file depends on changes. 113 file depends on changes.
114 </para> 114 </para>
@@ -118,22 +118,22 @@
118 <title>Preferences and Providers</title> 118 <title>Preferences and Providers</title>
119 119
120 <para> 120 <para>
121 Once all the <filename>.bb</filename> files have been 121 Once all the <filename>.bb</filename> files have been
122 parsed, BitBake starts to build the target (<filename>core-image-sato</filename> 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. 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 124 Once a provider is selected, BitBake resolves all the dependencies for
125 the target. 125 the target.
126 In the case of <filename>core-image-sato</filename>, it would lead to 126 In the case of <filename>core-image-sato</filename>, it would lead to
127 <filename>packagegroup-core-x11-sato</filename>, 127 <filename>packagegroup-core-x11-sato</filename>,
128 which in turn leads to recipes like <filename>matchbox-terminal</filename>, 128 which in turn leads to recipes like <filename>matchbox-terminal</filename>,
129 <filename>pcmanfm</filename> and <filename>gthumb</filename>. 129 <filename>pcmanfm</filename> and <filename>gthumb</filename>.
130 These recipes in turn depend on <filename>eglibc</filename> and the toolchain. 130 These recipes in turn depend on <filename>eglibc</filename> and the toolchain.
131 </para> 131 </para>
132 132
133 <para> 133 <para>
134 Sometimes a target might have multiple providers. 134 Sometimes a target might have multiple providers.
135 A common example is "virtual/kernel", which is provided by each kernel package. 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 136 Each machine often selects the best kernel provider by using a line similar to the
137 following in the machine configuration file: 137 following in the machine configuration file:
138 </para> 138 </para>
139 139
@@ -142,25 +142,25 @@
142 </literallayout> 142 </literallayout>
143 143
144 <para> 144 <para>
145 The default <filename><link linkend='var-PREFERRED_PROVIDER'>PREFERRED_PROVIDER</link></filename> 145 The default <filename><link linkend='var-PREFERRED_PROVIDER'>PREFERRED_PROVIDER</link></filename>
146 is the provider with the same name as the target. 146 is the provider with the same name as the target.
147 </para> 147 </para>
148 148
149 <para> 149 <para>
150 Understanding how providers are chosen is made complicated by the fact 150 Understanding how providers are chosen is made complicated by the fact
151 that multiple versions might exist. 151 that multiple versions might exist.
152 BitBake defaults to the highest version of a provider. 152 BitBake defaults to the highest version of a provider.
153 Version comparisons are made using the same method as Debian. 153 Version comparisons are made using the same method as Debian.
154 You can use the 154 You can use the
155 <filename><link linkend='var-PREFERRED_VERSION'>PREFERRED_VERSION</link></filename> 155 <filename><link linkend='var-PREFERRED_VERSION'>PREFERRED_VERSION</link></filename>
156 variable to specify a particular version (usually in the distro configuration). 156 variable to specify a particular version (usually in the distro configuration).
157 You can influence the order by using the 157 You can influence the order by using the
158 <filename><link linkend='var-DEFAULT_PREFERENCE'>DEFAULT_PREFERENCE</link></filename> 158 <filename><link linkend='var-DEFAULT_PREFERENCE'>DEFAULT_PREFERENCE</link></filename>
159 variable. 159 variable.
160 By default, files have a preference of "0". 160 By default, files have a preference of "0".
161 Setting the <filename>DEFAULT_PREFERENCE</filename> to "-1" makes the 161 Setting the <filename>DEFAULT_PREFERENCE</filename> to "-1" makes the
162 package unlikely to be used unless it is explicitly referenced. 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. 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. 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 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. 166 versions until they have undergone sufficient testing to be considered stable.
@@ -175,23 +175,23 @@
175 <title>Dependencies</title> 175 <title>Dependencies</title>
176 176
177 <para> 177 <para>
178 Each target BitBake builds consists of multiple tasks such as 178 Each target BitBake builds consists of multiple tasks such as
179 <filename>fetch</filename>, <filename>unpack</filename>, 179 <filename>fetch</filename>, <filename>unpack</filename>,
180 <filename>patch</filename>, <filename>configure</filename>, 180 <filename>patch</filename>, <filename>configure</filename>,
181 and <filename>compile</filename>. 181 and <filename>compile</filename>.
182 For best performance on multi-core systems, BitBake considers each task as an independent 182 For best performance on multi-core systems, BitBake considers each task as an independent
183 entity with its own set of dependencies. 183 entity with its own set of dependencies.
184 </para> 184 </para>
185 185
186 <para> 186 <para>
187 Dependencies are defined through several variables. 187 Dependencies are defined through several variables.
188 You can find information about variables BitBake uses in the BitBake documentation, 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 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>. 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 191 At a basic level, it is sufficient to know that BitBake uses the
192 <filename><link linkend='var-DEPENDS'>DEPENDS</link></filename> and 192 <filename><link linkend='var-DEPENDS'>DEPENDS</link></filename> and
193 <filename><link linkend='var-RDEPENDS'>RDEPENDS</link></filename> variables when 193 <filename><link linkend='var-RDEPENDS'>RDEPENDS</link></filename> variables when
194 calculating dependencies. 194 calculating dependencies.
195 </para> 195 </para>
196 </section> 196 </section>
197 197
@@ -199,40 +199,40 @@
199 <title>The Task List</title> 199 <title>The Task List</title>
200 200
201 <para> 201 <para>
202 Based on the generated list of providers and the dependency information, 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 203 BitBake can now calculate exactly what tasks it needs to run and in what
204 order it needs to run them. 204 order it needs to run them.
205 The build now starts with BitBake forking off threads up to the limit set in the 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. 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, 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 208 those tasks have all their dependencies met, and the thread threshold has not been
209 exceeded. 209 exceeded.
210 </para> 210 </para>
211 211
212 <para> 212 <para>
213 It is worth noting that you can greatly speed up the build time by properly setting 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. 214 the <filename>BB_NUMBER_THREADS</filename> variable.
215 See the 215 See the
216 "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>" 216 "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>"
217 section in the Yocto Project Quick Start for more information. 217 section in the Yocto Project Quick Start for more information.
218 </para> 218 </para>
219 219
220 <para> 220 <para>
221 As each task completes, a timestamp is written to the directory specified by the 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 (usually 222 <filename><link linkend='var-STAMP'>STAMP</link></filename> variable (usually
223 <filename>build/tmp/stamps/*/</filename>). 223 <filename>build/tmp/stamps/*/</filename>).
224 On subsequent runs, BitBake looks at the <filename>/build/tmp/stamps</filename> 224 On subsequent runs, BitBake looks at the <filename>/build/tmp/stamps</filename>
225 directory and does not rerun 225 directory and does not rerun
226 tasks that are already completed unless a timestamp is found to be invalid. 226 tasks that are already completed unless a timestamp is found to be invalid.
227 Currently, invalid timestamps are only considered on a per 227 Currently, invalid timestamps are only considered on a per
228 <filename>.bb</filename> file basis. 228 <filename>.bb</filename> file basis.
229 So, for example, if the configure stamp has a timestamp greater than the 229 So, for example, if the configure stamp has a timestamp greater than the
230 compile timestamp for a given target, then the compile task would rerun. 230 compile timestamp for a given target, then the compile task would rerun.
231 Running the compile task again, however, has no effect on other providers 231 Running the compile task again, however, has no effect on other providers
232 that depend on that target. 232 that depend on that target.
233 This behavior could change or become configurable in future versions of BitBake. 233 This behavior could change or become configurable in future versions of BitBake.
234 </para> 234 </para>
235 235
236 <note> 236 <note>
237 Some tasks are marked as "nostamp" tasks. 237 Some tasks are marked as "nostamp" tasks.
238 No timestamp file is created when these tasks are run. 238 No timestamp file is created when these tasks are run.
@@ -245,52 +245,52 @@
245 245
246 <para> 246 <para>
247 Tasks can either be a shell task or a Python task. 247 Tasks can either be a shell task or a Python task.
248 For shell tasks, BitBake writes a shell script to 248 For shell tasks, BitBake writes a shell script to
249 <filename>${WORKDIR}/temp/run.do_taskname.pid</filename> and then executes the script. 249 <filename>${WORKDIR}/temp/run.do_taskname.pid</filename> and then executes the script.
250 The generated shell script contains all the exported variables, and the shell functions 250 The generated shell script contains all the exported variables, and the shell functions
251 with all variables expanded. 251 with all variables expanded.
252 Output from the shell script goes to the file <filename>${WORKDIR}/temp/log.do_taskname.pid</filename>. 252 Output from the shell script goes to the file <filename>${WORKDIR}/temp/log.do_taskname.pid</filename>.
253 Looking at the expanded shell functions in the run file and the output in the log files 253 Looking at the expanded shell functions in the run file and the output in the log files
254 is a useful debugging technique. 254 is a useful debugging technique.
255 </para> 255 </para>
256 256
257 <para> 257 <para>
258 For Python tasks, BitBake executes the task internally and logs information to the 258 For Python tasks, BitBake executes the task internally and logs information to the
259 controlling terminal. 259 controlling terminal.
260 Future versions of BitBake will write the functions to files similar to the way 260 Future versions of BitBake will write the functions to files similar to the way
261 shell tasks are handled. 261 shell tasks are handled.
262 Logging will be handled in way similar to shell tasks as well. 262 Logging will be handled in way similar to shell tasks as well.
263 </para> 263 </para>
264 264
265 <para> 265 <para>
266 Once all the tasks have been completed BitBake exits. 266 Once all the tasks have been completed BitBake exits.
267 </para> 267 </para>
268 268
269 <para> 269 <para>
270 When running a task, BitBake tightly controls the execution environment 270 When running a task, BitBake tightly controls the execution environment
271 of the build tasks to make sure unwanted contamination from the build machine 271 of the build tasks to make sure unwanted contamination from the build machine
272 cannot influence the build. 272 cannot influence the build.
273 Consequently, if you do want something to get passed into the build 273 Consequently, if you do want something to get passed into the build
274 task's environment, you must take a few steps: 274 task's environment, you must take a few steps:
275 <orderedlist> 275 <orderedlist>
276 <listitem><para>Tell BitBake to load what you want from the environment 276 <listitem><para>Tell BitBake to load what you want from the environment
277 into the data store. 277 into the data store.
278 You can do so through the <filename>BB_ENV_EXTRAWHITE</filename> 278 You can do so through the <filename>BB_ENV_EXTRAWHITE</filename>
279 variable. 279 variable.
280 For example, assume you want to prevent the build system from 280 For example, assume you want to prevent the build system from
281 accessing your <filename>$HOME/.ccache</filename> directory. 281 accessing your <filename>$HOME/.ccache</filename> directory.
282 The following command tells BitBake to load 282 The following command tells BitBake to load
283 <filename>CCACHE_DIR</filename> from the environment into the data 283 <filename>CCACHE_DIR</filename> from the environment into the data
284 store: 284 store:
285 <literallayout class='monospaced'> 285 <literallayout class='monospaced'>
286 export BB_ENV_EXTRAWHITE="$BB_ENV_EXTRAWHITE CCACHE_DIR" 286 export BB_ENV_EXTRAWHITE="$BB_ENV_EXTRAWHITE CCACHE_DIR"
287 </literallayout></para></listitem> 287 </literallayout></para></listitem>
288 <listitem><para>Tell BitBake to export what you have loaded into the 288 <listitem><para>Tell BitBake to export what you have loaded into the
289 environment store to the task environment of every running task. 289 environment store to the task environment of every running task.
290 Loading something from the environment into the data store 290 Loading something from the environment into the data store
291 (previous step) only makes it available in the datastore. 291 (previous step) only makes it available in the datastore.
292 To export it to the task environment of every running task, 292 To export it to the task environment of every running task,
293 use a command similar to the following in your 293 use a command similar to the following in your
294 <filename>local.conf</filename> or distro configuration file: 294 <filename>local.conf</filename> or distro configuration file:
295 <literallayout class='monospaced'> 295 <literallayout class='monospaced'>
296 export CCACHE_DIR 296 export CCACHE_DIR
@@ -301,8 +301,8 @@
301 <note> 301 <note>
302 A side effect of the previous steps is that BitBake records the variable 302 A side effect of the previous steps is that BitBake records the variable
303 as a dependency of the build process in things like the shared state 303 as a dependency of the build process in things like the shared state
304 checksums. 304 checksums.
305 If doing so results in unnecessary rebuilds of tasks, you can whitelist the 305 If doing so results in unnecessary rebuilds of tasks, you can whitelist the
306 variable so that the shared state code ignores the dependency when it creates 306 variable so that the shared state code ignores the dependency when it creates
307 checksums. 307 checksums.
308 For information on this process, see the <filename>BB_HASHBASE_WHITELIST</filename> 308 For information on this process, see the <filename>BB_HASHBASE_WHITELIST</filename>
@@ -383,38 +383,38 @@ Options:
383 <title>Fetchers</title> 383 <title>Fetchers</title>
384 384
385 <para> 385 <para>
386 BitBake also contains a set of "fetcher" modules that allow 386 BitBake also contains a set of "fetcher" modules that allow
387 retrieval of source code from various types of sources. 387 retrieval of source code from various types of sources.
388 For example, BitBake can get source code from a disk with the metadata, from websites, 388 For example, BitBake can get source code from a disk with the metadata, from websites,
389 from remote shell accounts or from Source Code Management (SCM) systems 389 from remote shell accounts or from Source Code Management (SCM) systems
390 like <filename>cvs/subversion/git</filename>. 390 like <filename>cvs/subversion/git</filename>.
391 </para> 391 </para>
392 392
393 <para> 393 <para>
394 Fetchers are usually triggered by entries in 394 Fetchers are usually triggered by entries in
395 <filename><link linkend='var-SRC_URI'>SRC_URI</link></filename>. 395 <filename><link linkend='var-SRC_URI'>SRC_URI</link></filename>.
396 You can find information about the options and formats of entries for specific 396 You can find information about the options and formats of entries for specific
397 fetchers in the BitBake manual located in the 397 fetchers in the BitBake manual located in the
398 <filename>bitbake/doc/manual</filename> directory of the 398 <filename>bitbake/doc/manual</filename> directory of the
399 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. 399 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
400 </para> 400 </para>
401 401
402 <para> 402 <para>
403 One useful feature for certain Source Code Manager (SCM) fetchers is the ability to 403 One useful feature for certain Source Code Manager (SCM) fetchers is the ability to
404 "auto-update" when the upstream SCM changes version. 404 "auto-update" when the upstream SCM changes version.
405 Since this ability requires certain functionality from the SCM, not all 405 Since this ability requires certain functionality from the SCM, not all
406 systems support it. 406 systems support it.
407 Currently Subversion, Bazaar and to a limited extent, Git support the ability to "auto-update". 407 Currently Subversion, Bazaar and to a limited extent, Git support the ability to "auto-update".
408 This feature works using the <filename><link linkend='var-SRCREV'>SRCREV</link></filename> 408 This feature works using the <filename><link linkend='var-SRCREV'>SRCREV</link></filename>
409 variable. 409 variable.
410 See the 410 See the
411 "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-appdev-srcrev'>Using an External SCM</ulink>" section 411 "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-appdev-srcrev'>Using an External SCM</ulink>" section
412 in the Yocto Project Development Manual for more information. 412 in the Yocto Project Development Manual for more information.
413 </para> 413 </para>
414 414
415 </section> 415 </section>
416 416
417</chapter> 417</chapter>
418<!-- 418<!--
419vim: expandtab tw=80 ts=4 spell spelllang=en_gb 419vim: expandtab tw=80 ts=4 spell spelllang=en_gb
420--> 420-->
diff --git a/documentation/poky-ref-manual/ref-classes.xml b/documentation/poky-ref-manual/ref-classes.xml
index 973d065f58..5ba9811853 100644
--- a/documentation/poky-ref-manual/ref-classes.xml
+++ b/documentation/poky-ref-manual/ref-classes.xml
@@ -6,23 +6,23 @@
6<title>Classes</title> 6<title>Classes</title>
7 7
8<para> 8<para>
9 Class files are used to abstract common functionality and share it amongst multiple 9 Class files are used to abstract common functionality and share it amongst multiple
10 <filename>.bb</filename> files. 10 <filename>.bb</filename> files.
11 Any metadata usually found in a <filename>.bb</filename> file can also be placed in a class 11 Any metadata usually found in a <filename>.bb</filename> file can also be placed in a class
12 file. 12 file.
13 Class files are identified by the extension <filename>.bbclass</filename> and are usually placed 13 Class files are identified by the extension <filename>.bbclass</filename> and are usually placed
14 in a <filename>classes/</filename> directory beneath the 14 in a <filename>classes/</filename> directory beneath the
15 <filename>meta*/</filename> directory found in the 15 <filename>meta*/</filename> directory found in the
16 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. 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 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. 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> 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. 20 using the same method by which <filename>.conf</filename> files are searched.
21</para> 21</para>
22 22
23<para> 23<para>
24 In most cases inheriting the class is enough to enable its features, although 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 25 for some classes you might need to set variables or override some of the
26 default behaviour. 26 default behaviour.
27</para> 27</para>
28 28
@@ -30,14 +30,14 @@
30 <title>The base class - <filename>base.bbclass</filename></title> 30 <title>The base class - <filename>base.bbclass</filename></title>
31 31
32 <para> 32 <para>
33 The base class is special in that every <filename>.bb</filename> 33 The base class is special in that every <filename>.bb</filename>
34 file inherits it automatically. 34 file inherits it automatically.
35 This class contains definitions for standard basic 35 This class contains definitions for standard basic
36 tasks such as fetching, unpacking, configuring (empty by default), compiling 36 tasks such as fetching, unpacking, configuring (empty by default), compiling
37 (runs any <filename>Makefile</filename> present), installing (empty by default) and packaging 37 (runs any <filename>Makefile</filename> present), installing (empty by default) and packaging
38 (empty by default). 38 (empty by default).
39 These classes are often overridden or extended by other classes 39 These classes are often overridden or extended by other classes
40 such as <filename>autotools.bbclass</filename> or <filename>package.bbclass</filename>. 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>. 41 The class also contains some commonly used functions such as <filename>oe_runmake</filename>.
42 </para> 42 </para>
43</section> 43</section>
@@ -46,14 +46,14 @@
46 <title>Autotooled Packages - <filename>autotools.bbclass</filename></title> 46 <title>Autotooled Packages - <filename>autotools.bbclass</filename></title>
47 47
48 <para> 48 <para>
49 Autotools (<filename>autoconf</filename>, <filename>automake</filename>, 49 Autotools (<filename>autoconf</filename>, <filename>automake</filename>,
50 and <filename>libtool</filename>) bring standardization. 50 and <filename>libtool</filename>) bring standardization.
51 This class defines a set of tasks (configure, compile etc.) that 51 This class defines a set of tasks (configure, compile etc.) that
52 work for all Autotooled packages. 52 work for all Autotooled packages.
53 It should usually be enough to define a few standard variables 53 It should usually be enough to define a few standard variables
54 and then simply <filename>inherit autotools</filename>. 54 and then simply <filename>inherit autotools</filename>.
55 This class can also work with software that emulates Autotools. 55 This class can also work with software that emulates Autotools.
56 For more information, see the 56 For more information, see the
57 "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-extend-addpkg-autotools'>Autotooled Package</ulink>" 57 "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-extend-addpkg-autotools'>Autotooled Package</ulink>"
58 section in the Yocto Project Development Manual. 58 section in the Yocto Project Development Manual.
59 </para> 59 </para>
@@ -62,19 +62,19 @@
62 It's useful to have some idea of how the tasks defined by this class work 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. 63 and what they do behind the scenes.
64 <itemizedlist> 64 <itemizedlist>
65 <listitem><para><filename>do_configure</filename> &dash; regenerates the 65 <listitem><para><filename>do_configure</filename> &dash; regenerates the
66 configure script (using <filename>autoreconf</filename>) and then launches it 66 configure script (using <filename>autoreconf</filename>) and then launches it
67 with a standard set of arguments used during cross-compilation. 67 with a standard set of arguments used during cross-compilation.
68 You can pass additional parameters to <filename>configure</filename> through the 68 You can pass additional parameters to <filename>configure</filename> through the
69 <filename><link linkend='var-EXTRA_OECONF'>EXTRA_OECONF</link></filename> variable. 69 <filename><link linkend='var-EXTRA_OECONF'>EXTRA_OECONF</link></filename> variable.
70 </para></listitem> 70 </para></listitem>
71 <listitem><para><filename>do_compile</filename> &dash; runs <filename>make</filename> with 71 <listitem><para><filename>do_compile</filename> &dash; runs <filename>make</filename> with
72 arguments that specify the compiler and linker. 72 arguments that specify the compiler and linker.
73 You can pass additional arguments through 73 You can pass additional arguments through
74 the <filename><link linkend='var-EXTRA_OEMAKE'>EXTRA_OEMAKE</link></filename> variable. 74 the <filename><link linkend='var-EXTRA_OEMAKE'>EXTRA_OEMAKE</link></filename> variable.
75 </para></listitem> 75 </para></listitem>
76 <listitem><para><filename>do_install</filename> &dash; runs <filename>make install</filename> 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 77 and passes a DESTDIR option, which takes its value from the standard
78 <filename><link linkend='var-DESTDIR'>DESTDIR</link></filename> variable. 78 <filename><link linkend='var-DESTDIR'>DESTDIR</link></filename> variable.
79 </para></listitem> 79 </para></listitem>
80 </itemizedlist> 80 </itemizedlist>
@@ -85,28 +85,28 @@
85 <title>Alternatives - <filename>update-alternatives.bbclass</filename></title> 85 <title>Alternatives - <filename>update-alternatives.bbclass</filename></title>
86 86
87 <para> 87 <para>
88 Several programs can fulfill the same or similar function and be installed with the same name. 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 89 For example, the <filename>ar</filename> command is available from the
90 <filename>busybox</filename>, <filename>binutils</filename> and 90 <filename>busybox</filename>, <filename>binutils</filename> and
91 <filename>elfutils</filename> packages. 91 <filename>elfutils</filename> packages.
92 The <filename>update-alternatives.bbclass</filename> class handles renaming the 92 The <filename>update-alternatives.bbclass</filename> class handles renaming the
93 binaries so that multiple packages can be installed without conflicts. 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 94 The <filename>ar</filename> command still works regardless of which packages are installed
95 or subsequently removed. 95 or subsequently removed.
96 The class renames the conflicting binary in each package and symlinks the highest 96 The class renames the conflicting binary in each package and symlinks the highest
97 priority binary during installation or removal of packages. 97 priority binary during installation or removal of packages.
98 </para> 98 </para>
99 <para> 99 <para>
100 Four variables control this class: 100 Four variables control this class:
101 <itemizedlist> 101 <itemizedlist>
102 <listitem><para><filename>ALTERNATIVE_NAME</filename> &dash; The name of the 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> 103 binary that is replaced (<filename>ar</filename> in this example).</para></listitem>
104 <listitem><para><filename>ALTERNATIVE_LINK</filename> &dash; The path to 104 <listitem><para><filename>ALTERNATIVE_LINK</filename> &dash; The path to
105 the resulting binary (<filename>/bin/ar</filename> in this example).</para></listitem> 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 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> 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 108 <listitem><para><filename>ALTERNATIVE_PRIORITY</filename> &dash; The priority of
109 the binary. 109 the binary.
110 The version with the most features should have the highest priority.</para></listitem> 110 The version with the most features should have the highest priority.</para></listitem>
111 </itemizedlist> 111 </itemizedlist>
112 </para> 112 </para>
@@ -120,12 +120,12 @@
120 <title>Initscripts - <filename>update-rc.d.bbclass</filename></title> 120 <title>Initscripts - <filename>update-rc.d.bbclass</filename></title>
121 121
122 <para> 122 <para>
123 This class uses <filename>update-rc.d</filename> to safely install an 123 This class uses <filename>update-rc.d</filename> to safely install an
124 initialization script on behalf of the package. 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 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. 126 a package is removed and started when the package is installed.
127 Three variables control this class: 127 Three variables control this class:
128 <filename><link linkend='var-INITSCRIPT_PACKAGES'>INITSCRIPT_PACKAGES</link></filename>, 128 <filename><link linkend='var-INITSCRIPT_PACKAGES'>INITSCRIPT_PACKAGES</link></filename>,
129 <filename><link linkend='var-INITSCRIPT_NAME'>INITSCRIPT_NAME</link></filename> and 129 <filename><link linkend='var-INITSCRIPT_NAME'>INITSCRIPT_NAME</link></filename> and
130 <filename><link linkend='var-INITSCRIPT_PARAMS'>INITSCRIPT_PARAMS</link></filename>. 130 <filename><link linkend='var-INITSCRIPT_PARAMS'>INITSCRIPT_PARAMS</link></filename>.
131 See the variable links for details. 131 See the variable links for details.
@@ -137,16 +137,16 @@
137 137
138 <para> 138 <para>
139 Before <filename>pkg-config</filename> had become widespread, libraries shipped shell 139 Before <filename>pkg-config</filename> had become widespread, libraries shipped shell
140 scripts to give information about the libraries and include paths needed 140 scripts to give information about the libraries and include paths needed
141 to build software (usually named <filename>LIBNAME-config</filename>). 141 to build software (usually named <filename>LIBNAME-config</filename>).
142 This class assists any recipe using such scripts. 142 This class assists any recipe using such scripts.
143 </para> 143 </para>
144 144
145 <para> 145 <para>
146 During staging, BitBake installs such scripts into the 146 During staging, BitBake installs such scripts into the
147 <filename>sysroots/</filename> directory. 147 <filename>sysroots/</filename> directory.
148 BitBake also changes all paths to point into the <filename>sysroots/</filename> 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 149 directory so all builds that use the script will use the correct
150 directories for the cross compiling layout. 150 directories for the cross compiling layout.
151 </para> 151 </para>
152</section> 152</section>
@@ -171,7 +171,7 @@
171 171
172 <para> 172 <para>
173 During staging, BitBake installs <filename>pkg-config</filename> data into the 173 During staging, BitBake installs <filename>pkg-config</filename> data into the
174 <filename>sysroots/</filename> directory. 174 <filename>sysroots/</filename> directory.
175 By making use of sysroot functionality within <filename>pkg-config</filename>, 175 By making use of sysroot functionality within <filename>pkg-config</filename>,
176 this class no longer has to manipulate the files. 176 this class no longer has to manipulate the files.
177 </para> 177 </para>
@@ -183,14 +183,14 @@
183 <para> 183 <para>
184 Many software licenses require that source files be provided along with the binaries. 184 Many software licenses require that source files be provided along with the binaries.
185 To simplify this process, two classes were created: 185 To simplify this process, two classes were created:
186 <filename>src_distribute.bbclass</filename> and 186 <filename>src_distribute.bbclass</filename> and
187 <filename>src_distribute_local.bbclass</filename>. 187 <filename>src_distribute_local.bbclass</filename>.
188 </para> 188 </para>
189 189
190 <para> 190 <para>
191 The results of these classes are <filename>tmp/deploy/source/</filename> 191 The results of these classes are <filename>tmp/deploy/source/</filename>
192 subdirs with sources sorted by 192 subdirs with sources sorted by
193 <filename><link linkend='var-LICENSE'>LICENSE</link></filename> field. 193 <filename><link linkend='var-LICENSE'>LICENSE</link></filename> field.
194 If recipes list few licenses (or have entries like "Bitstream Vera"), 194 If recipes list few licenses (or have entries like "Bitstream Vera"),
195 the source archive is placed in each license directory. 195 the source archive is placed in each license directory.
196 </para> 196 </para>
@@ -198,11 +198,11 @@
198 <para> 198 <para>
199 This class operates using three modes: 199 This class operates using three modes:
200 <itemizedlist> 200 <itemizedlist>
201 <listitem><para><emphasis>copy:</emphasis> Copies the files to the 201 <listitem><para><emphasis>copy:</emphasis> Copies the files to the
202 distribute directory.</para></listitem> 202 distribute directory.</para></listitem>
203 <listitem><para><emphasis>symlink:</emphasis> Symlinks the files to the 203 <listitem><para><emphasis>symlink:</emphasis> Symlinks the files to the
204 distribute directory.</para></listitem> 204 distribute directory.</para></listitem>
205 <listitem><para><emphasis>move+symlink:</emphasis> Moves the files into 205 <listitem><para><emphasis>move+symlink:</emphasis> Moves the files into
206 the distribute directory and then symlinks them back.</para></listitem> 206 the distribute directory and then symlinks them back.</para></listitem>
207 </itemizedlist> 207 </itemizedlist>
208 </para> 208 </para>
@@ -213,11 +213,11 @@
213 213
214 <para> 214 <para>
215 Recipes for Perl modules are simple. 215 Recipes for Perl modules are simple.
216 These recipes usually only need to point to the source's archive and then inherit the 216 These recipes usually only need to point to the source's archive and then inherit the
217 proper <filename>.bbclass</filename> file. 217 proper <filename>.bbclass</filename> file.
218 Building is split into two methods depending on which method the module authors used. 218 Building is split into two methods depending on which method the module authors used.
219 </para> 219 </para>
220 220
221 <para> 221 <para>
222 Modules that use old <filename>Makefile.PL</filename>-based build system require 222 Modules that use old <filename>Makefile.PL</filename>-based build system require
223 <filename>cpan.bbclass</filename> in their recipes. 223 <filename>cpan.bbclass</filename> in their recipes.
@@ -240,12 +240,12 @@
240 </para> 240 </para>
241 241
242 <para> 242 <para>
243 Extensions that use an Autotools-based build system require Autotools and 243 Extensions that use an Autotools-based build system require Autotools and
244 <filename>distutils</filename>-based <filename>.bbclasse</filename> files in their recipes. 244 <filename>distutils</filename>-based <filename>.bbclasse</filename> files in their recipes.
245 </para> 245 </para>
246 246
247 <para> 247 <para>
248 Extensions that use <filename>distutils</filename>-based build systems require 248 Extensions that use <filename>distutils</filename>-based build systems require
249 <filename>distutils.bbclass</filename> in their recipes. 249 <filename>distutils.bbclass</filename> in their recipes.
250 </para> 250 </para>
251</section> 251</section>
@@ -254,10 +254,10 @@
254 <title>Developer Shell - <filename>devshell.bbclass</filename></title> 254 <title>Developer Shell - <filename>devshell.bbclass</filename></title>
255 255
256 <para> 256 <para>
257 This class adds the <filename>devshell</filename> task. 257 This class adds the <filename>devshell</filename> task.
258 Distribution policy dictates whether to include this class. 258 Distribution policy dictates whether to include this class.
259 See the 259 See the
260 "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-appdev-devshell'>Using a Development Shell</ulink>" section 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>. 261 in the Yocto Project Development Manual for more information about using <filename>devshell</filename>.
262 </para> 262 </para>
263</section> 263</section>
@@ -266,16 +266,16 @@
266 <title>Package Groups - <filename>packagegroup.bbclass</filename></title> 266 <title>Package Groups - <filename>packagegroup.bbclass</filename></title>
267 267
268 <para> 268 <para>
269 This class sets default values appropriate for package group recipes (such as 269 This class sets default values appropriate for package group recipes (such as
270 <filename><link linkend='var-PACKAGES'>PACKAGES</link></filename>, 270 <filename><link linkend='var-PACKAGES'>PACKAGES</link></filename>,
271 <filename><link linkend='var-PACKAGE_ARCH'>PACKAGE_ARCH</link></filename>, 271 <filename><link linkend='var-PACKAGE_ARCH'>PACKAGE_ARCH</link></filename>,
272 <filename><link linkend='var-ALLOW_EMPTY'>ALLOW_EMPTY</link></filename>, 272 <filename><link linkend='var-ALLOW_EMPTY'>ALLOW_EMPTY</link></filename>,
273 and so forth. 273 and so forth.
274 It is highly recommended that all package group recipes inherit this class. 274 It is highly recommended that all package group recipes inherit this class.
275 </para> 275 </para>
276 <para> 276 <para>
277 For information on how to use this class, see the 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>" 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. 279 section in the Yocto Project Development Manual.
280 </para> 280 </para>
281 <para> 281 <para>
@@ -289,41 +289,41 @@
289 289
290 <para> 290 <para>
291 The packaging classes add support for generating packages from a build's 291 The packaging classes add support for generating packages from a build's
292 output. 292 output.
293 The core generic functionality is in <filename>package.bbclass</filename>. 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 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>, 295 <filename>package_deb.bbclass</filename>, <filename>package_ipk.bbclass</filename>,
296 and <filename>package_rpm.bbclass</filename>. 296 and <filename>package_rpm.bbclass</filename>.
297 Most users will want one or more of these classes. 297 Most users will want one or more of these classes.
298 </para> 298 </para>
299 299
300 <para> 300 <para>
301 You can control the list of resulting package formats by using the 301 You can control the list of resulting package formats by using the
302 <filename><link linkend='var-PACKAGE_CLASSES'>PACKAGE_CLASSES</link></filename> 302 <filename><link linkend='var-PACKAGE_CLASSES'>PACKAGE_CLASSES</link></filename>
303 variable defined in the <filename>local.conf</filename> configuration file, 303 variable defined in the <filename>local.conf</filename> configuration file,
304 which is located in the <filename>conf</filename> folder of the 304 which is located in the <filename>conf</filename> folder of the
305 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. 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. 306 When defining the variable, you can specify one or more package types.
307 Since images are generated from packages, a packaging class is 307 Since images are generated from packages, a packaging class is
308 needed to enable image generation. 308 needed to enable image generation.
309 The first class listed in this variable is used for image generation. 309 The first class listed in this variable is used for image generation.
310 </para> 310 </para>
311 311
312 <para> 312 <para>
313 The package class you choose can affect build-time performance and has space 313 The package class you choose can affect build-time performance and has space
314 ramifications. 314 ramifications.
315 In general, building a package with RPM takes about thirty percent more time as 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. 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 317 This comparison takes into account a complete build of the package with all
318 dependencies previously built. 318 dependencies previously built.
319 The reason for this discrepancy is because the RPM package manager creates and 319 The reason for this discrepancy is because the RPM package manager creates and
320 processes more metadata than the IPK package manager. 320 processes more metadata than the IPK package manager.
321 Consequently, you might consider setting <filename>PACKAGE_CLASSES</filename> 321 Consequently, you might consider setting <filename>PACKAGE_CLASSES</filename>
322 to "package_ipk" if you are building smaller systems. 322 to "package_ipk" if you are building smaller systems.
323 </para> 323 </para>
324 324
325 <para> 325 <para>
326 Keep in mind, however, that RPM starts to provide more abilities than IPK due to 326 Keep in mind, however, that RPM starts to provide more abilities than IPK due to
327 the fact that it processes more metadata. 327 the fact that it processes more metadata.
328 For example, this information includes individual file types, file checksum generation 328 For example, this information includes individual file types, file checksum generation
329 and evaluation on install, sparse file support, conflict detection and resolution 329 and evaluation on install, sparse file support, conflict detection and resolution
@@ -332,12 +332,12 @@
332 332
333 <para> 333 <para>
334 Another consideration for packages built using the RPM package manager is space. 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 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. 336 of metadata can affect your ability to do on-device upgrades.
337 </para> 337 </para>
338 338
339 <para> 339 <para>
340 You can find additional information on the effects of the package class at these 340 You can find additional information on the effects of the package class at these
341 two Yocto Project mailing list links: 341 two Yocto Project mailing list links:
342 <itemizedlist> 342 <itemizedlist>
343 <listitem><para><ulink url='&YOCTO_LISTS_URL;/pipermail/poky/2011-May/006362.html'> 343 <listitem><para><ulink url='&YOCTO_LISTS_URL;/pipermail/poky/2011-May/006362.html'>
@@ -352,24 +352,24 @@
352 <title>Building kernels - <filename>kernel.bbclass</filename></title> 352 <title>Building kernels - <filename>kernel.bbclass</filename></title>
353 353
354 <para> 354 <para>
355 This class handles building Linux kernels. 355 This class handles building Linux kernels.
356 The class contains code to build all kernel trees. 356 The class contains code to build all kernel trees.
357 All needed headers are staged into the 357 All needed headers are staged into the
358 <filename><link linkend='var-STAGING_KERNEL_DIR'>STAGING_KERNEL_DIR</link></filename> 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>. 359 directory to allow out-of-tree module builds using <filename>module.bbclass</filename>.
360 </para> 360 </para>
361 361
362 <para> 362 <para>
363 This means that each built kernel module is packaged separately and inter-module 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. 364 dependencies are created by parsing the <filename>modinfo</filename> output.
365 If all modules are required, then installing the <filename>kernel-modules</filename> 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 366 package installs all packages with modules and various other kernel packages
367 such as <filename>kernel-vmlinux</filename>. 367 such as <filename>kernel-vmlinux</filename>.
368 </para> 368 </para>
369 369
370 <para> 370 <para>
371 Various other classes are used by the kernel and module classes internally including 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>, 372 <filename>kernel-arch.bbclass</filename>, <filename>module_strip.bbclass</filename>,
373 <filename>module-base.bbclass</filename>, and <filename>linux-kernel-base.bbclass</filename>. 373 <filename>module-base.bbclass</filename>, and <filename>linux-kernel-base.bbclass</filename>.
374 </para> 374 </para>
375</section> 375</section>
@@ -378,9 +378,9 @@
378 <title>Creating images - <filename>image.bbclass</filename> and <filename>rootfs*.bbclass</filename></title> 378 <title>Creating images - <filename>image.bbclass</filename> and <filename>rootfs*.bbclass</filename></title>
379 379
380 <para> 380 <para>
381 These classes add support for creating images in several formats. 381 These classes add support for creating images in several formats.
382 First, the root filesystem is created from packages using 382 First, the root filesystem is created from packages using
383 one of the <filename>rootfs_*.bbclass</filename> 383 one of the <filename>rootfs_*.bbclass</filename>
384 files (depending on the package format used) and then the image is created. 384 files (depending on the package format used) and then the image is created.
385 </para> 385 </para>
386 386
@@ -389,7 +389,7 @@
389 variable controls the types of images to generate. 389 variable controls the types of images to generate.
390 </para> 390 </para>
391 391
392 <para> 392 <para>
393 The <filename><link linkend='var-IMAGE_INSTALL'>IMAGE_INSTALL</link></filename> 393 The <filename><link linkend='var-IMAGE_INSTALL'>IMAGE_INSTALL</link></filename>
394 variable controls the list of packages to install into the image. 394 variable controls the list of packages to install into the image.
395 </para> 395 </para>
@@ -399,11 +399,11 @@
399 <title>Host System sanity checks - <filename>sanity.bbclass</filename></title> 399 <title>Host System sanity checks - <filename>sanity.bbclass</filename></title>
400 400
401 <para> 401 <para>
402 This class checks to see if prerequisite software is present so that 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. 403 users can be notified of potential problems that might affect their build.
404 The class also performs basic user configuration checks from 404 The class also performs basic user configuration checks from
405 the <filename>local.conf</filename> configuration file to 405 the <filename>local.conf</filename> configuration file to
406 prevent common mistakes that cause build failures. 406 prevent common mistakes that cause build failures.
407 Distribution policy usually determines whether to include this class. 407 Distribution policy usually determines whether to include this class.
408 </para> 408 </para>
409</section> 409</section>
@@ -420,14 +420,14 @@
420 </para> 420 </para>
421 421
422 <para> 422 <para>
423 You can configure the sanity checks so that specific test failures either raise a warning or 423 You can configure the sanity checks so that specific test failures either raise a warning or
424 an error message. 424 an error message.
425 Typically, failures for new tests generate a warning. 425 Typically, failures for new tests generate a warning.
426 Subsequent failures for the same test would then generate an error message 426 Subsequent failures for the same test would then generate an error message
427 once the metadata is in a known and good condition. 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 428 You use the <filename>WARN_QA</filename> variable to specify tests for which you
429 want to generate a warning message on failure. 429 want to generate a warning message on failure.
430 You use the <filename>ERROR_QA</filename> variable to specify tests for which you 430 You use the <filename>ERROR_QA</filename> variable to specify tests for which you
431 want to generate an error message on failure. 431 want to generate an error message on failure.
432 </para> 432 </para>
433 433
@@ -436,41 +436,41 @@
436 and <filename>ERROR_QA</filename> variables: 436 and <filename>ERROR_QA</filename> variables:
437 <itemizedlist> 437 <itemizedlist>
438 <listitem><para><emphasis><filename>ldflags:</filename></emphasis> 438 <listitem><para><emphasis><filename>ldflags:</filename></emphasis>
439 Ensures that the binaries were linked with the 439 Ensures that the binaries were linked with the
440 <filename>LDFLAGS</filename> options provided by the build system. 440 <filename>LDFLAGS</filename> options provided by the build system.
441 If this test fails, check that the <filename>LDFLAGS</filename> variable 441 If this test fails, check that the <filename>LDFLAGS</filename> variable
442 is being passed to the linker command.</para></listitem> 442 is being passed to the linker command.</para></listitem>
443 <listitem><para><emphasis><filename>useless-rpaths:</filename></emphasis> 443 <listitem><para><emphasis><filename>useless-rpaths:</filename></emphasis>
444 Checks for dynamic library load paths (rpaths) in the binaries that 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. 445 by default on a standard system are searched by the linker (e.g.
446 <filename>/lib</filename> and <filename>/usr/lib</filename>). 446 <filename>/lib</filename> and <filename>/usr/lib</filename>).
447 While these paths will not cause any breakage, they do waste space and 447 While these paths will not cause any breakage, they do waste space and
448 are unnecessary.</para></listitem> 448 are unnecessary.</para></listitem>
449 <listitem><para><emphasis><filename>rpaths:</filename></emphasis> 449 <listitem><para><emphasis><filename>rpaths:</filename></emphasis>
450 Checks for rpaths in the binaries that contain build system paths such 450 Checks for rpaths in the binaries that contain build system paths such
451 as <filename>TMPDIR</filename>. 451 as <filename>TMPDIR</filename>.
452 If this test fails, bad <filename>-rpath</filename> options are being 452 If this test fails, bad <filename>-rpath</filename> options are being
453 passed to the linker commands and your binaries have potential security 453 passed to the linker commands and your binaries have potential security
454 issues.</para></listitem> 454 issues.</para></listitem>
455 <listitem><para><emphasis><filename>dev-so:</filename></emphasis> 455 <listitem><para><emphasis><filename>dev-so:</filename></emphasis>
456 Checks that the <filename>.so</filename> symbolic links are in the 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. 457 <filename>-dev</filename> package and not in any of the other packages.
458 In general, these symlinks are only useful for development purposes. 458 In general, these symlinks are only useful for development purposes.
459 Thus, the <filename>-dev</filename> package is the correct location for 459 Thus, the <filename>-dev</filename> package is the correct location for
460 them. 460 them.
461 Some very rare cases do exist for dynamically loaded modules where 461 Some very rare cases do exist for dynamically loaded modules where
462 these symlinks are needed instead in the main package. 462 these symlinks are needed instead in the main package.
463 </para></listitem> 463 </para></listitem>
464 <listitem><para><emphasis><filename>debug-files:</filename></emphasis> 464 <listitem><para><emphasis><filename>debug-files:</filename></emphasis>
465 Checks for <filename>.debug</filename> directories in anything but the 465 Checks for <filename>.debug</filename> directories in anything but the
466 <filename>-dbg</filename> package. 466 <filename>-dbg</filename> package.
467 The debug files should all be in the <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> 468 Thus, anything packaged elsewhere is incorrect packaging.</para></listitem>
469 <listitem><para><emphasis><filename>arch:</filename></emphasis> 469 <listitem><para><emphasis><filename>arch:</filename></emphasis>
470 Checks the Executable and Linkable Format (ELF) type, bit size and endianness 470 Checks the Executable and Linkable Format (ELF) type, bit size and endianness
471 of any binaries to ensure it matches the target architecture. 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 472 This test fails if any binaries don't match the type since there would be an
473 incompatibility. 473 incompatibility.
474 Sometimes software, like bootloaders, might need to bypass this check. 474 Sometimes software, like bootloaders, might need to bypass this check.
475 </para></listitem> 475 </para></listitem>
476 <listitem><para><emphasis><filename>debug-deps:</filename></emphasis> 476 <listitem><para><emphasis><filename>debug-deps:</filename></emphasis>
@@ -478,24 +478,24 @@
478 <filename>-dbg</filename> packages and not on any other types of packages, 478 <filename>-dbg</filename> packages and not on any other types of packages,
479 which would cause a packaging bug.</para></listitem> 479 which would cause a packaging bug.</para></listitem>
480 <listitem><para><emphasis><filename>dev-deps:</filename></emphasis> 480 <listitem><para><emphasis><filename>dev-deps:</filename></emphasis>
481 Checks that <filename>-dev</filename> packages only depend on other 481 Checks that <filename>-dev</filename> packages only depend on other
482 <filename>-dev</filename> packages and not on any other types of packages, 482 <filename>-dev</filename> packages and not on any other types of packages,
483 which would be a packaging bug.</para></listitem> 483 which would be a packaging bug.</para></listitem>
484 <listitem><para><emphasis><filename>pkgconfig:</filename></emphasis> 484 <listitem><para><emphasis><filename>pkgconfig:</filename></emphasis>
485 Checks <filename>.pc</filename> files for any 485 Checks <filename>.pc</filename> files for any
486 <filename>TMPDIR/WORKDIR</filename> paths. 486 <filename>TMPDIR/WORKDIR</filename> paths.
487 Any <filename>.pc</filename> file containing these paths is incorrect 487 Any <filename>.pc</filename> file containing these paths is incorrect
488 since <filename>pkg-config</filename> itself adds the correct sysroot prefix 488 since <filename>pkg-config</filename> itself adds the correct sysroot prefix
489 when the files are accessed.</para></listitem> 489 when the files are accessed.</para></listitem>
490 <listitem><para><emphasis><filename>la:</filename></emphasis> 490 <listitem><para><emphasis><filename>la:</filename></emphasis>
491 Checks <filename>.la</filename> files for any <filename>TMPDIR</filename> 491 Checks <filename>.la</filename> files for any <filename>TMPDIR</filename>
492 paths. 492 paths.
493 Any <filename>.la</filename> file continaing these paths is incorrect since 493 Any <filename>.la</filename> file continaing these paths is incorrect since
494 <filename>libtool</filename> adds the correct sysroot prefix when using the 494 <filename>libtool</filename> adds the correct sysroot prefix when using the
495 files automatically itself.</para></listitem> 495 files automatically itself.</para></listitem>
496 <listitem><para><emphasis><filename>desktop:</filename></emphasis> 496 <listitem><para><emphasis><filename>desktop:</filename></emphasis>
497 Runs the <filename>desktop-file-validate</filename> program against any 497 Runs the <filename>desktop-file-validate</filename> program against any
498 <filename>.desktop</filename> files to validate their contents against 498 <filename>.desktop</filename> files to validate their contents against
499 the specification for <filename>.desktop</filename> files.</para></listitem> 499 the specification for <filename>.desktop</filename> files.</para></listitem>
500 </itemizedlist> 500 </itemizedlist>
501 </para> 501 </para>
@@ -511,17 +511,17 @@
511 still make the correct values available. 511 still make the correct values available.
512 The <filename><link linkend='structure-meta-site'>meta/site directory</link></filename> 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 513 contains test results sorted into different categories such as architecture, endianness, and
514 the <filename>libc</filename> used. 514 the <filename>libc</filename> used.
515 Site information provides a list of files containing data relevant to 515 Site information provides a list of files containing data relevant to
516 the current build in the 516 the current build in the
517 <filename><link linkend='var-CONFIG_SITE'>CONFIG_SITE</link></filename> variable 517 <filename><link linkend='var-CONFIG_SITE'>CONFIG_SITE</link></filename> variable
518 that Autotools automatically picks up. 518 that Autotools automatically picks up.
519 </para> 519 </para>
520 520
521 <para> 521 <para>
522 The class also provides variables like 522 The class also provides variables like
523 <filename><link linkend='var-SITEINFO_ENDIANNESS'>SITEINFO_ENDIANNESS</link></filename> 523 <filename><link linkend='var-SITEINFO_ENDIANNESS'>SITEINFO_ENDIANNESS</link></filename>
524 and <filename><link linkend='var-SITEINFO_BITS'>SITEINFO_BITS</link></filename> 524 and <filename><link linkend='var-SITEINFO_BITS'>SITEINFO_BITS</link></filename>
525 that can be used elsewhere in the metadata. 525 that can be used elsewhere in the metadata.
526 </para> 526 </para>
527 527
@@ -534,14 +534,14 @@
534 <title>Adding Users - <filename>useradd.bbclass</filename></title> 534 <title>Adding Users - <filename>useradd.bbclass</filename></title>
535 535
536 <para> 536 <para>
537 If you have packages that install files that are owned by custom users or groups, 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 538 you can use this class to specify those packages and associate the users and groups
539 with those packages. 539 with those packages.
540 The <filename>meta-skeleton/recipes-skeleton/useradd/useradd-example.bb</filename> 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> 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 542 provides a simple exmample that shows how to add three
543 users and groups to two packages. 543 users and groups to two packages.
544 See the <filename>useradd-example.bb</filename> for more information on how to 544 See the <filename>useradd-example.bb</filename> for more information on how to
545 use this class. 545 use this class.
546 </para> 546 </para>
547</section> 547</section>
@@ -550,33 +550,33 @@
550 <title>Using External Source - <filename>externalsrc.bbclass</filename></title> 550 <title>Using External Source - <filename>externalsrc.bbclass</filename></title>
551 551
552 <para> 552 <para>
553 You can use this class to build software from source code that is external to the 553 You can use this class to build software from source code that is external to the
554 OpenEmbedded build system. 554 OpenEmbedded build system.
555 In other words, your source code resides in an external tree outside of the Yocto Project. 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 556 Building software from an external source tree means that the normal fetch, unpack, and
557 patch process is not used. 557 patch process is not used.
558 </para> 558 </para>
559 559
560 <para> 560 <para>
561 To use the class, you need to define the 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. 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. 563 You also need to have your recipe inherit the <filename>externalsrc.bbclass</filename> class.
564 </para> 564 </para>
565 565
566 <para> 566 <para>
567 This class expects the source code to support recipe builds that use the 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 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. 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 570 By default, the <filename>B</filename> directory is set to the following, which is separate from the
571 Source Directory (<filename>S</filename>): 571 Source Directory (<filename>S</filename>):
572 <literallayout class='monospaced'> 572 <literallayout class='monospaced'>
573 ${WORKDIR}/${BPN}-{PV}/ 573 ${WORKDIR}/${BPN}-{PV}/
574 </literallayout> 574 </literallayout>
575 See the glossary entries for the 575 See the glossary entries for the
576 <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>, 576 <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>,
577 <link linkend='var-BPN'><filename>BPN</filename></link>, 577 <link linkend='var-BPN'><filename>BPN</filename></link>,
578 <link linkend='var-PV'><filename>PV</filename></link>, 578 <link linkend='var-PV'><filename>PV</filename></link>,
579 <link linkend='var-S'><filename>S</filename></link>, and 579 <link linkend='var-S'><filename>S</filename></link>, and
580 <link linkend='var-B'><filename>B</filename></link> for more information. 580 <link linkend='var-B'><filename>B</filename></link> for more information.
581 </para> 581 </para>
582 582
@@ -584,26 +584,26 @@
584 You can build object files in the external tree by setting the 584 You can build object files in the external tree by setting the
585 <filename>B</filename> variable equal to <filename>"${S}"</filename>. 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 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>, 587 (i.e., "natives" such as <filename>quilt-native</filename>,
588 or "crosses" such as <filename>gcc-cross</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. 589 So, be sure there are no "native", "cross", or "multilib" variants of the recipe.
590 </para> 590 </para>
591 591
592 <para> 592 <para>
593 If you do want to build different variants of a recipe, you can use the 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. 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 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. 596 recipe's ability to build variants in different working directories.
597 Most autotools-based recipes support separating these directories. 597 Most autotools-based recipes support separating these directories.
598 The OpenEmbedded build system defaults to using separate directories for <filename>gcc</filename> 598 The OpenEmbedded build system defaults to using separate directories for <filename>gcc</filename>
599 and some kernel recipes. 599 and some kernel recipes.
600 Alternatively, you can make sure that separate recipes exist that each 600 Alternatively, you can make sure that separate recipes exist that each
601 use the <filename>BBCLASSEXTEND</filename> variable to build each variant. 601 use the <filename>BBCLASSEXTEND</filename> variable to build each variant.
602 The separate recipes can inherit a single target recipe. 602 The separate recipes can inherit a single target recipe.
603 </para> 603 </para>
604 604
605 <para> 605 <para>
606 For information on how to use this class, see the 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 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. 608 Software from an External Source</ulink>" section in the Yocto Project Development Manual.
609 </para> 609 </para>
@@ -613,12 +613,12 @@
613 <title>Other Classes</title> 613 <title>Other Classes</title>
614 614
615 <para> 615 <para>
616 Thus far, this chapter has discussed only the most useful and important 616 Thus far, this chapter has discussed only the most useful and important
617 classes. 617 classes.
618 However, other classes exist within the <filename>meta/classes</filename> directory 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>. 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 620 You can examine the <filename>.bbclass</filename> files directly for more
621 information. 621 information.
622 </para> 622 </para>
623</section> 623</section>
624 624
@@ -715,6 +715,6 @@
715 715
716 716
717</chapter> 717</chapter>
718<!-- 718<!--
719vim: expandtab tw=80 ts=4 719vim: expandtab tw=80 ts=4
720--> 720-->
diff --git a/documentation/poky-ref-manual/ref-features.xml b/documentation/poky-ref-manual/ref-features.xml
index ec70547314..77c31275ae 100644
--- a/documentation/poky-ref-manual/ref-features.xml
+++ b/documentation/poky-ref-manual/ref-features.xml
@@ -7,7 +7,7 @@
7 7
8 <para> 8 <para>
9 Features provide a mechanism for working out which packages 9 Features provide a mechanism for working out which packages
10 should be included in the generated images. 10 should be included in the generated images.
11 Distributions can select which features they want to support through the 11 Distributions can select which features they want to support through the
12 <filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename> 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. 13 variable, which is set in the <filename>poky.conf</filename> distribution configuration file.
@@ -19,16 +19,16 @@
19 19
20 <para> 20 <para>
21 These two variables combine to work out which kernel modules, 21 These two variables combine to work out which kernel modules,
22 utilities, and other packages to include. 22 utilities, and other packages to include.
23 A given distribution can support a selected subset of features so some machine features might not 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. 24 be included if the distribution itself does not support them.
25 </para> 25 </para>
26 26
27 <para> 27 <para>
28 One method you can use to determine which recipes are checking to see if a 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 29 particular feature is contained or not is to <filename>grep</filename> through
30 the metadata for the feature. 30 the metadata for the feature.
31 Here is an example that discovers the recipes whose build is potentially 31 Here is an example that discovers the recipes whose build is potentially
32 changed based on a given feature: 32 changed based on a given feature:
33 <literallayout class='monospaced'> 33 <literallayout class='monospaced'>
34 $ cd $HOME/poky 34 $ cd $HOME/poky
@@ -38,21 +38,21 @@
38 38
39 <para> 39 <para>
40 This chapter provides a reference of shipped machine and distro features 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 41 you can include as part of the image, a reference on image types you can
42 build, and a reference on feature backfilling. 42 build, and a reference on feature backfilling.
43 </para> 43 </para>
44 44
45 45
46 <section id='ref-features-distro'> 46 <section id='ref-features-distro'>
47 <title>Distro</title> 47 <title>Distro</title>
48 48
49 <para> 49 <para>
50 The items below are features you can use with 50 The items below are features you can use with
51 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>. 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 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. 53 go beyond simply controlling the installation of a package or packages.
54 Sometimes a feature can influence how certain recipes are built. 54 Sometimes a feature can influence how certain recipes are built.
55 For example, a feature might determine whether a particular configure option 55 For example, a feature might determine whether a particular configure option
56 is specified within <filename>do_configure</filename> for a particular 56 is specified within <filename>do_configure</filename> for a particular
57 recipe. 57 recipe.
58 </para> 58 </para>
@@ -60,7 +60,7 @@
60 <para> 60 <para>
61 This list only represents features as shipped with the Yocto Project metadata: 61 This list only represents features as shipped with the Yocto Project metadata:
62 <itemizedlist> 62 <itemizedlist>
63 <listitem><para><emphasis>alsa:</emphasis> ALSA support will be included (OSS compatibility 63 <listitem><para><emphasis>alsa:</emphasis> ALSA support will be included (OSS compatibility
64 kernel modules will be installed if available).</para></listitem> 64 kernel modules will be installed if available).</para></listitem>
65 <listitem><para><emphasis>bluetooth:</emphasis> Include bluetooth support (integrated BT only) 65 <listitem><para><emphasis>bluetooth:</emphasis> Include bluetooth support (integrated BT only)
66 </para></listitem> 66 </para></listitem>
@@ -69,7 +69,7 @@
69 </para></listitem> 69 </para></listitem>
70 <listitem><para><emphasis>irda:</emphasis> Include Irda support 70 <listitem><para><emphasis>irda:</emphasis> Include Irda support
71 </para></listitem> 71 </para></listitem>
72 <listitem><para><emphasis>keyboard:</emphasis> Include keyboard support (e.g. keymaps will be 72 <listitem><para><emphasis>keyboard:</emphasis> Include keyboard support (e.g. keymaps will be
73 loaded during boot). 73 loaded during boot).
74 </para></listitem> 74 </para></listitem>
75 <listitem><para><emphasis>pci:</emphasis> Include PCI bus support 75 <listitem><para><emphasis>pci:</emphasis> Include PCI bus support
@@ -103,12 +103,12 @@
103 <title>Machine</title> 103 <title>Machine</title>
104 104
105 <para> 105 <para>
106 The items below are features you can use with 106 The items below are features you can use with
107 <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link>. 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 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. 109 go beyond simply controlling the installation of a package or packages.
110 Sometimes a feature can influence how certain recipes are built. 110 Sometimes a feature can influence how certain recipes are built.
111 For example, a feature might determine whether a particular configure option 111 For example, a feature might determine whether a particular configure option
112 is specified within <filename>do_configure</filename> for a particular 112 is specified within <filename>do_configure</filename> for a particular
113 recipe. 113 recipe.
114 </para> 114 </para>
@@ -154,7 +154,7 @@
154 <title>Images</title> 154 <title>Images</title>
155 155
156 <para> 156 <para>
157 The contents of images generated by the OpenEmbedded build system can be controlled by the 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> 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> 159 and <filename><link linkend='var-EXTRA_IMAGE_FEATURES'>EXTRA_IMAGE_FEATURES</link></filename>
160 variables that you typically configure in your image recipes. 160 variables that you typically configure in your image recipes.
@@ -164,48 +164,48 @@
164 </para> 164 </para>
165 165
166 <para> 166 <para>
167 Current list of 167 Current list of
168 <filename>IMAGE_FEATURES</filename> contains the following: 168 <filename>IMAGE_FEATURES</filename> contains the following:
169 <itemizedlist> 169 <itemizedlist>
170 <listitem><para><emphasis>splash:</emphasis> Enables showing a splash screen during boot. 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 171 By default, this screen is provided by <filename>psplash</filename>, which does
172 allow customization. 172 allow customization.
173 If you prefer to use an alternative splash screen package, you can do so by 173 If you prefer to use an alternative splash screen package, you can do so by
174 setting the <filename>SPLASH</filename> variable 174 setting the <filename>SPLASH</filename> variable
175 to a different package name (or names) within the image recipe or at the distro 175 to a different package name (or names) within the image recipe or at the distro
176 configuration level.</para></listitem> 176 configuration level.</para></listitem>
177 <listitem><para><emphasis>ssh-server-dropbear:</emphasis> Installs the Dropbear minimal 177 <listitem><para><emphasis>ssh-server-dropbear:</emphasis> Installs the Dropbear minimal
178 SSH server. 178 SSH server.
179 </para></listitem> 179 </para></listitem>
180 <listitem><para><emphasis>ssh-server-openssh:</emphasis> Installs the OpenSSH SSH server, 180 <listitem><para><emphasis>ssh-server-openssh:</emphasis> Installs the OpenSSH SSH server,
181 which is more full-featured than Dropbear. 181 which is more full-featured than Dropbear.
182 Note that if both the OpenSSH SSH server and the Dropbear minimal SSH server 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 183 are present in <filename>IMAGE_FEATURES</filename>, then OpenSSH will take
184 precedence and Dropbear will not be installed.</para></listitem> 184 precedence and Dropbear will not be installed.</para></listitem>
185 <listitem><para><emphasis>x11:</emphasis> Installs the X server</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 186 <listitem><para><emphasis>x11-base:</emphasis> Installs the X server with a
187 minimal environment.</para></listitem> 187 minimal environment.</para></listitem>
188 <listitem><para><emphasis>x11-sato:</emphasis> Installs the OpenedHand Sato environment. 188 <listitem><para><emphasis>x11-sato:</emphasis> Installs the OpenedHand Sato environment.
189 </para></listitem> 189 </para></listitem>
190 <listitem><para><emphasis>tools-sdk:</emphasis> Installs a full SDK that runs on the device. 190 <listitem><para><emphasis>tools-sdk:</emphasis> Installs a full SDK that runs on the device.
191 </para></listitem> 191 </para></listitem>
192 <listitem><para><emphasis>tools-debug:</emphasis> Installs debugging tools such as 192 <listitem><para><emphasis>tools-debug:</emphasis> Installs debugging tools such as
193 <filename>strace</filename> and <filename>gdb</filename>. 193 <filename>strace</filename> and <filename>gdb</filename>.
194 </para></listitem> 194 </para></listitem>
195 <listitem><para><emphasis>tools-profile:</emphasis> Installs profiling tools such as 195 <listitem><para><emphasis>tools-profile:</emphasis> Installs profiling tools such as
196 <filename>oprofile</filename>, <filename>exmap</filename>, and 196 <filename>oprofile</filename>, <filename>exmap</filename>, and
197 <filename>LTTng</filename>.</para></listitem> 197 <filename>LTTng</filename>.</para></listitem>
198 <listitem><para><emphasis>tools-testapps:</emphasis> Installs device testing tools (e.g. 198 <listitem><para><emphasis>tools-testapps:</emphasis> Installs device testing tools (e.g.
199 touchscreen debugging).</para></listitem> 199 touchscreen debugging).</para></listitem>
200 <listitem><para><emphasis>nfs-server:</emphasis> Installs an NFS server.</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 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> 202 extra library links) for all packages installed in a given image.</para></listitem>
203 <listitem><para><emphasis>staticdev-pkgs:</emphasis> Installs static development 203 <listitem><para><emphasis>staticdev-pkgs:</emphasis> Installs static development
204 packages (i.e. static libraries containing <filename>*.a</filename> files) for all 204 packages (i.e. static libraries containing <filename>*.a</filename> files) for all
205 packages installed in a given image.</para></listitem> 205 packages installed in a given image.</para></listitem>
206 <listitem><para><emphasis>dbg-pkgs:</emphasis> Installs debug symbol packages for all packages 206 <listitem><para><emphasis>dbg-pkgs:</emphasis> Installs debug symbol packages for all packages
207 installed in a given image.</para></listitem> 207 installed in a given image.</para></listitem>
208 <listitem><para><emphasis>doc-pkgs:</emphasis> Installs documentation packages for all packages 208 <listitem><para><emphasis>doc-pkgs:</emphasis> Installs documentation packages for all packages
209 installed in a given image.</para></listitem> 209 installed in a given image.</para></listitem>
210 </itemizedlist> 210 </itemizedlist>
211 </para> 211 </para>
@@ -218,30 +218,30 @@
218 Sometimes it is necessary in the OpenEmbedded build system to extend 218 Sometimes it is necessary in the OpenEmbedded build system to extend
219 <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link> 219 <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link>
220 or <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_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 221 to control functionality that was previously enabled and not able
222 to be disabled. 222 to be disabled.
223 For these cases, we need to add an 223 For these cases, we need to add an
224 additional feature item to appear in one of these variables, 224 additional feature item to appear in one of these variables,
225 but we do not want to force developers who have existing values 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 226 of the variables in their configuration to add the new feature
227 in order to retain the same overall level of functionality. 227 in order to retain the same overall level of functionality.
228 Thus, the OpenEmbedded build system has a mechanism to 228 Thus, the OpenEmbedded build system has a mechanism to
229 automatically "backfill" these added features into existing 229 automatically "backfill" these added features into existing
230 distro or machine configurations. 230 distro or machine configurations.
231 You can see the list of features for which this is done by 231 You can see the list of features for which this is done by
232 finding the 232 finding the
233 <link linkend='var-DISTRO_FEATURES_BACKFILL'><filename>DISTRO_FEATURES_BACKFILL</filename></link> 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> 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. 235 variables in the <filename>meta/conf/bitbake.conf</filename> file.
236 </para> 236 </para>
237 237
238 <para> 238 <para>
239 Because such features are backfilled by default into all 239 Because such features are backfilled by default into all
240 configurations as described in the previous paragraph, developers 240 configurations as described in the previous paragraph, developers
241 who wish to disable the new features need to be able to selectively 241 who wish to disable the new features need to be able to selectively
242 prevent the backfilling from occurring. 242 prevent the backfilling from occurring.
243 They can do this by adding the undesired feature or features to the 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> 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> 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. 246 variables for distro features and machine features respectively.
247 </para> 247 </para>
@@ -249,46 +249,46 @@
249 <para> 249 <para>
250 Here are two examples to help illustrate feature backfilling: 250 Here are two examples to help illustrate feature backfilling:
251 <itemizedlist> 251 <itemizedlist>
252 <listitem><para><emphasis>The "pulseaudio" distro feature option</emphasis>: 252 <listitem><para><emphasis>The "pulseaudio" distro feature option</emphasis>:
253 Previously, PulseAudio support was enabled within the Qt and 253 Previously, PulseAudio support was enabled within the Qt and
254 GStreamer frameworks. 254 GStreamer frameworks.
255 Because of this, the feature is backfilled and thus 255 Because of this, the feature is backfilled and thus
256 enabled for all distros through the 256 enabled for all distros through the
257 <filename>DISTRO_FEATURES_BACKFILL</filename> 257 <filename>DISTRO_FEATURES_BACKFILL</filename>
258 variable in the <filename>meta/conf/bitbake.conf</filename> file. 258 variable in the <filename>meta/conf/bitbake.conf</filename> file.
259 However, your distro needs to disable the feature. 259 However, your distro needs to disable the feature.
260 You can disable the feature without affecting 260 You can disable the feature without affecting
261 other existing distro configurations that need PulseAudio support 261 other existing distro configurations that need PulseAudio support
262 by adding "pulseaudio" to 262 by adding "pulseaudio" to
263 <filename>DISTRO_FEATURES_BACKFILL_CONSIDERED</filename> 263 <filename>DISTRO_FEATURES_BACKFILL_CONSIDERED</filename>
264 in your distro's <filename>.conf</filename> file. 264 in your distro's <filename>.conf</filename> file.
265 Adding the feature to this variable when it also 265 Adding the feature to this variable when it also
266 exists in the <filename>DISTRO_FEATURES_BACKFILL</filename> 266 exists in the <filename>DISTRO_FEATURES_BACKFILL</filename>
267 variable prevents the build system from adding the feature to 267 variable prevents the build system from adding the feature to
268 your configuration's <filename>DISTRO_FEATURES</filename>, effectively disabling 268 your configuration's <filename>DISTRO_FEATURES</filename>, effectively disabling
269 the feature for that particular distro.</para></listitem> 269 the feature for that particular distro.</para></listitem>
270 <listitem><para><emphasis>The "rtc" machine feature option</emphasis>: 270 <listitem><para><emphasis>The "rtc" machine feature option</emphasis>:
271 Previously, real time clock (RTC) support was enabled for all 271 Previously, real time clock (RTC) support was enabled for all
272 target devices. 272 target devices.
273 Because of this, the feature is backfilled and thus enabled 273 Because of this, the feature is backfilled and thus enabled
274 for all machines through the <filename>MACHINE_FEATURES_BACKFILL</filename> 274 for all machines through the <filename>MACHINE_FEATURES_BACKFILL</filename>
275 variable in the <filename>meta/conf/bitbake.conf</filename> file. 275 variable in the <filename>meta/conf/bitbake.conf</filename> file.
276 However, your target device does not have this capability. 276 However, your target device does not have this capability.
277 You can disable RTC support for your device without 277 You can disable RTC support for your device without
278 affecting other machines that need RTC support 278 affecting other machines that need RTC support
279 by adding the feature to your machine's 279 by adding the feature to your machine's
280 <filename>MACHINE_FEATURES_BACKFILL_CONSIDERED</filename> 280 <filename>MACHINE_FEATURES_BACKFILL_CONSIDERED</filename>
281 list in the machine's <filename>.conf</filename> file. 281 list in the machine's <filename>.conf</filename> file.
282 Adding the feature to this variable when it also 282 Adding the feature to this variable when it also
283 exists in the <filename>MACHINE_FEATURES_BACKFILL</filename> 283 exists in the <filename>MACHINE_FEATURES_BACKFILL</filename>
284 variable prevents the build system from adding the feature to 284 variable prevents the build system from adding the feature to
285 your configuration's <filename>MACHINE_FEATURES</filename>, effectively 285 your configuration's <filename>MACHINE_FEATURES</filename>, effectively
286 disabling RTC support for that particular machine.</para></listitem> 286 disabling RTC support for that particular machine.</para></listitem>
287 </itemizedlist> 287 </itemizedlist>
288 </para> 288 </para>
289 </section> 289 </section>
290</chapter> 290</chapter>
291 291
292<!-- 292<!--
293vim: expandtab tw=80 ts=4 spell spelllang=en_gb 293vim: expandtab tw=80 ts=4 spell spelllang=en_gb
294--> 294-->
diff --git a/documentation/poky-ref-manual/ref-images.xml b/documentation/poky-ref-manual/ref-images.xml
index 79f2409933..0a827ca235 100644
--- a/documentation/poky-ref-manual/ref-images.xml
+++ b/documentation/poky-ref-manual/ref-images.xml
@@ -6,8 +6,8 @@
6 <title>Images</title> 6 <title>Images</title>
7 7
8 <para> 8 <para>
9 The OpenEmbedded build process supports several types of images to satisfy different needs. 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 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. 11 that essentially begins the build for the type of image you want.
12 </para> 12 </para>
13 13
@@ -24,16 +24,16 @@
24 </note> 24 </note>
25 25
26 <para> 26 <para>
27 From within the <filename>poky</filename> Git repository, use the following command to list 27 From within the <filename>poky</filename> Git repository, use the following command to list
28 the supported images: 28 the supported images:
29 <literallayout class='monospaced'> 29 <literallayout class='monospaced'>
30 $ ls meta*/recipes*/images/*.bb 30 $ ls meta*/recipes*/images/*.bb
31 </literallayout> 31 </literallayout>
32 These recipes reside in the <filename>meta/recipes-core/images</filename>, 32 These recipes reside in the <filename>meta/recipes-core/images</filename>,
33 <filename>meta/recipes-extended/images</filename>, 33 <filename>meta/recipes-extended/images</filename>,
34 <filename>meta/recipes-graphics/images</filename>, and 34 <filename>meta/recipes-graphics/images</filename>, and
35 <filename>meta/recipes-sato/images</filename> directories 35 <filename>meta/recipes-sato/images</filename> directories
36 within the <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>source directory</ulink>. 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: 37 Although the recipe names are somewhat explanatory, here is a list that describes them:
38 </para> 38 </para>
39 39
@@ -45,17 +45,17 @@
45 <listitem><para><emphasis><filename>core-image-minimal-dev</filename>:</emphasis> 45 <listitem><para><emphasis><filename>core-image-minimal-dev</filename>:</emphasis>
46 A <filename>core-image-minimal</filename> image suitable for development work 46 A <filename>core-image-minimal</filename> image suitable for development work
47 using the host. 47 using the host.
48 The image includes headers and libraries you can use in a host development 48 The image includes headers and libraries you can use in a host development
49 environment. 49 environment.
50 </para></listitem> 50 </para></listitem>
51 <listitem><para><emphasis><filename>core-image-minimal-initramfs</filename>:</emphasis> 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 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, 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. 54 which allows the system to find the first “init” program more efficiently.
55 </para></listitem> 55 </para></listitem>
56 <listitem><para><emphasis><filename>core-image-minimal-mtdutils</filename>:</emphasis> 56 <listitem><para><emphasis><filename>core-image-minimal-mtdutils</filename>:</emphasis>
57 A <filename>core-image-minimal</filename> image that has support 57 A <filename>core-image-minimal</filename> image that has support
58 for the Minimal MTD Utilities, which let the user interact with the 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. 59 MTD subsystem in the kernel to perform operations on flash devices.
60 </para></listitem> 60 </para></listitem>
61 <listitem><para><emphasis><filename>core-image-x11</filename>:</emphasis> 61 <listitem><para><emphasis><filename>core-image-x11</filename>:</emphasis>
@@ -69,64 +69,64 @@
69 <listitem><para><emphasis><filename>core-image-lsb-dev</filename>:</emphasis> 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 70 A <filename>core-image-lsb</filename> image that is suitable for development work
71 using the host. 71 using the host.
72 The image includes headers and libraries you can use in a host development 72 The image includes headers and libraries you can use in a host development
73 environment. 73 environment.
74 </para></listitem> 74 </para></listitem>
75 <listitem><para><emphasis><filename>core-image-lsb-sdk</filename>:</emphasis> 75 <listitem><para><emphasis><filename>core-image-lsb-sdk</filename>:</emphasis>
76 A <filename>core-image-lsb</filename> that includes everything in meta-toolchain 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. 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> 78 This image is suitable for development using the target.</para></listitem>
79 <listitem><para><emphasis><filename>core-image-clutter</filename>:</emphasis> 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 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> 81 rich and animated graphical user interfaces.</para></listitem>
82 <listitem><para><emphasis><filename>core-image-sato</filename>:</emphasis> 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 83 An image with Sato support, a mobile environment and visual style that works well
84 with mobile devices. 84 with mobile devices.
85 The image supports X11 with a Sato theme and applications such as 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> 86 a terminal, editor, file manager, media player, and so forth.</para></listitem>
87 <listitem><para><emphasis><filename>core-image-sato-dev</filename>:</emphasis> 87 <listitem><para><emphasis><filename>core-image-sato-dev</filename>:</emphasis>
88 A <filename>core-image-sato</filename> image suitable for development 88 A <filename>core-image-sato</filename> image suitable for development
89 using the host. 89 using the host.
90 The image includes libraries needed to build applications on the device itself, 90 The image includes libraries needed to build applications on the device itself,
91 testing and profiling tools, and debug symbols. 91 testing and profiling tools, and debug symbols.
92 This image was formerly <filename>core-image-sdk</filename>.</para></listitem> 92 This image was formerly <filename>core-image-sdk</filename>.</para></listitem>
93 <listitem><para><emphasis><filename>core-image-sato-sdk</filename>:</emphasis> 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. 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 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> 96 and is suitable for development using the target.</para></listitem>
97 <listitem><para><emphasis><filename>core-image-rt</filename>:</emphasis> 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 98 A <filename>core-image-minimal</filename> image plus a real-time test suite and
99 tools appropriate for real-time use.</para></listitem> 99 tools appropriate for real-time use.</para></listitem>
100 <listitem><para><emphasis><filename>core-image-rt-sdk</filename>:</emphasis> 100 <listitem><para><emphasis><filename>core-image-rt-sdk</filename>:</emphasis>
101 A <filename>core-image-rt</filename> image that includes everything in 101 A <filename>core-image-rt</filename> image that includes everything in
102 <filename>meta-toolchain</filename>. 102 <filename>meta-toolchain</filename>.
103 The image also includes development headers and libraries to form a complete 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> 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> 105 <listitem><para><emphasis><filename>core-image-gtk-directfb</filename>:</emphasis>
106 An image that uses <filename>gtk+</filename> over <filename>directfb</filename> 106 An image that uses <filename>gtk+</filename> over <filename>directfb</filename>
107 instead of X11. 107 instead of X11.
108 In order to build, this image requires specific distro configuration that enables 108 In order to build, this image requires specific distro configuration that enables
109 <filename>gtk</filename> over <filename>directfb</filename>.</para></listitem> 109 <filename>gtk</filename> over <filename>directfb</filename>.</para></listitem>
110 <listitem><para><emphasis><filename>build-appliance-image</filename>:</emphasis> 110 <listitem><para><emphasis><filename>build-appliance-image</filename>:</emphasis>
111 An image you can boot and run using either the 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> 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>. 113 or <ulink url='http://www.vmware.com/products/workstation/overview.html'>VMware Workstation</ulink>.
114 For more information on this image, see the 114 For more information on this image, see the
115 <ulink url='&YOCTO_HOME_URL;/documentation/build-appliance'>Build Appliance</ulink> page on 115 <ulink url='&YOCTO_HOME_URL;/documentation/build-appliance'>Build Appliance</ulink> page on
116 the Yocto Project website.</para></listitem> 116 the Yocto Project website.</para></listitem>
117 </itemizedlist> 117 </itemizedlist>
118 118
119 <tip> 119 <tip>
120 From the Yocto Project release 1.1 onwards, <filename>-live</filename> and 120 From the Yocto Project release 1.1 onwards, <filename>-live</filename> and
121 <filename>-directdisk</filename> images have been replaced by a "live" 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 122 option in <filename>IMAGE_FSTYPES</filename> that will work with any image to produce an
123 image file that can be 123 image file that can be
124 copied directly to a CD or USB device and run as is. 124 copied directly to a CD or USB device and run as is.
125 To build a live image, simply add 125 To build a live image, simply add
126 "live" to <filename>IMAGE_FSTYPES</filename> within the <filename>local.conf</filename> 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. 127 file or wherever appropriate and then build the desired image as normal.
128 </tip> 128 </tip>
129</chapter> 129</chapter>
130<!-- 130<!--
131vim: expandtab tw=80 ts=4 131vim: expandtab tw=80 ts=4
132--> 132-->
diff --git a/documentation/poky-ref-manual/ref-structure.xml b/documentation/poky-ref-manual/ref-structure.xml
index 166907ceef..673b05a52b 100644
--- a/documentation/poky-ref-manual/ref-structure.xml
+++ b/documentation/poky-ref-manual/ref-structure.xml
@@ -9,7 +9,7 @@
9<para> 9<para>
10 The <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> consists of several components. 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. 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 12 This chapter describes the Source Directory and gives information about the various
13 files and directories. 13 files and directories.
14</para> 14</para>
15 15
@@ -35,26 +35,26 @@
35 <para> 35 <para>
36 The <ulink url='source-directory'>Source Directory</ulink> 36 The <ulink url='source-directory'>Source Directory</ulink>
37 includes a copy of BitBake for ease of use. 37 includes a copy of BitBake for ease of use.
38 The copy usually matches the current stable BitBake release from the BitBake project. 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 39 BitBake, a metadata interpreter, reads the Yocto Project metadata and runs the tasks
40 defined by that data. 40 defined by that data.
41 Failures are usually from the metadata and not from BitBake itself. 41 Failures are usually from the metadata and not from BitBake itself.
42 Consequently, most users do not need to worry about BitBake. 42 Consequently, most users do not need to worry about BitBake.
43 </para> 43 </para>
44 44
45 <para> 45 <para>
46 When you run the <filename>bitbake</filename> command, the wrapper script in 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, 47 <filename>scripts/</filename> is executed to run the main BitBake executable,
48 which resides in the <filename>bitbake/bin/</filename> directory. 48 which resides in the <filename>bitbake/bin/</filename> directory.
49 Sourcing the <link linkend="structure-core-script">&OE_INIT_FILE;</link> 49 Sourcing the <link linkend="structure-core-script">&OE_INIT_FILE;</link>
50 script places the <filename>scripts</filename> and <filename>bitbake/bin</filename> 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 51 directories (in that order) into the shell's <filename>PATH</filename> environment
52 variable. 52 variable.
53 </para> 53 </para>
54 54
55 <para> 55 <para>
56 For more information on BitBake, see the BitBake documentation 56 For more information on BitBake, see the BitBake documentation
57 inculded in the <filename>bitbake/doc/manual</filename> directory of the 57 inculded in the <filename>bitbake/doc/manual</filename> directory of the
58 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. 58 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
59 </para> 59 </para>
60 </section> 60 </section>
@@ -63,21 +63,21 @@
63 <title><filename>build/</filename></title> 63 <title><filename>build/</filename></title>
64 64
65 <para> 65 <para>
66 This directory contains user configuration files and the output 66 This directory contains user configuration files and the output
67 generated by the OpenEmbedded build system in its standard configuration where 67 generated by the OpenEmbedded build system in its standard configuration where
68 the source tree is combined with the output. 68 the source tree is combined with the output.
69 The <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> 69 The <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
70 is created initially when you <filename>source</filename> 70 is created initially when you <filename>source</filename>
71 the OpenEmbedded build environment setup script <filename>&OE_INIT_FILE;</filename>. 71 the OpenEmbedded build environment setup script <filename>&OE_INIT_FILE;</filename>.
72 </para> 72 </para>
73 73
74 <para> 74 <para>
75 It is also possible to place output and configuration 75 It is also possible to place output and configuration
76 files in a directory separate from the 76 files in a directory separate from the
77 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> 77 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
78 by providing a directory name when you <filename>source</filename> 78 by providing a directory name when you <filename>source</filename>
79 the setup script. 79 the setup script.
80 For information on separating output from your local Source Directory files, see <link 80 For information on separating output from your local Source Directory files, see <link
81 linkend='structure-core-script'>&OE_INIT_FILE;</link>. 81 linkend='structure-core-script'>&OE_INIT_FILE;</link>.
82 </para> 82 </para>
83 </section> 83 </section>
@@ -88,9 +88,9 @@
88 <para> 88 <para>
89 This directory holds the source for the Yocto Project documentation 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 90 as well as templates and tools that allow you to generate PDF and HTML
91 versions of the manuals. 91 versions of the manuals.
92 Each manual is contained in a sub-folder. 92 Each manual is contained in a sub-folder.
93 For example, the files for this manual reside in 93 For example, the files for this manual reside in
94 <filename>poky-ref-manual</filename>. 94 <filename>poky-ref-manual</filename>.
95 </para> 95 </para>
96 </section> 96 </section>
@@ -99,7 +99,7 @@
99 <title><filename>meta/</filename></title> 99 <title><filename>meta/</filename></title>
100 100
101 <para> 101 <para>
102 This directory contains the OpenEmbedded Core metadata. 102 This directory contains the OpenEmbedded Core metadata.
103 The directory holds recipes, common classes, and machine 103 The directory holds recipes, common classes, and machine
104 configuration for emulated targets (qemux86, qemuarm, 104 configuration for emulated targets (qemux86, qemuarm,
105 and so on.) 105 and so on.)
@@ -138,7 +138,7 @@
138 <title><filename>meta-skeleton/</filename></title> 138 <title><filename>meta-skeleton/</filename></title>
139 139
140 <para> 140 <para>
141 This directory contains template recipes for BSP and kernel development. 141 This directory contains template recipes for BSP and kernel development.
142 </para> 142 </para>
143 </section> 143 </section>
144 144
@@ -146,7 +146,7 @@
146 <title><filename>scripts/</filename></title> 146 <title><filename>scripts/</filename></title>
147 147
148 <para> 148 <para>
149 This directory contains various integration scripts that implement 149 This directory contains various integration scripts that implement
150 extra functionality in the Yocto Project environment (e.g. QEMU scripts). 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 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. 152 directory to the shell's <filename>PATH</filename> environment variable.
@@ -154,7 +154,7 @@
154 154
155 <para> 155 <para>
156 The <filename>scripts</filename> directory has useful scripts that assist contributing 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 157 back to the Yocto Project, such as <filename>create_pull_request</filename> and
158 <filename>send_pull_request</filename>. 158 <filename>send_pull_request</filename>.
159 </para> 159 </para>
160 </section> 160 </section>
@@ -163,23 +163,23 @@
163 <title><filename>&OE_INIT_FILE;</filename></title> 163 <title><filename>&OE_INIT_FILE;</filename></title>
164 164
165 <para> 165 <para>
166 This script sets up the OpenEmbedded build environment. 166 This script sets up the OpenEmbedded build environment.
167 Running this script with the <filename>source</filename> command in 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 168 a shell makes changes to <filename>PATH</filename> and sets other core BitBake variables based on the
169 current working directory. 169 current working directory.
170 You need to run this script before running BitBake commands. 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 171 The script uses other scripts within the <filename>scripts</filename> directory to do
172 the bulk of the work. 172 the bulk of the work.
173 </para> 173 </para>
174 174
175 <para> 175 <para>
176 By default, running this script without a Build Directory argument creates the 176 By default, running this script without a Build Directory argument creates the
177 <filename>build</filename> directory. 177 <filename>build</filename> directory.
178 If you provide a Build Directory argument when you <filename>source</filename> 178 If you provide a Build Directory argument when you <filename>source</filename>
179 the script, you direct OpenEmbedded build system to create a 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. 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 181 For example, the following command creates a Build Directory named
182 <filename>mybuilds</filename> that is outside of the 182 <filename>mybuilds</filename> that is outside of the
183 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>: 183 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>:
184 <literallayout class='monospaced'> 184 <literallayout class='monospaced'>
185 $ source &OE_INIT_FILE; ~/mybuilds 185 $ source &OE_INIT_FILE; ~/mybuilds
@@ -189,7 +189,7 @@
189 contain spaces. 189 contain spaces.
190 If you attempt to run the <filename>&OE_INIT_FILE;</filename> script 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 191 from a Source Directory that contains spaces in either the filenames
192 or directory names, the script returns an error indicating no such 192 or directory names, the script returns an error indicating no such
193 file or directory. 193 file or directory.
194 Be sure to use a Source Directory free of names containing spaces. 194 Be sure to use a Source Directory free of names containing spaces.
195 </note> 195 </note>
@@ -200,7 +200,7 @@
200 <title><filename>LICENSE, README, and README.hardware</filename></title> 200 <title><filename>LICENSE, README, and README.hardware</filename></title>
201 201
202 <para> 202 <para>
203 These files are standard top-level files. 203 These files are standard top-level files.
204 </para> 204 </para>
205 </section> 205 </section>
206</section> 206</section>
@@ -212,8 +212,8 @@
212 <title><filename>build/pseudodone</filename></title> 212 <title><filename>build/pseudodone</filename></title>
213 213
214 <para> 214 <para>
215 This tag file indicates that the initial pseudo binary was created. 215 This tag file indicates that the initial pseudo binary was created.
216 The file is built the first time BitBake is invoked. 216 The file is built the first time BitBake is invoked.
217 </para> 217 </para>
218 </section> 218 </section>
219 219
@@ -221,24 +221,24 @@
221 <title><filename>build/conf/local.conf</filename></title> 221 <title><filename>build/conf/local.conf</filename></title>
222 222
223 <para> 223 <para>
224 This file contains all the local user configuration for your build environment. 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 225 If there is no <filename>local.conf</filename> present, it is created from
226 <filename>local.conf.sample</filename>. 226 <filename>local.conf.sample</filename>.
227 The <filename>local.conf</filename> file contains documentation on the various configuration options. 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 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 '?='). 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 230 Some variables are hard-coded for various reasons but these variables are
231 relatively rare. 231 relatively rare.
232 </para> 232 </para>
233 233
234 <para> 234 <para>
235 Edit this file to set the <filename><link linkend='var-MACHINE'>MACHINE</link></filename> 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 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>), 237 (<link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>),
238 where you want to downloaded files 238 where you want to downloaded files
239 (<filename><link linkend='var-DL_DIR'>DL_DIR</link></filename>), 239 (<filename><link linkend='var-DL_DIR'>DL_DIR</link></filename>),
240 and how you want your host machine to use resources 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 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>). 242 <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>).
243 </para> 243 </para>
244 </section> 244 </section>
@@ -248,8 +248,8 @@
248 248
249 <para> 249 <para>
250 This file defines layers, which are directory trees, traversed (or walked) by BitBake. 250 This file defines layers, which are directory trees, traversed (or walked) by BitBake.
251 If <filename>bblayers.conf</filename> 251 If <filename>bblayers.conf</filename>
252 is not present, it is created from <filename>bblayers.conf.sample</filename> when 252 is not present, it is created from <filename>bblayers.conf.sample</filename> when
253 you <filename>source</filename> the environment setup script. 253 you <filename>source</filename> the environment setup script.
254 </para> 254 </para>
255 255
@@ -276,7 +276,7 @@
276 276
277 <para> 277 <para>
278 This directory is used for the upstream source tarballs. 278 This directory is used for the upstream source tarballs.
279 The directory can be reused by multiple builds or moved to another location. 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 280 You can control the location of this directory through the
281 <filename><link linkend='var-DL_DIR'>DL_DIR</link></filename> variable. 281 <filename><link linkend='var-DL_DIR'>DL_DIR</link></filename> variable.
282 </para> 282 </para>
@@ -287,7 +287,7 @@
287 287
288 <para> 288 <para>
289 This directory is used for the shared state cache. 289 This directory is used for the shared state cache.
290 The directory can be reused by multiple builds or moved to another location. 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 291 You can control the location of this directory through the
292 <filename><link linkend='var-SSTATE_DIR'>SSTATE_DIR</link></filename> variable. 292 <filename><link linkend='var-SSTATE_DIR'>SSTATE_DIR</link></filename> variable.
293 </para> 293 </para>
@@ -298,9 +298,9 @@
298 298
299 <para> 299 <para>
300 This directory receives all the OpenEmbedded build system's output. 300 This directory receives all the OpenEmbedded build system's output.
301 BitBake creates this directory if it does not exist. 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), 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 303 you can remove everything in the <filename>tmp</filename> directory or get rid of the
304 directory completely. 304 directory completely.
305 If you do, you should also completely remove the <filename>build/sstate-cache</filename> 305 If you do, you should also completely remove the <filename>build/sstate-cache</filename>
306 directory as well. 306 directory as well.
@@ -320,7 +320,7 @@
320 320
321 <para> 321 <para>
322 When BitBake parses the metadata, it creates a cache file of the result that can 322 When BitBake parses the metadata, it creates a cache file of the result that can
323 be used when subsequently running commands. 323 be used when subsequently running commands.
324 These results are stored here on a per-machine basis. 324 These results are stored here on a per-machine basis.
325 </para> 325 </para>
326 </section> 326 </section>
@@ -337,7 +337,7 @@
337 <title><filename>build/tmp/deploy/deb/</filename></title> 337 <title><filename>build/tmp/deploy/deb/</filename></title>
338 338
339 <para> 339 <para>
340 This directory receives any <filename>.deb</filename> packages produced by 340 This directory receives any <filename>.deb</filename> packages produced by
341 the build process. 341 the build process.
342 The packages are sorted into feeds for different architecture types. 342 The packages are sorted into feeds for different architecture types.
343 </para> 343 </para>
@@ -347,8 +347,8 @@
347 <title><filename>build/tmp/deploy/rpm/</filename></title> 347 <title><filename>build/tmp/deploy/rpm/</filename></title>
348 348
349 <para> 349 <para>
350 This directory receives any <filename>.rpm</filename> packages produced by 350 This directory receives any <filename>.rpm</filename> packages produced by
351 the build process. 351 the build process.
352 The packages are sorted into feeds for different architecture types. 352 The packages are sorted into feeds for different architecture types.
353 </para> 353 </para>
354 </section> 354 </section>
@@ -368,16 +368,16 @@
368 <title><filename>build/tmp/deploy/images/</filename></title> 368 <title><filename>build/tmp/deploy/images/</filename></title>
369 369
370 <para> 370 <para>
371 This directory receives complete filesystem images. 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. 372 If you want to flash the resulting image from a build onto a device, look here for the image.
373 </para> 373 </para>
374 374
375 <para> 375 <para>
376 Be careful when deleting files in this directory. 376 Be careful when deleting files in this directory.
377 You can safely delete old images from this directory (e.g. 377 You can safely delete old images from this directory (e.g.
378 <filename>core-image-*</filename>, <filename>hob-image-*</filename>, 378 <filename>core-image-*</filename>, <filename>hob-image-*</filename>,
379 etc.). 379 etc.).
380 However, the kernel (<filename>*zImage*</filename>, <filename>*uImage*</filename>, 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 381 bootloader and other supplementary files might be deployed here prior to building an
382 image. 382 image.
383 Because these files, however, are not directly produced from the image, if you 383 Because these files, however, are not directly produced from the image, if you
@@ -385,8 +385,8 @@
385 </para> 385 </para>
386 386
387 <para> 387 <para>
388 If you do accidentally delete files here, you will need to force them to be 388 If you do accidentally delete files here, you will need to force them to be
389 re-created. 389 re-created.
390 In order to do that, you will need to know the target that produced them. 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: 391 For example, these commands rebuild and re-create the kernel files:
392 <literallayout class='monospaced'> 392 <literallayout class='monospaced'>
@@ -400,7 +400,7 @@
400 <title><filename>build/tmp/deploy/ipk/</filename></title> 400 <title><filename>build/tmp/deploy/ipk/</filename></title>
401 401
402 <para> 402 <para>
403 This directory receives <filename>.ipk</filename> packages produced by 403 This directory receives <filename>.ipk</filename> packages produced by
404 the build process.</para> 404 the build process.</para>
405 </section> 405 </section>
406 406
@@ -408,9 +408,9 @@
408 <title><filename>build/tmp/sysroots/</filename></title> 408 <title><filename>build/tmp/sysroots/</filename></title>
409 409
410 <para> 410 <para>
411 This directory contains shared header files and libraries as well as other shared 411 This directory contains shared header files and libraries as well as other shared
412 data. 412 data.
413 Packages that need to share output with other packages do so within this directory. 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 414 The directory is subdivided by architecture so multiple builds can run within
415 the one Build Directory. 415 the one Build Directory.
416 </para> 416 </para>
@@ -420,9 +420,9 @@
420 <title><filename>build/tmp/stamps/</filename></title> 420 <title><filename>build/tmp/stamps/</filename></title>
421 421
422 <para> 422 <para>
423 This directory holds information that that BitBake uses for accounting purposes 423 This directory holds information that that BitBake uses for accounting purposes
424 to track what tasks have run and when they have run. 424 to track what tasks have run and when they have run.
425 The directory is sub-divided by architecture. 425 The directory is sub-divided by architecture.
426 The files in the directory are empty of data. 426 The files in the directory are empty of data.
427 However, BitBake uses the filenames and timestamps for tracking purposes. 427 However, BitBake uses the filenames and timestamps for tracking purposes.
428 </para> 428 </para>
@@ -432,9 +432,9 @@
432 <title><filename>build/tmp/log/</filename></title> 432 <title><filename>build/tmp/log/</filename></title>
433 433
434 <para> 434 <para>
435 This directory contains general logs that are not otherwise placed using the 435 This directory contains general logs that are not otherwise placed using the
436 package's <filename><link linkend='var-WORKDIR'>WORKDIR</link></filename>. 436 package's <filename><link linkend='var-WORKDIR'>WORKDIR</link></filename>.
437 Examples of logs are the output from the <filename>check_pkg</filename> or 437 Examples of logs are the output from the <filename>check_pkg</filename> or
438 <filename>distro_check</filename> tasks. 438 <filename>distro_check</filename> tasks.
439 Running a build does not necessarily mean this directory is created. 439 Running a build does not necessarily mean this directory is created.
440 </para> 440 </para>
@@ -444,7 +444,7 @@
444 <title><filename>build/tmp/pkgdata/</filename></title> 444 <title><filename>build/tmp/pkgdata/</filename></title>
445 445
446 <para> 446 <para>
447 This directory contains intermediate packaging data that is used later in the packaging process. 447 This directory contains intermediate packaging data that is used later in the packaging process.
448 For more information, see the "<link linkend='ref-classes-package'>Packaging - package*.bbclass</link>" section. 448 For more information, see the "<link linkend='ref-classes-package'>Packaging - package*.bbclass</link>" section.
449 </para> 449 </para>
450 </section> 450 </section>
@@ -453,7 +453,7 @@
453 <title><filename>build/tmp/work/</filename></title> 453 <title><filename>build/tmp/work/</filename></title>
454 454
455 <para> 455 <para>
456 This directory contains architecture-specific work sub-directories for packages built by BitBake. 456 This directory contains architecture-specific work sub-directories for packages built by BitBake.
457 All tasks execute from a work directory. 457 All tasks execute from a work directory.
458 For example, the source for a particular package is unpacked, patched, configured and compiled all 458 For example, the source for a particular package is unpacked, patched, configured and compiled all
459 within its own work directory. 459 within its own work directory.
@@ -462,31 +462,31 @@
462 </para> 462 </para>
463 463
464 <para> 464 <para>
465 It is worth considering the structure of a typical work directory. 465 It is worth considering the structure of a typical work directory.
466 As an example, consider the <filename>linux-yocto-kernel-3.0</filename> 466 As an example, consider the <filename>linux-yocto-kernel-3.0</filename>
467 on the machine <filename>qemux86</filename> 467 on the machine <filename>qemux86</filename>
468 built within the Yocto Project. 468 built within the Yocto Project.
469 For this package, a work directory of 469 For this package, a work directory of
470 <filename>tmp/work/qemux86-poky-linux/linux-yocto-3.0+git1+&lt;.....&gt;</filename>, 470 <filename>tmp/work/qemux86-poky-linux/linux-yocto-3.0+git1+&lt;.....&gt;</filename>,
471 referred to as <filename><link linkend='var-WORKDIR'>WORKDIR</link></filename>, is created. 471 referred to as <filename><link linkend='var-WORKDIR'>WORKDIR</link></filename>, is created.
472 Within this directory, the source is unpacked to 472 Within this directory, the source is unpacked to
473 <filename>linux-qemux86-standard-build</filename> and then patched by Quilt 473 <filename>linux-qemux86-standard-build</filename> and then patched by Quilt
474 (see the 474 (see the
475 "<ulink url='&YOCTO_DOCS_DEV_URL;#using-a-quilt-workflow'>Modifying Package 475 "<ulink url='&YOCTO_DOCS_DEV_URL;#using-a-quilt-workflow'>Modifying Package
476 Source Code with Quilt</ulink>" section in the Yocto Project Development Manual. 476 Source Code with Quilt</ulink>" section in the Yocto Project Development Manual.
477 Within the <filename>linux-qemux86-standard-build</filename> directory, 477 Within the <filename>linux-qemux86-standard-build</filename> directory,
478 standard Quilt directories <filename>linux-3.0/patches</filename> 478 standard Quilt directories <filename>linux-3.0/patches</filename>
479 and <filename>linux-3.0/.pc</filename> are created, 479 and <filename>linux-3.0/.pc</filename> are created,
480 and standard Quilt commands can be used. 480 and standard Quilt commands can be used.
481 </para> 481 </para>
482 482
483 <para> 483 <para>
484 There are other directories generated within WORKDIR. 484 There are other directories generated within WORKDIR.
485 The most important directory is WORKDIR<filename>/temp/</filename>, which has log files for each 485 The most important directory is WORKDIR<filename>/temp/</filename>, which has log files for each
486 task (<filename>log.do_*.pid</filename>) and contains the scripts BitBake runs for 486 task (<filename>log.do_*.pid</filename>) and contains the scripts BitBake runs for
487 each task (<filename>run.do_*.pid</filename>). 487 each task (<filename>run.do_*.pid</filename>).
488 The WORKDIR<filename>/image/</filename> directory is where "make 488 The WORKDIR<filename>/image/</filename> directory is where "make
489 install" places its output that is then split into sub-packages 489 install" places its output that is then split into sub-packages
490 within WORKDIR<filename>/packages-split/</filename>. 490 within WORKDIR<filename>/packages-split/</filename>.
491 </para> 491 </para>
492 </section> 492 </section>
@@ -496,7 +496,7 @@
496 <title>The Metadata - <filename>meta/</filename></title> 496 <title>The Metadata - <filename>meta/</filename></title>
497 497
498 <para> 498 <para>
499 As mentioned previously, metadata is the core of the Yocto Project. 499 As mentioned previously, metadata is the core of the Yocto Project.
500 Metadata has several important subdivisions: 500 Metadata has several important subdivisions:
501 </para> 501 </para>
502 502
@@ -504,16 +504,16 @@
504 <title><filename>meta/classes/</filename></title> 504 <title><filename>meta/classes/</filename></title>
505 505
506 <para> 506 <para>
507 This directory contains the <filename>*.bbclass</filename> files. 507 This directory contains the <filename>*.bbclass</filename> files.
508 Class files are used to abstract common code so it can be reused by multiple 508 Class files are used to abstract common code so it can be reused by multiple
509 packages. 509 packages.
510 Every package inherits the <filename>base.bbclass</filename> file. 510 Every package inherits the <filename>base.bbclass</filename> file.
511 Examples of other important classes are <filename>autotools.bbclass</filename>, which 511 Examples of other important classes are <filename>autotools.bbclass</filename>, which
512 in theory allows any Autotool-enabled package to work with the Yocto Project with minimal effort. 512 in theory allows any Autotool-enabled package to work with the Yocto Project with minimal effort.
513 Another example is <filename>kernel.bbclass</filename> that contains common code and functions 513 Another example is <filename>kernel.bbclass</filename> that contains common code and functions
514 for working with the Linux kernel. 514 for working with the Linux kernel.
515 Functions like image generation or packaging also have their specific class files 515 Functions like image generation or packaging also have their specific class files
516 such as <filename>image.bbclass</filename>, <filename>rootfs_*.bbclass</filename> and 516 such as <filename>image.bbclass</filename>, <filename>rootfs_*.bbclass</filename> and
517 <filename>package*.bbclass</filename>. 517 <filename>package*.bbclass</filename>.
518 </para> 518 </para>
519 </section> 519 </section>
@@ -522,13 +522,13 @@
522 <title><filename>meta/conf/</filename></title> 522 <title><filename>meta/conf/</filename></title>
523 523
524 <para> 524 <para>
525 This directory contains the core set of configuration files that start from 525 This directory contains the core set of configuration files that start from
526 <filename>bitbake.conf</filename> and from which all other configuration 526 <filename>bitbake.conf</filename> and from which all other configuration
527 files are included. 527 files are included.
528 See the include statements at the end of the file and you will note that even 528 See the include statements at the end of the file and you will note that even
529 <filename>local.conf</filename> is loaded from there. 529 <filename>local.conf</filename> is loaded from there.
530 While <filename>bitbake.conf</filename> sets up the defaults, you can often override 530 While <filename>bitbake.conf</filename> sets up the defaults, you can often override
531 these by using the (<filename>local.conf</filename>) file, machine file or 531 these by using the (<filename>local.conf</filename>) file, machine file or
532 the distribution configuration file. 532 the distribution configuration file.
533 </para> 533 </para>
534 </section> 534 </section>
@@ -537,11 +537,11 @@
537 <title><filename>meta/conf/machine/</filename></title> 537 <title><filename>meta/conf/machine/</filename></title>
538 538
539 <para> 539 <para>
540 This directory contains all the machine configuration files. 540 This directory contains all the machine configuration files.
541 If you set <filename>MACHINE="qemux86"</filename>, 541 If you set <filename>MACHINE="qemux86"</filename>,
542 the OpenEmbedded build system looks for a <filename>qemux86.conf</filename> file in this 542 the OpenEmbedded build system looks for a <filename>qemux86.conf</filename> file in this
543 directory. 543 directory.
544 The <filename>include</filename> directory contains various data common to multiple machines. 544 The <filename>include</filename> directory contains various data common to multiple machines.
545 If you want to add support for a new machine to the Yocto Project, look in this directory. 545 If you want to add support for a new machine to the Yocto Project, look in this directory.
546 </para> 546 </para>
547 </section> 547 </section>
@@ -550,10 +550,10 @@
550 <title><filename>meta/conf/distro/</filename></title> 550 <title><filename>meta/conf/distro/</filename></title>
551 551
552 <para> 552 <para>
553 Any distribution-specific configuration is controlled from this directory. 553 Any distribution-specific configuration is controlled from this directory.
554 For the Yocto Project, the <filename>defaultsetup.conf</filename> is the main file here. 554 For the Yocto Project, the <filename>defaultsetup.conf</filename> is the main file here.
555 This directory includes the versions and the 555 This directory includes the versions and the
556 <filename>SRCDATE</filename> definitions for applications that are configured here. 556 <filename>SRCDATE</filename> definitions for applications that are configured here.
557 An example of an alternative configuration might be <filename>poky-bleeding.conf</filename>. 557 An example of an alternative configuration might be <filename>poky-bleeding.conf</filename>.
558 Although this file mainly inherits its configuration from Poky. 558 Although this file mainly inherits its configuration from Poky.
559 </para> 559 </para>
@@ -563,7 +563,7 @@
563 <title><filename>meta/recipes-bsp/</filename></title> 563 <title><filename>meta/recipes-bsp/</filename></title>
564 564
565 <para> 565 <para>
566 This directory contains anything linking to specific hardware or hardware 566 This directory contains anything linking to specific hardware or hardware
567 configuration information such as "u-boot" and "grub". 567 configuration information such as "u-boot" and "grub".
568 </para> 568 </para>
569 </section> 569 </section>
@@ -580,7 +580,7 @@
580 <title><filename>meta/recipes-core/</filename></title> 580 <title><filename>meta/recipes-core/</filename></title>
581 581
582 <para> 582 <para>
583 This directory contains what is needed to build a basic working Linux image 583 This directory contains what is needed to build a basic working Linux image
584 including commonly used dependencies. 584 including commonly used dependencies.
585 </para> 585 </para>
586 </section> 586 </section>
@@ -598,8 +598,8 @@
598 <title><filename>meta/recipes-extended/</filename></title> 598 <title><filename>meta/recipes-extended/</filename></title>
599 599
600 <para> 600 <para>
601 This directory contains non-essential applications that add features compared to the 601 This directory contains non-essential applications that add features compared to the
602 alternatives in core. 602 alternatives in core.
603 You might need this directory for full tool functionality or for Linux Standard Base (LSB) 603 You might need this directory for full tool functionality or for Linux Standard Base (LSB)
604 compliance. 604 compliance.
605 </para> 605 </para>
@@ -625,7 +625,7 @@
625 <title><filename>meta/recipes-kernel/</filename></title> 625 <title><filename>meta/recipes-kernel/</filename></title>
626 626
627 <para> 627 <para>
628 This directory contains the kernel and generic applications and libraries that 628 This directory contains the kernel and generic applications and libraries that
629 have strong kernel dependencies. 629 have strong kernel dependencies.
630 </para> 630 </para>
631 </section> 631 </section>
@@ -651,7 +651,7 @@
651 651
652 <para> 652 <para>
653 This directory contains package and image recipes for using and testing 653 This directory contains package and image recipes for using and testing
654 the <filename>PREEMPT_RT</filename> kernel. 654 the <filename>PREEMPT_RT</filename> kernel.
655 </para> 655 </para>
656 </section> 656 </section>
657 657
@@ -668,7 +668,7 @@
668 <title><filename>meta/recipes-support/</filename></title> 668 <title><filename>meta/recipes-support/</filename></title>
669 669
670 <para> 670 <para>
671 This directory contains recipes that used by other recipes, but that are not directly 671 This directory contains recipes that used by other recipes, but that are not directly
672 included in images (i.e. dependencies of other recipes). 672 included in images (i.e. dependencies of other recipes).
673 </para> 673 </para>
674 </section> 674 </section>
@@ -678,9 +678,9 @@
678 678
679 <para> 679 <para>
680 This directory contains a list of cached results for various architectures. 680 This directory contains a list of cached results for various architectures.
681 Because certain "autoconf" test results cannot be determined when cross-compiling due to 681 Because certain "autoconf" test results cannot be determined when cross-compiling due to
682 the tests not able to run on a live system, the information in this directory is 682 the tests not able to run on a live system, the information in this directory is
683 passed to "autoconf" for the various architectures. 683 passed to "autoconf" for the various architectures.
684 </para> 684 </para>
685 </section> 685 </section>
686 686
@@ -694,6 +694,6 @@
694</section> 694</section>
695 695
696</chapter> 696</chapter>
697<!-- 697<!--
698vim: expandtab tw=80 ts=4 698vim: expandtab tw=80 ts=4
699--> 699-->
diff --git a/documentation/poky-ref-manual/ref-variables.xml b/documentation/poky-ref-manual/ref-variables.xml
index 275a7465b8..03875132cc 100644
--- a/documentation/poky-ref-manual/ref-variables.xml
+++ b/documentation/poky-ref-manual/ref-variables.xml
@@ -16,48 +16,48 @@
16 16
17 17
18 <para> 18 <para>
19 <link linkend='var-ALLOW_EMPTY'>A</link> 19 <link linkend='var-ALLOW_EMPTY'>A</link>
20 <link linkend='var-B'>B</link> 20 <link linkend='var-B'>B</link>
21 <link linkend='var-CFLAGS'>C</link> 21 <link linkend='var-CFLAGS'>C</link>
22 <link linkend='var-D'>D</link> 22 <link linkend='var-D'>D</link>
23 <link linkend='var-ENABLE_BINARY_LOCALE_GENERATION'>E</link> 23 <link linkend='var-ENABLE_BINARY_LOCALE_GENERATION'>E</link>
24 <link linkend='var-FILES'>F</link> 24 <link linkend='var-FILES'>F</link>
25<!-- <link linkend='var-glossary-g'>G</link> --> 25<!-- <link linkend='var-glossary-g'>G</link> -->
26 <link linkend='var-HOMEPAGE'>H</link> 26 <link linkend='var-HOMEPAGE'>H</link>
27 <link linkend='var-IMAGE_FEATURES'>I</link> 27 <link linkend='var-IMAGE_FEATURES'>I</link>
28<!-- <link linkend='var-glossary-j'>J</link> --> 28<!-- <link linkend='var-glossary-j'>J</link> -->
29 <link linkend='var-KBRANCH'>K</link> 29 <link linkend='var-KBRANCH'>K</link>
30 <link linkend='var-LAYERDIR'>L</link> 30 <link linkend='var-LAYERDIR'>L</link>
31 <link linkend='var-MACHINE'>M</link> 31 <link linkend='var-MACHINE'>M</link>
32<!-- <link linkend='var-glossary-n'>N</link> --> 32<!-- <link linkend='var-glossary-n'>N</link> -->
33 <link linkend='var-OE_TERMINAL'>O</link> 33 <link linkend='var-OE_TERMINAL'>O</link>
34 <link linkend='var-P'>P</link> 34 <link linkend='var-P'>P</link>
35<!-- <link linkend='var-glossary-q'>Q</link> --> 35<!-- <link linkend='var-glossary-q'>Q</link> -->
36 <link linkend='var-RCONFLICTS'>R</link> 36 <link linkend='var-RCONFLICTS'>R</link>
37 <link linkend='var-S'>S</link> 37 <link linkend='var-S'>S</link>
38 <link linkend='var-T'>T</link> 38 <link linkend='var-T'>T</link>
39<!-- <link linkend='var-glossary-u'>U</link> --> 39<!-- <link linkend='var-glossary-u'>U</link> -->
40<!-- <link linkend='var-glossary-v'>V</link> --> 40<!-- <link linkend='var-glossary-v'>V</link> -->
41 <link linkend='var-WORKDIR'>W</link> 41 <link linkend='var-WORKDIR'>W</link>
42<!-- <link linkend='var-glossary-x'>X</link> --> 42<!-- <link linkend='var-glossary-x'>X</link> -->
43<!-- <link linkend='var-glossary-y'>Y</link> --> 43<!-- <link linkend='var-glossary-y'>Y</link> -->
44<!-- <link linkend='var-glossary-z'>Z</link>--> 44<!-- <link linkend='var-glossary-z'>Z</link>-->
45 </para> 45 </para>
46 46
47 <glossdiv id='var-glossary-a'><title>A</title> 47 <glossdiv id='var-glossary-a'><title>A</title>
48 48
49 <glossentry id='var-ALLOW_EMPTY'><glossterm>ALLOW_EMPTY</glossterm> 49 <glossentry id='var-ALLOW_EMPTY'><glossterm>ALLOW_EMPTY</glossterm>
50 <glossdef> 50 <glossdef>
51 <para> 51 <para>
52 Specifies if an output package should still be produced if it is empty. 52 Specifies if an output package should still be produced if it is empty.
53 By default, BitBake does not produce empty packages. 53 By default, BitBake does not produce empty packages.
54 This default behavior can cause issues when there is an 54 This default behavior can cause issues when there is an
55 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link> or 55 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link> or
56 some other runtime hard-requirement on the existence of the package. 56 some other runtime hard-requirement on the existence of the package.
57 </para> 57 </para>
58 58
59 <para> 59 <para>
60 Like all package-controlling variables, you must always use them in 60 Like all package-controlling variables, you must always use them in
61 conjunction with a package name override. 61 conjunction with a package name override.
62 Here is an example: 62 Here is an example:
63 <literallayout class='monospaced'> 63 <literallayout class='monospaced'>
@@ -69,7 +69,7 @@
69 69
70 <glossentry id='var-AUTHOR'><glossterm>AUTHOR</glossterm> 70 <glossentry id='var-AUTHOR'><glossterm>AUTHOR</glossterm>
71 <glossdef> 71 <glossdef>
72 <para>The email address used to contact the original author or authors in 72 <para>The email address used to contact the original author or authors in
73 order to send patches, forward bugs, etc.</para> 73 order to send patches, forward bugs, etc.</para>
74 </glossdef> 74 </glossdef>
75 </glossentry> 75 </glossentry>
@@ -86,7 +86,7 @@
86 </glossdef> 86 </glossdef>
87 </glossentry> 87 </glossentry>
88 88
89 </glossdiv> 89 </glossdiv>
90 90
91 <glossdiv id='var-glossary-b'><title>B</title> 91 <glossdiv id='var-glossary-b'><title>B</title>
92 92
@@ -101,7 +101,7 @@
101 <literallayout class='monospaced'> 101 <literallayout class='monospaced'>
102 B = ${WORKDIR}/${BPN}-{PV}/ 102 B = ${WORKDIR}/${BPN}-{PV}/
103 </literallayout> 103 </literallayout>
104 You can separate the (<filename>S</filename>) directory and the directory pointed to 104 You can separate the (<filename>S</filename>) directory and the directory pointed to
105 by the <filename>B</filename> variable. 105 by the <filename>B</filename> variable.
106 Most autotools-based recipes support separating these directories. 106 Most autotools-based recipes support separating these directories.
107 The build system defaults to using separate directories for <filename>gcc</filename> 107 The build system defaults to using separate directories for <filename>gcc</filename>
@@ -114,7 +114,7 @@
114 <glossdef> 114 <glossdef>
115 <para> 115 <para>
116 A list of packages not to install despite being recommended by a recipe. 116 A list of packages not to install despite being recommended by a recipe.
117 Support for this variable exists only when using the 117 Support for this variable exists only when using the
118 <filename>ipk</filename> packaging backend. 118 <filename>ipk</filename> packaging backend.
119 </para> 119 </para>
120 </glossdef> 120 </glossdef>
@@ -124,50 +124,50 @@
124 <glossdef> 124 <glossdef>
125 <para> 125 <para>
126 Monitors disk space and available inodes during the build 126 Monitors disk space and available inodes during the build
127 and allows you to control the build based on these 127 and allows you to control the build based on these
128 parameters. 128 parameters.
129 </para> 129 </para>
130 130
131 <para> 131 <para>
132 Disk space monitoring is disabled by default. 132 Disk space monitoring is disabled by default.
133 To enable monitoring, add the <filename>BB_DISKMON_DIRS</filename> 133 To enable monitoring, add the <filename>BB_DISKMON_DIRS</filename>
134 variable to your <filename>conf/local.conf</filename> file found in the 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>. 135 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
136 Use the following form: 136 Use the following form:
137 <literallayout class='monospaced'> 137 <literallayout class='monospaced'>
138 BB_DISKMON_DIRS = "&lt;action&gt;,&lt;dir&gt;,&lt;threshold&gt; [...]" 138 BB_DISKMON_DIRS = "&lt;action&gt;,&lt;dir&gt;,&lt;threshold&gt; [...]"
139 139
140 where: 140 where:
141 141
142 &lt;action&gt; is: 142 &lt;action&gt; is:
143 ABORT: Immediately abort the build when 143 ABORT: Immediately abort the build when
144 a threshold is broken. 144 a threshold is broken.
145 STOPTASKS: Stop the build after the currently 145 STOPTASKS: Stop the build after the currently
146 executing tasks have finished when 146 executing tasks have finished when
147 a threshold is broken. 147 a threshold is broken.
148 WARN: Issue a warning but continue the 148 WARN: Issue a warning but continue the
149 build when a threshold is broken. 149 build when a threshold is broken.
150 Subsequent warnings are issued as 150 Subsequent warnings are issued as
151 defined by the 151 defined by the
152 <link linkend='var-BB_DISKMON_WARNINTERVAL'>BB_DISKMON_WARNINTERVAL</link> variable, 152 <link linkend='var-BB_DISKMON_WARNINTERVAL'>BB_DISKMON_WARNINTERVAL</link> variable,
153 which must be defined in the 153 which must be defined in the
154 conf/local.conf file. 154 conf/local.conf file.
155 155
156 &lt;dir&gt; is: 156 &lt;dir&gt; is:
157 Any directory you choose. You can specify one or 157 Any directory you choose. You can specify one or
158 more directories to monitor by separating the 158 more directories to monitor by separating the
159 groupings with a space. If two directories are 159 groupings with a space. If two directories are
160 on the same device, only the first directory 160 on the same device, only the first directory
161 is monitored. 161 is monitored.
162 162
163 &lt;threshold&gt; is: 163 &lt;threshold&gt; is:
164 Either the minimum available disk space, 164 Either the minimum available disk space,
165 the minimum number of free inodes, or 165 the minimum number of free inodes, or
166 both. You must specify at least one. To 166 both. You must specify at least one. To
167 omit one or the other, simply omit the value. 167 omit one or the other, simply omit the value.
168 Specify the threshold using G, M, K for Gbytes, 168 Specify the threshold using G, M, K for Gbytes,
169 Mbytes, and Kbytes, respectively. If you do 169 Mbytes, and Kbytes, respectively. If you do
170 not specify G, M, or K, Kbytes is assumed by 170 not specify G, M, or K, Kbytes is assumed by
171 default. Do not use GB, MB, or KB. 171 default. Do not use GB, MB, or KB.
172 </literallayout> 172 </literallayout>
173 </para> 173 </para>
@@ -179,36 +179,36 @@
179 BB_DISKMON_DIRS = "STOPTASKS,${TMPDIR},1G" 179 BB_DISKMON_DIRS = "STOPTASKS,${TMPDIR},1G"
180 BB_DISKMON_DIRS = "ABORT,${TMPDIR},,100K" 180 BB_DISKMON_DIRS = "ABORT,${TMPDIR},,100K"
181 </literallayout> 181 </literallayout>
182 The first example works only if you also provide 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 183 the <link linkend='var-BB_DISKMON_WARNINTERVAL'><filename>BB_DISKMON_WARNINTERVAL</filename></link> variable
184 in the <filename>conf/local.conf</filename>. 184 in the <filename>conf/local.conf</filename>.
185 This example causes the build system to immediately 185 This example causes the build system to immediately
186 abort when either the disk space in <filename>${TMPDIR}</filename> drops 186 abort when either the disk space in <filename>${TMPDIR}</filename> drops
187 below 1 Gbyte or the available free inodes drops below 187 below 1 Gbyte or the available free inodes drops below
188 100 Kbytes. 188 100 Kbytes.
189 Because two directories are provided with the variable, the 189 Because two directories are provided with the variable, the
190 build system also issue a 190 build system also issue a
191 warning when the disk space in the 191 warning when the disk space in the
192 <filename>${SSTATE_DIR}</filename> directory drops 192 <filename>${SSTATE_DIR}</filename> directory drops
193 below 1 Gbyte or the number of free inodes drops 193 below 1 Gbyte or the number of free inodes drops
194 below 100 Kbytes. 194 below 100 Kbytes.
195 Subsequent warnings are issued during intervals as 195 Subsequent warnings are issued during intervals as
196 defined by the <filename>BB_DISKMON_WARNINTERVAL</filename> 196 defined by the <filename>BB_DISKMON_WARNINTERVAL</filename>
197 variable. 197 variable.
198 </para> 198 </para>
199 199
200 <para> 200 <para>
201 The second example stops the build after all currently 201 The second example stops the build after all currently
202 executing tasks complete when the minimum disk space 202 executing tasks complete when the minimum disk space
203 in the <filename>${TMPDIR}</filename> directory drops 203 in the <filename>${TMPDIR}</filename> directory drops
204 below 1 Gbyte. 204 below 1 Gbyte.
205 No disk monitoring occurs for the free inodes in this case. 205 No disk monitoring occurs for the free inodes in this case.
206 </para> 206 </para>
207 207
208 <para> 208 <para>
209 The final example immediately aborts the build when the 209 The final example immediately aborts the build when the
210 number of free inodes in the <filename>${TMPDIR}</filename> directory 210 number of free inodes in the <filename>${TMPDIR}</filename> directory
211 drops below 100 Kbytes. 211 drops below 100 Kbytes.
212 No disk space monitoring for the directory itself occurs 212 No disk space monitoring for the directory itself occurs
213 in this case. 213 in this case.
214 </para> 214 </para>
@@ -219,26 +219,26 @@
219 <glossdef> 219 <glossdef>
220 <para> 220 <para>
221 Defines the disk space and free inode warning intervals. 221 Defines the disk space and free inode warning intervals.
222 To set these intervals, define the variable in your 222 To set these intervals, define the variable in your
223 <filename>conf/local.conf</filename> file in the 223 <filename>conf/local.conf</filename> file in the
224 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. 224 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
225 </para> 225 </para>
226 226
227 <para> 227 <para>
228 If you are going to use the 228 If you are going to use the
229 <filename>BB_DISKMON_WARNINTERVAL</filename> variable, you must 229 <filename>BB_DISKMON_WARNINTERVAL</filename> variable, you must
230 also use the 230 also use the
231 <link linkend='var-BB_DISKMON_DIRS'><filename>BB_DISKMON_DIRS</filename></link> variable 231 <link linkend='var-BB_DISKMON_DIRS'><filename>BB_DISKMON_DIRS</filename></link> variable
232 and define its action as "WARN". 232 and define its action as "WARN".
233 During the build, subsequent warnings are issued each time 233 During the build, subsequent warnings are issued each time
234 disk space or number of free inodes further reduces by 234 disk space or number of free inodes further reduces by
235 the respective interval. 235 the respective interval.
236 </para> 236 </para>
237 237
238 <para> 238 <para>
239 If you do not provide a <filename>BB_DISKMON_WARNINTERVAL</filename> 239 If you do not provide a <filename>BB_DISKMON_WARNINTERVAL</filename>
240 variable and you do use <filename>BB_DISKMON_DIRS</filename> with 240 variable and you do use <filename>BB_DISKMON_DIRS</filename> with
241 the "WARN" action, the disk monitoring interval defaults to 241 the "WARN" action, the disk monitoring interval defaults to
242 the following: 242 the following:
243 <literallayout class='monospaced'> 243 <literallayout class='monospaced'>
244 BB_DISKMON_WARNINTERVAL = "50M,5K" 244 BB_DISKMON_WARNINTERVAL = "50M,5K"
@@ -246,22 +246,22 @@
246 </para> 246 </para>
247 247
248 <para> 248 <para>
249 When specifying the variable in your configuration file, 249 When specifying the variable in your configuration file,
250 use the following form: 250 use the following form:
251 <literallayout class='monospaced'> 251 <literallayout class='monospaced'>
252 BB_DISKMON_WARNINTERVAL = "&lt;disk_space_interval&gt;,&lt;disk_inode_interval&gt;" 252 BB_DISKMON_WARNINTERVAL = "&lt;disk_space_interval&gt;,&lt;disk_inode_interval&gt;"
253 253
254 where: 254 where:
255 255
256 &lt;disk_space_interval&gt; is: 256 &lt;disk_space_interval&gt; is:
257 An interval of memory expressed in either 257 An interval of memory expressed in either
258 G, M, or K for Gbytes, Mbytes, or Kbytes, 258 G, M, or K for Gbytes, Mbytes, or Kbytes,
259 respectively. You cannot use GB, MB, or KB. 259 respectively. You cannot use GB, MB, or KB.
260 260
261 &lt;disk_inode_interval&gt; is: 261 &lt;disk_inode_interval&gt; is:
262 An interval of free inodes expressed in either 262 An interval of free inodes expressed in either
263 G, M, or K for Gbytes, Mbytes, or Kbytes, 263 G, M, or K for Gbytes, Mbytes, or Kbytes,
264 respectively. You cannot use GB, MB, or KB. 264 respectively. You cannot use GB, MB, or KB.
265 </literallayout> 265 </literallayout>
266 </para> 266 </para>
267 267
@@ -271,12 +271,12 @@
271 BB_DISKMON_DIRS = "WARN,${SSTATE_DIR},1G,100K" 271 BB_DISKMON_DIRS = "WARN,${SSTATE_DIR},1G,100K"
272 BB_DISKMON_WARNINTERVAL = "50M,5K" 272 BB_DISKMON_WARNINTERVAL = "50M,5K"
273 </literallayout> 273 </literallayout>
274 These variables cause the OpenEmbedded build system to 274 These variables cause the OpenEmbedded build system to
275 issue subsequent warnings each time the available 275 issue subsequent warnings each time the available
276 disk space further reduces by 50 Mbytes or the number 276 disk space further reduces by 50 Mbytes or the number
277 of free inodes further reduces by 5 Kbytes in the 277 of free inodes further reduces by 5 Kbytes in the
278 <filename>${SSTATE_DIR}</filename> directory. 278 <filename>${SSTATE_DIR}</filename> directory.
279 Subsequent warnings based on the interval occur each time 279 Subsequent warnings based on the interval occur each time
280 a respective interval is reached beyond the intial warning 280 a respective interval is reached beyond the intial warning
281 (i.e. 1 Gbytes and 100 Kbytes). 281 (i.e. 1 Gbytes and 100 Kbytes).
282 </para> 282 </para>
@@ -310,24 +310,24 @@
310 <glossentry id='var-BBMASK'><glossterm>BBMASK</glossterm> 310 <glossentry id='var-BBMASK'><glossterm>BBMASK</glossterm>
311 <glossdef> 311 <glossdef>
312 <para>Prevents BitBake from processing recipes and recipe append files. 312 <para>Prevents BitBake from processing recipes and recipe append files.
313 You can use the <filename>BBMASK</filename> variable to "hide" 313 You can use the <filename>BBMASK</filename> variable to "hide"
314 these <filename>.bb</filename> and <filename>.bbappend</filename> files. 314 these <filename>.bb</filename> and <filename>.bbappend</filename> files.
315 BitBake ignores any recipe or recipe append files that match the expression. 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. 316 It is as if BitBake does not see them at all.
317 Consequently, matching files are not parsed or otherwise used by 317 Consequently, matching files are not parsed or otherwise used by
318 BitBake.</para> 318 BitBake.</para>
319 <para>The value you provide is passed to python's regular expression compiler. 319 <para>The value you provide is passed to python's regular expression compiler.
320 For complete syntax information, see python's documentation at 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>. 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. 322 The expression is compared against the full paths to the files.
323 For example, the following uses a complete regular expression to tell 323 For example, the following uses a complete regular expression to tell
324 BitBake to ignore all recipe and recipe append files in the 324 BitBake to ignore all recipe and recipe append files in the
325 <filename>.*/meta-ti/recipes-misc/</filename> directory: 325 <filename>.*/meta-ti/recipes-misc/</filename> directory:
326 <literallayout class='monospaced'> 326 <literallayout class='monospaced'>
327 BBMASK = ".*/meta-ti/recipes-misc/" 327 BBMASK = ".*/meta-ti/recipes-misc/"
328 </literallayout></para> 328 </literallayout></para>
329 <para>Use the <filename>BBMASK</filename> variable from within the 329 <para>Use the <filename>BBMASK</filename> variable from within the
330 <filename>conf/local.conf</filename> file found 330 <filename>conf/local.conf</filename> file found
331 in the <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.</para> 331 in the <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.</para>
332 </glossdef> 332 </glossdef>
333 </glossentry> 333 </glossentry>
@@ -342,9 +342,9 @@
342 342
343 <glossentry id='var-BBFILE_COLLECTIONS'><glossterm>BBFILE_COLLECTIONS</glossterm> 343 <glossentry id='var-BBFILE_COLLECTIONS'><glossterm>BBFILE_COLLECTIONS</glossterm>
344 <glossdef> 344 <glossdef>
345 <para>Lists the names of configured layers. 345 <para>Lists the names of configured layers.
346 These names are used to find the other <filename>BBFILE_*</filename> 346 These names are used to find the other <filename>BBFILE_*</filename>
347 variables. 347 variables.
348 Typically, each layer will append its name to this variable in its 348 Typically, each layer will append its name to this variable in its
349 <filename>conf/layer.conf</filename> file. 349 <filename>conf/layer.conf</filename> file.
350 </para> 350 </para>
@@ -353,9 +353,9 @@
353 353
354 <glossentry id='var-BBFILE_PATTERN'><glossterm>BBFILE_PATTERN</glossterm> 354 <glossentry id='var-BBFILE_PATTERN'><glossterm>BBFILE_PATTERN</glossterm>
355 <glossdef> 355 <glossdef>
356 <para>Variable that expands to match files from <filename>BBFILES</filename> in a particular layer. 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 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. 358 be suffixed with the name of the specific layer (e.g.
359 <filename>BBFILE_PATTERN_emenlow</filename>).</para> 359 <filename>BBFILE_PATTERN_emenlow</filename>).</para>
360 </glossdef> 360 </glossdef>
361 </glossentry> 361 </glossentry>
@@ -364,21 +364,21 @@
364 <glossdef> 364 <glossdef>
365 <para>Assigns the priority for recipe files in each layer.</para> 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 366 <para>This variable is useful in situations where the same recipe appears in
367 more than one layer. 367 more than one layer.
368 Setting this variable allows you to prioritize a 368 Setting this variable allows you to prioritize a
369 layer against other layers that contain the same recipe - effectively 369 layer against other layers that contain the same recipe - effectively
370 letting you control the precedence for the multiple layers. 370 letting you control the precedence for the multiple layers.
371 The precedence established through this variable stands regardless of a 371 The precedence established through this variable stands regardless of a
372 recipe's version (<filename>PV</filename> variable). 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 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 374 which the <filename>BBFILE_PRIORITY</filename> is set to have a lower precedence still has a
375 lower precedence.</para> 375 lower precedence.</para>
376 <para>A larger value for the <filename>BBFILE_PRIORITY</filename> variable results in a higher 376 <para>A larger value for the <filename>BBFILE_PRIORITY</filename> variable results in a higher
377 precedence. 377 precedence.
378 For example, the value 6 has a higher precedence than the value 5. 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 379 If not specified, the <filename>BBFILE_PRIORITY</filename> variable is set based on layer
380 dependencies (see the 380 dependencies (see the
381 <filename><link linkend='var-LAYERDEPENDS'>LAYERDEPENDS</link></filename> variable for 381 <filename><link linkend='var-LAYERDEPENDS'>LAYERDEPENDS</link></filename> variable for
382 more information. 382 more information.
383 The default priority, if unspecified 383 The default priority, if unspecified
384 for a layer with no dependencies, is the lowest defined priority + 1 384 for a layer with no dependencies, is the lowest defined priority + 1
@@ -398,7 +398,7 @@
398 398
399 <glossentry id='var-BBPATH'><glossterm>BBPATH</glossterm> 399 <glossentry id='var-BBPATH'><glossterm>BBPATH</glossterm>
400 <glossdef> 400 <glossdef>
401 <para>Used by BitBake to locate <filename>.bbclass</filename> and configuration files. 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> 402 This variable is analogous to the <filename>PATH</filename> variable.</para>
403 </glossdef> 403 </glossdef>
404 </glossentry> 404 </glossentry>
@@ -411,9 +411,9 @@
411 411
412 <glossentry id='var-BBLAYERS'><glossterm>BBLAYERS</glossterm> 412 <glossentry id='var-BBLAYERS'><glossterm>BBLAYERS</glossterm>
413 <glossdef> 413 <glossdef>
414 <para>Lists the layers to enable during the build. 414 <para>Lists the layers to enable during the build.
415 This variable is defined in the <filename>bblayers.conf</filename> configuration 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>. 416 file in the <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
417 Here is an example: 417 Here is an example:
418 <literallayout class='monospaced'> 418 <literallayout class='monospaced'>
419 BBLAYERS = " \ 419 BBLAYERS = " \
@@ -428,7 +428,7 @@
428 /home/scottrif/poky/meta-yocto \ 428 /home/scottrif/poky/meta-yocto \
429 " 429 "
430 </literallayout> 430 </literallayout>
431 This example enables four layers, one of which is a custom, user-defined layer 431 This example enables four layers, one of which is a custom, user-defined layer
432 named <filename>meta-mykernel</filename>. 432 named <filename>meta-mykernel</filename>.
433 </para> 433 </para>
434 </glossdef> 434 </glossdef>
@@ -464,7 +464,7 @@ Core layer for images cannot be removed
464 464
465 <glossentry id='var-BP'><glossterm>BP</glossterm> 465 <glossentry id='var-BP'><glossterm>BP</glossterm>
466 <glossdef> 466 <glossdef>
467 <para>The base recipe name and version but without any special 467 <para>The base recipe name and version but without any special
468 recipe name suffix (i.e. <filename>-native</filename>, <filename>lib64-</filename>, 468 recipe name suffix (i.e. <filename>-native</filename>, <filename>lib64-</filename>,
469 and so forth). 469 and so forth).
470 <filename>BP</filename> is comprised of the following: 470 <filename>BP</filename> is comprised of the following:
@@ -495,8 +495,8 @@ Core layer for images cannot be removed
495 <glossentry id='var-CFLAGS'><glossterm>CFLAGS</glossterm> 495 <glossentry id='var-CFLAGS'><glossterm>CFLAGS</glossterm>
496 <glossdef> 496 <glossdef>
497 <para> 497 <para>
498 Flags passed to C compiler for the target system. 498 Flags passed to C compiler for the target system.
499 This variable evaluates to the same as 499 This variable evaluates to the same as
500 <filename><link linkend='var-TARGET_CFLAGS'>TARGET_CFLAGS</link></filename>. 500 <filename><link linkend='var-TARGET_CFLAGS'>TARGET_CFLAGS</link></filename>.
501 </para> 501 </para>
502 </glossdef> 502 </glossdef>
@@ -504,7 +504,7 @@ Core layer for images cannot be removed
504 504
505 <glossentry id='var-COMBINED_FEATURES'><glossterm>COMBINED_FEATURES</glossterm> 505 <glossentry id='var-COMBINED_FEATURES'><glossterm>COMBINED_FEATURES</glossterm>
506 <glossdef> 506 <glossdef>
507 <para>A set of features common between 507 <para>A set of features common between
508 <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link> 508 <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link>
509 and <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_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> 510 See the glossary descriptions for these variables for more information.</para>
@@ -513,11 +513,11 @@ Core layer for images cannot be removed
513 513
514 <glossentry id='var-COMPATIBLE_MACHINE'><glossterm>COMPATIBLE_MACHINE</glossterm> 514 <glossentry id='var-COMPATIBLE_MACHINE'><glossterm>COMPATIBLE_MACHINE</glossterm>
515 <glossdef> 515 <glossdef>
516 <para>A regular expression which evaluates to match the machines the recipe 516 <para>A regular expression which evaluates to match the machines the recipe
517 works with. 517 works with.
518 It stops recipes being run on machines for which they are not compatible. 518 It stops recipes being run on machines for which they are not compatible.
519 This is particularly useful with kernels. 519 This is particularly useful with kernels.
520 It also helps to increase parsing speed as further parsing of the recipe is skipped 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> 521 if it is found the current machine is not compatible.</para>
522 </glossdef> 522 </glossdef>
523 </glossentry> 523 </glossentry>
@@ -527,46 +527,46 @@ Core layer for images cannot be removed
527 <para> 527 <para>
528 Identifies editable or configurable files that are part of a package. 528 Identifies editable or configurable files that are part of a package.
529 If the Package Management System (PMS) is being used to update 529 If the Package Management System (PMS) is being used to update
530 packages on the target system, it is possible that 530 packages on the target system, it is possible that
531 configuration files you have changed after the original installation 531 configuration files you have changed after the original installation
532 and that you now want to remain unchanged are overwritten. 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 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. 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 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. 536 package that you wish to prevent the PMS from overwriting during this update process.
537 </para> 537 </para>
538 538
539 <para> 539 <para>
540 To use the <filename>CONFFILES</filename> variable, provide a package name 540 To use the <filename>CONFFILES</filename> variable, provide a package name
541 override that identifies the resulting package. 541 override that identifies the resulting package.
542 Then, provide a space-separated list of files. 542 Then, provide a space-separated list of files.
543 Here is an example: 543 Here is an example:
544 <literallayout class='monospaced'> 544 <literallayout class='monospaced'>
545 CONFFILES_${PN} += "${sysconfdir}/file1 \ 545 CONFFILES_${PN} += "${sysconfdir}/file1 \
546 ${sysconfdir}/file2 ${sysconfdir}/file3" 546 ${sysconfdir}/file2 ${sysconfdir}/file3"
547 </literallayout> 547 </literallayout>
548 </para> 548 </para>
549 549
550 <para> 550 <para>
551 A relationship exists between the <filename>CONFFILES</filename> and 551 A relationship exists between the <filename>CONFFILES</filename> and
552 <filename><link linkend='var-FILES'>FILES</link></filename> variables. 552 <filename><link linkend='var-FILES'>FILES</link></filename> variables.
553 The files listed within <filename>CONFFILES</filename> must be a subset of 553 The files listed within <filename>CONFFILES</filename> must be a subset of
554 the files listed within <filename>FILES</filename>. 554 the files listed within <filename>FILES</filename>.
555 Because the configuration files you provide with <filename>CONFFILES</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, 556 are simply being identified so that the PMS will not overwrite them,
557 it makes sense that 557 it makes sense that
558 the files must already be included as part of the package through the 558 the files must already be included as part of the package through the
559 <filename>FILES</filename> variable. 559 <filename>FILES</filename> variable.
560 </para> 560 </para>
561 561
562 <note> 562 <note>
563 When specifying paths as part of the <filename>CONFFILES</filename> variable, 563 When specifying paths as part of the <filename>CONFFILES</filename> variable,
564 it is good practice to use appropriate path variables. 564 it is good practice to use appropriate path variables.
565 For example, <filename>${sysconfdir}</filename> rather than 565 For example, <filename>${sysconfdir}</filename> rather than
566 <filename>/etc</filename> or <filename>${bindir}</filename> rather 566 <filename>/etc</filename> or <filename>${bindir}</filename> rather
567 than <filename>/usr/bin</filename>. 567 than <filename>/usr/bin</filename>.
568 You can find a list of these variables at the top of the 568 You can find a list of these variables at the top of the
569 <filename>/meta/conf/bitbake.conf</filename> file in the 569 <filename>/meta/conf/bitbake.conf</filename> file in the
570 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. 570 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
571 </note> 571 </note>
572 </glossdef> 572 </glossdef>
@@ -575,9 +575,9 @@ Core layer for images cannot be removed
575 <glossentry id='var-CONFIG_SITE'><glossterm>CONFIG_SITE</glossterm> 575 <glossentry id='var-CONFIG_SITE'><glossterm>CONFIG_SITE</glossterm>
576 <glossdef> 576 <glossdef>
577 <para> 577 <para>
578 A list of files that contains <filename>autoconf</filename> test results relevant 578 A list of files that contains <filename>autoconf</filename> test results relevant
579 to the current build. 579 to the current build.
580 This variable is used by the Autotools utilities when running 580 This variable is used by the Autotools utilities when running
581 <filename>configure</filename>. 581 <filename>configure</filename>.
582 </para> 582 </para>
583 </glossdef> 583 </glossdef>
@@ -586,9 +586,9 @@ Core layer for images cannot be removed
586 <glossentry id='var-CORE_IMAGE_EXTRA_INSTALL'><glossterm>CORE_IMAGE_EXTRA_INSTALL</glossterm> 586 <glossentry id='var-CORE_IMAGE_EXTRA_INSTALL'><glossterm>CORE_IMAGE_EXTRA_INSTALL</glossterm>
587 <glossdef> 587 <glossdef>
588 <para> 588 <para>
589 Specifies the list of packages to be added to the image. 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> 590 This variable should only be set in the <filename>local.conf</filename>
591 configuration file found in the 591 configuration file found in the
592 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. 592 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
593 </para> 593 </para>
594 594
@@ -611,9 +611,9 @@ Core layer for images cannot be removed
611 <glossentry id='var-DEBUG_BUILD'><glossterm>DEBUG_BUILD</glossterm> 611 <glossentry id='var-DEBUG_BUILD'><glossterm>DEBUG_BUILD</glossterm>
612 <glossdef> 612 <glossdef>
613 <para> 613 <para>
614 Specifies to build packages with debugging information. 614 Specifies to build packages with debugging information.
615 This influences the value of the 615 This influences the value of the
616 <filename><link linkend='var-SELECTED_OPTIMIZATION'>SELECTED_OPTIMIZATION</link></filename> 616 <filename><link linkend='var-SELECTED_OPTIMIZATION'>SELECTED_OPTIMIZATION</link></filename>
617 variable. 617 variable.
618 </para> 618 </para>
619 </glossdef> 619 </glossdef>
@@ -622,9 +622,9 @@ Core layer for images cannot be removed
622 <glossentry id='var-DEBUG_OPTIMIZATION'><glossterm>DEBUG_OPTIMIZATION</glossterm> 622 <glossentry id='var-DEBUG_OPTIMIZATION'><glossterm>DEBUG_OPTIMIZATION</glossterm>
623 <glossdef> 623 <glossdef>
624 <para> 624 <para>
625 The options to pass in 625 The options to pass in
626 <filename><link linkend='var-TARGET_CFLAGS'>TARGET_CFLAGS</link></filename> 626 <filename><link linkend='var-TARGET_CFLAGS'>TARGET_CFLAGS</link></filename>
627 and <filename><link linkend='var-CFLAGS'>CFLAGS</link></filename> when compiling 627 and <filename><link linkend='var-CFLAGS'>CFLAGS</link></filename> when compiling
628 a system for debugging. 628 a system for debugging.
629 This variable defaults to "-O -fno-omit-frame-pointer -g". 629 This variable defaults to "-O -fno-omit-frame-pointer -g".
630 </para> 630 </para>
@@ -641,9 +641,9 @@ Core layer for images cannot be removed
641 <glossdef> 641 <glossdef>
642 <para> 642 <para>
643 Lists a recipe's build-time dependencies 643 Lists a recipe's build-time dependencies
644 (i.e. other recipe files). 644 (i.e. other recipe files).
645 The system ensures that all the dependencies listed 645 The system ensures that all the dependencies listed
646 have been built and have their contents in the appropriate 646 have been built and have their contents in the appropriate
647 sysroots before the recipe's configure task is executed. 647 sysroots before the recipe's configure task is executed.
648 </para> 648 </para>
649 </glossdef> 649 </glossdef>
@@ -652,8 +652,8 @@ Core layer for images cannot be removed
652 <glossentry id='var-DESCRIPTION'><glossterm>DESCRIPTION</glossterm> 652 <glossentry id='var-DESCRIPTION'><glossterm>DESCRIPTION</glossterm>
653 <glossdef> 653 <glossdef>
654 <para>The package description used by package managers. 654 <para>The package description used by package managers.
655 If not set, <filename>DESCRIPTION</filename> takes 655 If not set, <filename>DESCRIPTION</filename> takes
656 the value of the 656 the value of the
657 <link linkend='var-SUMMARY'><filename>SUMMARY</filename></link> 657 <link linkend='var-SUMMARY'><filename>SUMMARY</filename></link>
658 variable. 658 variable.
659 </para> 659 </para>
@@ -669,11 +669,11 @@ Core layer for images cannot be removed
669 <glossentry id='var-DISTRO'><glossterm>DISTRO</glossterm> 669 <glossentry id='var-DISTRO'><glossterm>DISTRO</glossterm>
670 <glossdef> 670 <glossdef>
671 <para> 671 <para>
672 The short name of the distribution. 672 The short name of the distribution.
673 This variable corresponds to a file with the 673 This variable corresponds to a file with the
674 extension <filename>.conf</filename> 674 extension <filename>.conf</filename>
675 located in a <filename>conf/distro</filename> directory 675 located in a <filename>conf/distro</filename> directory
676 within the metadata that contains the distribution configuration. 676 within the metadata that contains the distribution configuration.
677 The 677 The
678 value must not contain spaces, and is typically all lower-case. 678 value must not contain spaces, and is typically all lower-case.
679 </para> 679 </para>
@@ -689,11 +689,11 @@ Core layer for images cannot be removed
689 <glossdef> 689 <glossdef>
690 <para> 690 <para>
691 Specifies a list of distro-specific packages to add to all images. 691 Specifies a list of distro-specific packages to add to all images.
692 This variable takes affect through 692 This variable takes affect through
693 <filename>packagegroup-base</filename> so the 693 <filename>packagegroup-base</filename> so the
694 variable only really applies to the more full-featured 694 variable only really applies to the more full-featured
695 images that include <filename>packagegroup-base</filename>. 695 images that include <filename>packagegroup-base</filename>.
696 You can use this variable to keep distro policy out of 696 You can use this variable to keep distro policy out of
697 generic images. 697 generic images.
698 As with all other distro variables, you set this variable 698 As with all other distro variables, you set this variable
699 in the distro <filename>.conf</filename> file. 699 in the distro <filename>.conf</filename> file.
@@ -704,10 +704,10 @@ Core layer for images cannot be removed
704 <glossentry id='var-DISTRO_EXTRA_RRECOMMENDS'><glossterm>DISTRO_EXTRA_RRECOMMENDS</glossterm> 704 <glossentry id='var-DISTRO_EXTRA_RRECOMMENDS'><glossterm>DISTRO_EXTRA_RRECOMMENDS</glossterm>
705 <glossdef> 705 <glossdef>
706 <para> 706 <para>
707 Specifies a list of distro-specific packages to add to all images 707 Specifies a list of distro-specific packages to add to all images
708 if the packages exist. 708 if the packages exist.
709 The packages might not exist or be empty (e.g. kernel modules). 709 The packages might not exist or be empty (e.g. kernel modules).
710 The list of packages are automatically installed but can be 710 The list of packages are automatically installed but can be
711 removed by the user. 711 removed by the user.
712 </para> 712 </para>
713 </glossdef> 713 </glossdef>
@@ -725,18 +725,18 @@ Core layer for images cannot be removed
725 725
726 <glossentry id='var-DISTRO_FEATURES_BACKFILL'><glossterm>DISTRO_FEATURES_BACKFILL</glossterm> 726 <glossentry id='var-DISTRO_FEATURES_BACKFILL'><glossterm>DISTRO_FEATURES_BACKFILL</glossterm>
727 <glossdef> 727 <glossdef>
728 <para>Features to be added to 728 <para>Features to be added to
729 <filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename> 729 <filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename>
730 if not also present in 730 if not also present in
731 <filename><link linkend='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'>DISTRO_FEATURES_BACKFILL_CONSIDERED</link></filename>. 731 <filename><link linkend='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'>DISTRO_FEATURES_BACKFILL_CONSIDERED</link></filename>.
732 </para> 732 </para>
733 733
734 <para> 734 <para>
735 This variable is set in the <filename>meta/conf/bitbake.conf</filename> file. 735 This variable is set in the <filename>meta/conf/bitbake.conf</filename> file.
736 It is not intended to be user-configurable. 736 It is not intended to be user-configurable.
737 It is best to just reference the variable to see which distro features are 737 It is best to just reference the variable to see which distro features are
738 being backfilled for all distro configurations. 738 being backfilled for all distro configurations.
739 See the <link linkend='ref-features-backfill'>Feature backfilling</link> section for 739 See the <link linkend='ref-features-backfill'>Feature backfilling</link> section for
740 more information. 740 more information.
741 </para> 741 </para>
742 </glossdef> 742 </glossdef>
@@ -749,7 +749,7 @@ Core layer for images cannot be removed
749 that should not backfilled (i.e. added to 749 that should not backfilled (i.e. added to
750 <filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename>) 750 <filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename>)
751 during the build. 751 during the build.
752 See the "<link linkend='ref-features-backfill'>Feature Backfilling</link>" section for 752 See the "<link linkend='ref-features-backfill'>Feature Backfilling</link>" section for
753 more information. 753 more information.
754 </para> 754 </para>
755 </glossdef> 755 </glossdef>
@@ -764,9 +764,9 @@ Core layer for images cannot be removed
764 <glossentry id='var-DISTRO_PN_ALIAS'><glossterm>DISTRO_PN_ALIAS</glossterm> 764 <glossentry id='var-DISTRO_PN_ALIAS'><glossterm>DISTRO_PN_ALIAS</glossterm>
765 <glossdef> 765 <glossdef>
766 <para>Alias names used for the recipe in various Linux distributions.</para> 766 <para>Alias names used for the recipe in various Linux distributions.</para>
767 <para>See the 767 <para>See the
768 "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-configuring-DISTRO_PN_ALIAS'>Handling 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 769 a Package Name Alias</ulink>" section in the Yocto Project Development
770 Manual for more information.</para> 770 Manual for more information.</para>
771 </glossdef> 771 </glossdef>
772 </glossentry> 772 </glossentry>
@@ -784,8 +784,8 @@ Core layer for images cannot be removed
784 You can set this directory by defining the <filename>DL_DIR</filename> 784 You can set this directory by defining the <filename>DL_DIR</filename>
785 variable in the <filename>/conf/local.conf</filename> file. 785 variable in the <filename>/conf/local.conf</filename> file.
786 This directory is self-maintaining and you should not have 786 This directory is self-maintaining and you should not have
787 to touch it. 787 to touch it.
788 By default, the directory is <filename>downloads</filename> in the 788 By default, the directory is <filename>downloads</filename> in the
789 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. 789 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
790 <literallayout class='monospaced'> 790 <literallayout class='monospaced'>
791 #DL_DIR ?= "${TOPDIR}/downloads" 791 #DL_DIR ?= "${TOPDIR}/downloads"
@@ -795,22 +795,22 @@ Core layer for images cannot be removed
795 </para> 795 </para>
796 796
797 <para> 797 <para>
798 During a first build, the system downloads many different source code 798 During a first build, the system downloads many different source code
799 tarballs from various upstream projects. 799 tarballs from various upstream projects.
800 Downloading can take a while, particularly if your network 800 Downloading can take a while, particularly if your network
801 connection is slow. 801 connection is slow.
802 Tarballs are all stored in the directory defined by 802 Tarballs are all stored in the directory defined by
803 <filename>DL_DIR</filename> and the build system looks there first 803 <filename>DL_DIR</filename> and the build system looks there first
804 to find source tarballs. 804 to find source tarballs.
805 <note> 805 <note>
806 When wiping and rebuilding, you can preserve this directory to speed 806 When wiping and rebuilding, you can preserve this directory to speed
807 up this part of subsequent builds. 807 up this part of subsequent builds.
808 </note> 808 </note>
809 </para> 809 </para>
810 810
811 <para> 811 <para>
812 You can safely share this directory between multiple builds on the 812 You can safely share this directory between multiple builds on the
813 same development machine. 813 same development machine.
814 For additional information on how the build process gets source files 814 For additional information on how the build process gets source files
815 when working behind a firewall or proxy server, see the 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>" 816 "<link linkend='how-does-the-yocto-project-obtain-source-code-and-will-it-work-behind-my-firewall-or-proxy-server'>FAQ</link>"
@@ -836,15 +836,15 @@ Core layer for images cannot be removed
836 <glossdef> 836 <glossdef>
837 <para> 837 <para>
838 Used with file and pathnames to create a prefix for a recipe's 838 Used with file and pathnames to create a prefix for a recipe's
839 version based on the recipe's 839 version based on the recipe's
840 <link linkend='var-PE'><filename>PE</filename></link> value. 840 <link linkend='var-PE'><filename>PE</filename></link> value.
841 If <filename>PE</filename> is set and greater than zero for a recipe, 841 If <filename>PE</filename> is set and greater than zero for a recipe,
842 <filename>EXTENDPE</filename> becomes that value (e.g if 842 <filename>EXTENDPE</filename> becomes that value (e.g if
843 <filename>PE</filename> is equal to "1" then <filename>EXTENDPE</filename> 843 <filename>PE</filename> is equal to "1" then <filename>EXTENDPE</filename>
844 becomes "1_"). 844 becomes "1_").
845 If a recipe's <filename>PE</filename> is not set (the default) or is equal to 845 If a recipe's <filename>PE</filename> is not set (the default) or is equal to
846 zero, <filename>EXTENDPE</filename> becomes "".</para> 846 zero, <filename>EXTENDPE</filename> becomes "".</para>
847 <para>See the <link linkend='var-STAMP'><filename>STAMP</filename></link> 847 <para>See the <link linkend='var-STAMP'><filename>STAMP</filename></link>
848 variable for an example. 848 variable for an example.
849 </para> 849 </para>
850 </glossdef> 850 </glossdef>
@@ -855,38 +855,38 @@ Core layer for images cannot be removed
855 <para>Allows extra packages to be added to the generated images. 855 <para>Allows extra packages to be added to the generated images.
856 You set this variable in the <filename>local.conf</filename> 856 You set this variable in the <filename>local.conf</filename>
857 configuration file. 857 configuration file.
858 Note that some image features are also added using the 858 Note that some image features are also added using the
859 <filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename> 859 <filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename>
860 variable generally configured in image recipes. 860 variable generally configured in image recipes.
861 You can use this variable to add more features in addition to those. 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> 862 Here are some examples of features you can add:</para>
863 <literallayout class='monospaced'> 863 <literallayout class='monospaced'>
864"dbg-pkgs" - Adds -dbg packages for all installed packages 864"dbg-pkgs" - Adds -dbg packages for all installed packages
865 including symbol information for debugging and 865 including symbol information for debugging and
866 profiling. 866 profiling.
867 867
868"dev-pkgs" - Adds -dev packages for all installed packages. 868"dev-pkgs" - Adds -dev packages for all installed packages.
869 This is useful if you want to develop against 869 This is useful if you want to develop against
870 the libraries in the image. 870 the libraries in the image.
871 871
872"tools-sdk" - Adds development tools such as gcc, make, 872"tools-sdk" - Adds development tools such as gcc, make,
873 pkgconfig and so forth. 873 pkgconfig and so forth.
874 874
875"tools-debug" - Adds debugging tools such as gdb and 875"tools-debug" - Adds debugging tools such as gdb and
876 strace. 876 strace.
877 877
878"tools-profile" - Adds profiling tools such as oprofile, 878"tools-profile" - Adds profiling tools such as oprofile,
879 exmap, lttng and valgrind (x86 only). 879 exmap, lttng and valgrind (x86 only).
880 880
881"tools-testapps" - Adds useful testing tools such as 881"tools-testapps" - Adds useful testing tools such as
882 ts_print, aplay, arecord and so 882 ts_print, aplay, arecord and so
883 forth. 883 forth.
884 884
885"debug-tweaks" - Makes an image suitable for development. 885"debug-tweaks" - Makes an image suitable for development.
886 For example, ssh root access has a blank 886 For example, ssh root access has a blank
887 password. You should remove this feature 887 password. You should remove this feature
888 before you produce a production image. 888 before you produce a production image.
889 </literallayout> 889 </literallayout>
890 890
891 <para>There are other valid features too, see the 891 <para>There are other valid features too, see the
892 <link linkend='ref-features-image'>Images</link> 892 <link linkend='ref-features-image'>Images</link>
@@ -901,12 +901,12 @@ Core layer for images cannot be removed
901 </para> 901 </para>
902 <para>Sometimes a recipe is required to build the final image but is not 902 <para>Sometimes a recipe is required to build the final image but is not
903 needed in the root filesystem. 903 needed in the root filesystem.
904 You can use the <filename>EXTRA_IMAGEDEPENDS</filename> variable to 904 You can use the <filename>EXTRA_IMAGEDEPENDS</filename> variable to
905 list these recipes and thus, specify the dependencies. 905 list these recipes and thus, specify the dependencies.
906 A typical example is a required bootloader in a machine configuration. 906 A typical example is a required bootloader in a machine configuration.
907 </para> 907 </para>
908 <note> 908 <note>
909 To add packages to the root filesystem, see the various 909 To add packages to the root filesystem, see the various
910 <filename>*DEPENDS</filename> and <filename>*RECOMMENDS</filename> 910 <filename>*DEPENDS</filename> and <filename>*RECOMMENDS</filename>
911 variables. 911 variables.
912 </note> 912 </note>
@@ -944,32 +944,32 @@ Core layer for images cannot be removed
944 <para> 944 <para>
945 To use the <filename>FILES</filename> variable, provide a package name 945 To use the <filename>FILES</filename> variable, provide a package name
946 override that identifies the resulting package. 946 override that identifies the resulting package.
947 Then, provide a space-separated list of files or paths that identifies the 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. 948 files you want included as part of the resulting package.
949 Here is an example: 949 Here is an example:
950 <literallayout class='monospaced'> 950 <literallayout class='monospaced'>
951 FILES_${PN} += "${bindir}/mydir1/ ${bindir}/mydir2/myfile" 951 FILES_${PN} += "${bindir}/mydir1/ ${bindir}/mydir2/myfile"
952 </literallayout> 952 </literallayout>
953 </para> 953 </para>
954 954
955 <note> 955 <note>
956 When specifying paths as part of the <filename>FILES</filename> variable, 956 When specifying paths as part of the <filename>FILES</filename> variable,
957 it is good practice to use appropriate path variables. 957 it is good practice to use appropriate path variables.
958 For example, <filename>${sysconfdir}</filename> rather than 958 For example, <filename>${sysconfdir}</filename> rather than
959 <filename>/etc</filename> or <filename>${bindir}</filename> rather 959 <filename>/etc</filename> or <filename>${bindir}</filename> rather
960 than <filename>/usr/bin</filename>. 960 than <filename>/usr/bin</filename>.
961 You can find a list of these variables at the top of the 961 You can find a list of these variables at the top of the
962 <filename>/meta/conf/bitbake.conf</filename> file in the 962 <filename>/meta/conf/bitbake.conf</filename> file in the
963 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. 963 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
964 </note> 964 </note>
965 965
966 <para> 966 <para>
967 If some of the files you provide with the <filename>FILES</filename> variable 967 If some of the files you provide with the <filename>FILES</filename> variable
968 are editable and you know they should not be 968 are editable and you know they should not be
969 overwritten during the package update process by the Package Management 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 970 System (PMS), you can identify these files so that the PMS will not
971 overwrite them. 971 overwrite them.
972 See the <filename><link linkend='var-CONFFILES'>CONFFILES</link></filename> 972 See the <filename><link linkend='var-CONFFILES'>CONFFILES</link></filename>
973 variable for information on how to identify these files to the PMS. 973 variable for information on how to identify these files to the PMS.
974 </para> 974 </para>
975 975
@@ -979,11 +979,11 @@ Core layer for images cannot be removed
979 <glossentry id='var-FILESEXTRAPATHS'><glossterm>FILESEXTRAPATHS</glossterm> 979 <glossentry id='var-FILESEXTRAPATHS'><glossterm>FILESEXTRAPATHS</glossterm>
980 <glossdef> 980 <glossdef>
981 <para> 981 <para>
982 Extends the search path the OpenEmbedded build system uses when 982 Extends the search path the OpenEmbedded build system uses when
983 looking for files and patches as it processes recipes. 983 looking for files and patches as it processes recipes.
984 The directories BitBake uses when it processes recipes is defined by the 984 The directories BitBake uses when it processes recipes is defined by the
985 <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link> variable. 985 <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link> variable.
986 You can add directories to the search path by defining the 986 You can add directories to the search path by defining the
987 <filename>FILESEXTRAPATHS</filename> variable. 987 <filename>FILESEXTRAPATHS</filename> variable.
988 </para> 988 </para>
989 989
@@ -993,17 +993,17 @@ Core layer for images cannot be removed
993 <literallayout class='monospaced'> 993 <literallayout class='monospaced'>
994 FILESEXTRAPATHS_prepend := "path_1:path_2:path_3:" 994 FILESEXTRAPATHS_prepend := "path_1:path_2:path_3:"
995 </literallayout> 995 </literallayout>
996 Typically, you want your directories searched first. 996 Typically, you want your directories searched first.
997 To make sure that happens, use <filename>_prepend</filename> and 997 To make sure that happens, use <filename>_prepend</filename> and
998 the immediate expansion (<filename>:=</filename>) operator as shown in the 998 the immediate expansion (<filename>:=</filename>) operator as shown in the
999 previous example. 999 previous example.
1000 Finally, to maintain the integrity of the <filename>FILESPATH</filename> variable, 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. 1001 you must include the appropriate beginning or ending (as needed) colon character.
1002 </para> 1002 </para>
1003 1003
1004 <para> 1004 <para>
1005 The <filename>FILESEXTRAPATHS</filename> variable is intended for use in 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. 1006 <filename>.bbappend</filename> files to include any additional files provided in that layer.
1007 You typically accomplish this with the following: 1007 You typically accomplish this with the following:
1008 <literallayout class='monospaced'> 1008 <literallayout class='monospaced'>
1009 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" 1009 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
@@ -1017,15 +1017,15 @@ Core layer for images cannot be removed
1017 <para> 1017 <para>
1018 The default set of directories the OpenEmbedded build system uses 1018 The default set of directories the OpenEmbedded build system uses
1019 when searching for patches and files. 1019 when searching for patches and files.
1020 During the build process, BitBake searches each directory in 1020 During the build process, BitBake searches each directory in
1021 <filename>FILESPATH</filename> in the specified order when looking for 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. 1022 files and patches specified by each <filename>file://</filename> URI in a recipe.
1023 </para> 1023 </para>
1024 1024
1025 <para> 1025 <para>
1026 The default value for the <filename>FILESPATH</filename> variable is defined 1026 The default value for the <filename>FILESPATH</filename> variable is defined
1027 in the <filename>base.bbclass</filename> class found in 1027 in the <filename>base.bbclass</filename> class found in
1028 <filename>meta/classes</filename> in the 1028 <filename>meta/classes</filename> in the
1029 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>: 1029 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>:
1030 <literallayout class='monospaced'> 1030 <literallayout class='monospaced'>
1031FILESPATH = "${@base_set_filespath([ "${FILE_DIRNAME}/${PF}", \ 1031FILESPATH = "${@base_set_filespath([ "${FILE_DIRNAME}/${PF}", \
@@ -1033,9 +1033,9 @@ FILESPATH = "${@base_set_filespath([ "${FILE_DIRNAME}/${PF}", \
1033 "${FILE_DIRNAME}/${BP}", "${FILE_DIRNAME}/${BPN}", \ 1033 "${FILE_DIRNAME}/${BP}", "${FILE_DIRNAME}/${BPN}", \
1034 "${FILE_DIRNAME}/files", "${FILE_DIRNAME}" ], d)}" 1034 "${FILE_DIRNAME}/files", "${FILE_DIRNAME}" ], d)}"
1035 </literallayout> 1035 </literallayout>
1036 Do not hand-edit the <filename>FILESPATH</filename> variable. 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 1037 If you want to extend the set of pathnames that BitBake uses when searching for
1038 files and patches, use the 1038 files and patches, use the
1039 <link linkend='var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></link> variable. 1039 <link linkend='var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></link> variable.
1040 </para> 1040 </para>
1041 </glossdef> 1041 </glossdef>
@@ -1045,29 +1045,29 @@ FILESPATH = "${@base_set_filespath([ "${FILE_DIRNAME}/${PF}", \
1045 <glossdef> 1045 <glossdef>
1046 <para>Allows you to define your own file permissions settings table as part of 1046 <para>Allows you to define your own file permissions settings table as part of
1047 your configuration for the packaging process. 1047 your configuration for the packaging process.
1048 For example, suppose you need a consistent set of custom permissions for 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. 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 1050 It is best to do this in the packages themselves but this is not always
1051 possible. 1051 possible.
1052 </para> 1052 </para>
1053 <para> 1053 <para>
1054 By default, the OpenEmbedded build system uses the <filename>fs-perms.txt</filename>, which 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 1055 is located in the <filename>meta/files</filename> folder in the
1056 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. 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 1057 If you create your own file permissions setting table, you should place it in your
1058 layer or the distros layer. 1058 layer or the distros layer.
1059 </para> 1059 </para>
1060 <para> 1060 <para>
1061 You define the <filename>FILESYSTEM_PERMS_TABLES</filename> variable in the 1061 You define the <filename>FILESYSTEM_PERMS_TABLES</filename> variable in the
1062 <filename>conf/local.conf</filename> file, which is found 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 1063 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>, to
1064 point to your custom <filename>fs-perms.txt</filename>. 1064 point to your custom <filename>fs-perms.txt</filename>.
1065 You can specify more than a single file permissions setting table. 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 1066 The paths you specify to these files must be defined within the
1067 <filename>BBPATH</filename> variable. 1067 <filename>BBPATH</filename> variable.
1068 </para> 1068 </para>
1069 <para> 1069 <para>
1070 For guidance on how to create your own file permissions settings table file, 1070 For guidance on how to create your own file permissions settings table file,
1071 examine the existing <filename>fs-perms.txt</filename>. 1071 examine the existing <filename>fs-perms.txt</filename>.
1072 </para> 1072 </para>
1073 </glossdef> 1073 </glossdef>
@@ -1076,11 +1076,11 @@ FILESPATH = "${@base_set_filespath([ "${FILE_DIRNAME}/${PF}", \
1076 <glossentry id='var-FULL_OPTIMIZATION'><glossterm>FULL_OPTIMIZATION</glossterm> 1076 <glossentry id='var-FULL_OPTIMIZATION'><glossterm>FULL_OPTIMIZATION</glossterm>
1077 <glossdef> 1077 <glossdef>
1078 <para> 1078 <para>
1079 The options to pass in 1079 The options to pass in
1080 <filename><link linkend='var-TARGET_CFLAGS'>TARGET_CFLAGS</link></filename> 1080 <filename><link linkend='var-TARGET_CFLAGS'>TARGET_CFLAGS</link></filename>
1081 and <filename><link linkend='var-CFLAGS'>CFLAGS</link></filename> 1081 and <filename><link linkend='var-CFLAGS'>CFLAGS</link></filename>
1082 when compiling an optimized system. 1082 when compiling an optimized system.
1083 This variable defaults to 1083 This variable defaults to
1084 "-fexpensive-optimizations -fomit-frame-pointer -frename-registers -O2". 1084 "-fexpensive-optimizations -fomit-frame-pointer -frename-registers -O2".
1085 </para> 1085 </para>
1086 </glossdef> 1086 </glossdef>
@@ -1110,7 +1110,7 @@ FILESPATH = "${@base_set_filespath([ "${FILE_DIRNAME}/${PF}", \
1110 Typically, you configure this variable in an image recipe. 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 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. 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 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 1114 full list of features that can be included in images built by the
1115 OpenEmbedded build system.</para> 1115 OpenEmbedded build system.</para>
1116 </glossdef> 1116 </glossdef>
@@ -1131,28 +1131,28 @@ FILESPATH = "${@base_set_filespath([ "${FILE_DIRNAME}/${PF}", \
1131 </para> 1131 </para>
1132 1132
1133 <para> 1133 <para>
1134 Image recipes set <filename>IMAGE_INSTALL</filename> to specify the 1134 Image recipes set <filename>IMAGE_INSTALL</filename> to specify the
1135 packages to install into an image through <filename>image.bbclass</filename>. 1135 packages to install into an image through <filename>image.bbclass</filename>.
1136 Additionally, "helper" classes exist, such as <filename>core-image.bbclass</filename>, 1136 Additionally, "helper" classes exist, such as <filename>core-image.bbclass</filename>,
1137 that can take 1137 that can take
1138 <filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename> lists 1138 <filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename> lists
1139 and turn these into auto-generated entries in 1139 and turn these into auto-generated entries in
1140 <filename>IMAGE_INSTALL</filename> in addition to its default contents. 1140 <filename>IMAGE_INSTALL</filename> in addition to its default contents.
1141 </para> 1141 </para>
1142 1142
1143 <para> 1143 <para>
1144 Using <filename>IMAGE_INSTALL</filename> with the <filename>+=</filename> 1144 Using <filename>IMAGE_INSTALL</filename> with the <filename>+=</filename>
1145 operator from the <filename>/conf/local.conf</filename> file or from within 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. 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> 1147 Since <filename>core-image.bbclass</filename> sets <filename>IMAGE_INSTALL</filename>
1148 to a default value using the <filename>?=</filename> operator, using a 1148 to a default value using the <filename>?=</filename> operator, using a
1149 <filename>+=</filename> operation against <filename>IMAGE_INSTALL</filename> 1149 <filename>+=</filename> operation against <filename>IMAGE_INSTALL</filename>
1150 will result in unexpected behavior when used in 1150 will result in unexpected behavior when used in
1151 <filename>/conf/local.conf</filename>. 1151 <filename>/conf/local.conf</filename>.
1152 Furthermore, the same operation from with an image recipe may or may not 1152 Furthermore, the same operation from with an image recipe may or may not
1153 succeed depending on the specific situation. 1153 succeed depending on the specific situation.
1154 In both these cases, the behavior is contrary to how most users expect 1154 In both these cases, the behavior is contrary to how most users expect
1155 the <filename>+=</filename> operator to work. 1155 the <filename>+=</filename> operator to work.
1156 </para> 1156 </para>
1157 1157
1158 <para> 1158 <para>
@@ -1171,27 +1171,27 @@ FILESPATH = "${@base_set_filespath([ "${FILE_DIRNAME}/${PF}", \
1171 <para> 1171 <para>
1172 Defines a multiplier that the build system applies to the initial image 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 1173 size for cases when the multiplier times the returned disk usage value
1174 for the image is greater than the sum of 1174 for the image is greater than the sum of
1175 <filename><link linkend='var-IMAGE_ROOTFS_SIZE'>IMAGE_ROOTFS_SIZE</link></filename> 1175 <filename><link linkend='var-IMAGE_ROOTFS_SIZE'>IMAGE_ROOTFS_SIZE</link></filename>
1176 and 1176 and
1177 <filename><link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'>IMAGE_ROOTFS_EXTRA_SPACE</link></filename>. 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 1178 The result of the multiplier applied to the initial image size creates
1179 free disk space in the image as overhead. 1179 free disk space in the image as overhead.
1180 By default, the build process uses a multiplier of 1.3 for this variable. 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 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. 1182 method is used to determine the final generated image size.
1183 You should be aware that post install scripts and the package management 1183 You should be aware that post install scripts and the package management
1184 system uses disk space inside this overhead area. 1184 system uses disk space inside this overhead area.
1185 Consequently, the multiplier does not produce an image with 1185 Consequently, the multiplier does not produce an image with
1186 all the theoretical free disk space. 1186 all the theoretical free disk space.
1187 See <filename><link linkend='var-IMAGE_ROOTFS_SIZE'>IMAGE_ROOTFS_SIZE</link></filename> 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. 1188 for information on how the build system determines the overall image size.
1189 </para> 1189 </para>
1190 1190
1191 <para> 1191 <para>
1192 The default 30% free disk space typically gives the image enough room to boot 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 1193 and allows for basic post installs while still leaving a small amount of
1194 free disk space. 1194 free disk space.
1195 If 30% free space is inadequate, you can increase the default value. 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: 1196 For example, the following setting gives you 50% free space added to the image:
1197 <literallayout class='monospaced'> 1197 <literallayout class='monospaced'>
@@ -1201,12 +1201,12 @@ FILESPATH = "${@base_set_filespath([ "${FILE_DIRNAME}/${PF}", \
1201 1201
1202 <para> 1202 <para>
1203 Alternatively, you can ensure a specific amount of free disk space is added 1203 Alternatively, you can ensure a specific amount of free disk space is added
1204 to the image by using 1204 to the image by using
1205 <filename><link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'>IMAGE_ROOTFS_EXTRA_SPACE</link></filename> 1205 <filename><link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'>IMAGE_ROOTFS_EXTRA_SPACE</link></filename>
1206 the variable. 1206 the variable.
1207 </para> 1207 </para>
1208 </glossdef> 1208 </glossdef>
1209 </glossentry> 1209 </glossentry>
1210 1210
1211 <glossentry id='var-IMAGE_ROOTFS_EXTRA_SPACE'><glossterm>IMAGE_ROOTFS_EXTRA_SPACE</glossterm> 1211 <glossentry id='var-IMAGE_ROOTFS_EXTRA_SPACE'><glossterm>IMAGE_ROOTFS_EXTRA_SPACE</glossterm>
1212 <glossdef> 1212 <glossdef>
@@ -1214,32 +1214,32 @@ FILESPATH = "${@base_set_filespath([ "${FILE_DIRNAME}/${PF}", \
1214 Defines additional free disk space created in the image in Kbytes. 1214 Defines additional free disk space created in the image in Kbytes.
1215 By default, this variable is set to "0". 1215 By default, this variable is set to "0".
1216 This free disk space is added to the image after the build system determines 1216 This free disk space is added to the image after the build system determines
1217 the image size as described in 1217 the image size as described in
1218 <filename><link linkend='var-IMAGE_ROOTFS_SIZE'>IMAGE_ROOTFS_SIZE</link></filename>. 1218 <filename><link linkend='var-IMAGE_ROOTFS_SIZE'>IMAGE_ROOTFS_SIZE</link></filename>.
1219 </para> 1219 </para>
1220 1220
1221 <para> 1221 <para>
1222 This variable is particularly useful when you want to ensure that a 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 1223 specific amount of free disk space is available on a device after an image
1224 is installed and running. 1224 is installed and running.
1225 For example, to be sure 5 Gbytes of free disk space is available, set the 1225 For example, to be sure 5 Gbytes of free disk space is available, set the
1226 variable as follows: 1226 variable as follows:
1227 <literallayout class='monospaced'> 1227 <literallayout class='monospaced'>
1228 IMAGE_ROOTFS_EXTRA_SPACE = "5242880" 1228 IMAGE_ROOTFS_EXTRA_SPACE = "5242880"
1229 </literallayout> 1229 </literallayout>
1230 </para> 1230 </para>
1231 </glossdef> 1231 </glossdef>
1232 </glossentry> 1232 </glossentry>
1233 1233
1234 <glossentry id='var-IMAGE_ROOTFS_SIZE'><glossterm>IMAGE_ROOTFS_SIZE</glossterm> 1234 <glossentry id='var-IMAGE_ROOTFS_SIZE'><glossterm>IMAGE_ROOTFS_SIZE</glossterm>
1235 <glossdef> 1235 <glossdef>
1236 <para> 1236 <para>
1237 Defines the size in Kbytes for the generated image. 1237 Defines the size in Kbytes for the generated image.
1238 The OpenEmbedded build system determines the final size for the generated 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 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 1240 for the generated image, a requested size for the image, and requested
1241 additional free disk space to be added to the image. 1241 additional free disk space to be added to the image.
1242 Programatically, the build system determines the final size of the 1242 Programatically, the build system determines the final size of the
1243 generated image as follows: 1243 generated image as follows:
1244 <literallayout class='monospaced'> 1244 <literallayout class='monospaced'>
1245 if (image-du * overhead) &lt; rootfs-size: 1245 if (image-du * overhead) &lt; rootfs-size:
@@ -1251,7 +1251,7 @@ FILESPATH = "${@base_set_filespath([ "${FILE_DIRNAME}/${PF}", \
1251 1251
1252 image-du = Returned value of the du command on 1252 image-du = Returned value of the du command on
1253 the image. 1253 the image.
1254 1254
1255 overhead = IMAGE_OVERHEAD_FACTOR 1255 overhead = IMAGE_OVERHEAD_FACTOR
1256 1256
1257 rootfs-size = IMAGE_ROOTFS_SIZE 1257 rootfs-size = IMAGE_ROOTFS_SIZE
@@ -1261,12 +1261,12 @@ FILESPATH = "${@base_set_filespath([ "${FILE_DIRNAME}/${PF}", \
1261 1261
1262 xspace = IMAGE_ROOTFS_EXTRA_SPACE 1262 xspace = IMAGE_ROOTFS_EXTRA_SPACE
1263 </literallayout> 1263 </literallayout>
1264<!-- In the above example, <filename>overhead</filename> is defined by the 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> 1265 <filename><link linkend='var-IMAGE_OVERHEAD_FACTOR'>IMAGE_OVERHEAD_FACTOR</link></filename>
1266 variable, <filename>xspace</filename> is defined by the 1266 variable, <filename>xspace</filename> is defined by the
1267 <filename><link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'>IMAGE_ROOTFS_EXTRA_SPACE</link></filename> 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 1268 variable, and <filename>du</filename> is the results of the disk usage command
1269 on the initially generated image. --> 1269 on the initially generated image. -->
1270 </para> 1270 </para>
1271 </glossdef> 1271 </glossdef>
1272 </glossentry> 1272 </glossentry>
@@ -1275,38 +1275,38 @@ FILESPATH = "${@base_set_filespath([ "${FILE_DIRNAME}/${PF}", \
1275 <glossdef> 1275 <glossdef>
1276 <para>Helps define the recipe revision for recipes that share 1276 <para>Helps define the recipe revision for recipes that share
1277 a common <filename>include</filename> file. 1277 a common <filename>include</filename> file.
1278 You can think of this variable as part of the recipe revision 1278 You can think of this variable as part of the recipe revision
1279 as set from within an include file.</para> 1279 as set from within an include file.</para>
1280 <para>Suppose, for example, you have a set of recipes that 1280 <para>Suppose, for example, you have a set of recipes that
1281 are used across several projects. 1281 are used across several projects.
1282 And, within each of those recipes the revision 1282 And, within each of those recipes the revision
1283 (its <filename>PR</filename> value) is set accordingly. 1283 (its <filename>PR</filename> value) is set accordingly.
1284 In this case, when the revision of those recipes changes 1284 In this case, when the revision of those recipes changes
1285 the burden is on you to find all those recipes and 1285 the burden is on you to find all those recipes and
1286 be sure that they get changed to reflect the updated 1286 be sure that they get changed to reflect the updated
1287 version of the recipe. 1287 version of the recipe.
1288 In this scenario, it can get complicated when recipes 1288 In this scenario, it can get complicated when recipes
1289 used in many places and that provide common functionality 1289 used in many places and that provide common functionality
1290 are upgraded to a new revision.</para> 1290 are upgraded to a new revision.</para>
1291 <para>A more efficient way of dealing with this situation is 1291 <para>A more efficient way of dealing with this situation is
1292 to set the <filename>INC_PR</filename> variable inside 1292 to set the <filename>INC_PR</filename> variable inside
1293 the <filename>include</filename> files that the recipes 1293 the <filename>include</filename> files that the recipes
1294 share and then expand the <filename>INC_PR</filename> 1294 share and then expand the <filename>INC_PR</filename>
1295 variable within the recipes to help 1295 variable within the recipes to help
1296 define the recipe revision. 1296 define the recipe revision.
1297 </para> 1297 </para>
1298 <para> 1298 <para>
1299 The following provides an example that shows how to use 1299 The following provides an example that shows how to use
1300 the <filename>INC_PR</filename> variable 1300 the <filename>INC_PR</filename> variable
1301 given a common <filename>include</filename> file that 1301 given a common <filename>include</filename> file that
1302 defines the variable. 1302 defines the variable.
1303 Once the variable is defined in the 1303 Once the variable is defined in the
1304 <filename>include</filename> file, you can use the 1304 <filename>include</filename> file, you can use the
1305 variable to set the <filename>PR</filename> values in 1305 variable to set the <filename>PR</filename> values in
1306 each recipe. 1306 each recipe.
1307 You will notice that when you set a recipe's 1307 You will notice that when you set a recipe's
1308 <filename>PR</filename> you can provide more granular 1308 <filename>PR</filename> you can provide more granular
1309 revisioning by appending values to the 1309 revisioning by appending values to the
1310 <filename>INC_PR</filename> variable: 1310 <filename>INC_PR</filename> variable:
1311 <literallayout class='monospaced'> 1311 <literallayout class='monospaced'>
1312recipes-graphics/xorg-font/xorg-font-common.inc:INC_PR = "r2" 1312recipes-graphics/xorg-font/xorg-font-common.inc:INC_PR = "r2"
@@ -1314,8 +1314,8 @@ recipes-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" 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" 1315recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
1316 </literallayout> 1316 </literallayout>
1317 The first line of the example establishes the baseline 1317 The first line of the example establishes the baseline
1318 revision to be used for all recipes that use the 1318 revision to be used for all recipes that use the
1319 <filename>include</filename> file. 1319 <filename>include</filename> file.
1320 The remaining lines in the example are from individual 1320 The remaining lines in the example are from individual
1321 recipes and show how the <filename>PR</filename> value 1321 recipes and show how the <filename>PR</filename> value
@@ -1335,8 +1335,8 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
1335 <glossentry id='var-INHERIT'><glossterm>INHERIT</glossterm> 1335 <glossentry id='var-INHERIT'><glossterm>INHERIT</glossterm>
1336 <glossdef> 1336 <glossdef>
1337 <para> 1337 <para>
1338 Causes the named class to be inherited at 1338 Causes the named class to be inherited at
1339 this point during parsing. 1339 this point during parsing.
1340 The variable is only valid in configuration files. 1340 The variable is only valid in configuration files.
1341 </para> 1341 </para>
1342 </glossdef> 1342 </glossdef>
@@ -1346,8 +1346,8 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
1346 <glossentry id='var-INITSCRIPT_PACKAGES'><glossterm>INITSCRIPT_PACKAGES</glossterm> 1346 <glossentry id='var-INITSCRIPT_PACKAGES'><glossterm>INITSCRIPT_PACKAGES</glossterm>
1347 <glossdef> 1347 <glossdef>
1348 <para> 1348 <para>
1349 A list of the packages that contain initscripts. 1349 A list of the packages that contain initscripts.
1350 If multiple packages are specified, you need to append the package name 1350 If multiple packages are specified, you need to append the package name
1351 to the other <filename>INITSCRIPT_*</filename> as an override.</para> 1351 to the other <filename>INITSCRIPT_*</filename> as an override.</para>
1352 <para> 1352 <para>
1353 This variable is used in recipes when using <filename>update-rc.d.bbclass</filename>. 1353 This variable is used in recipes when using <filename>update-rc.d.bbclass</filename>.
@@ -1372,12 +1372,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
1372 <glossdef> 1372 <glossdef>
1373 <para> 1373 <para>
1374 Specifies the options to pass to <filename>update-rc.d</filename>. 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 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 1376 runlevel of 99, starts the script in initlevels 2 and 5, and
1377 stops the script in levels 0, 1 and 6. 1377 stops the script in levels 0, 1 and 6.
1378 </para> 1378 </para>
1379 <para> 1379 <para>
1380 The variable is mandatory and is used in recipes when using 1380 The variable is mandatory and is used in recipes when using
1381 <filename>update-rc.d.bbclass</filename>. 1381 <filename>update-rc.d.bbclass</filename>.
1382 </para> 1382 </para>
1383 </glossdef> 1383 </glossdef>
@@ -1394,36 +1394,36 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
1394 <glossentry id='var-KBRANCH'><glossterm>KBRANCH</glossterm> 1394 <glossentry id='var-KBRANCH'><glossterm>KBRANCH</glossterm>
1395 <glossdef> 1395 <glossdef>
1396 <para> 1396 <para>
1397 A regular expression used by the build process to explicitly identify the kernel 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. 1398 branch that is validated, patched and configured during a build.
1399 The <filename>KBRANCH</filename> variable is optional. 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 1400 You can use it to trigger checks to ensure the exact kernel branch you want is
1401 being used by the build process. 1401 being used by the build process.
1402 </para> 1402 </para>
1403 1403
1404 <para> 1404 <para>
1405 Values for this variable are set in the kernel's recipe file and the kernel's 1405 Values for this variable are set in the kernel's recipe file and the kernel's
1406 append file. 1406 append file.
1407 For example, if you are using the Yocto Project kernel that is based on the 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 1408 Linux 3.4 kernel, the kernel recipe file is the
1409 <filename>meta/recipes-kernel/linux/linux-yocto_3.4.bb</filename> file. 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 1410 Following is the default value for <filename>KBRANCH</filename> and the default
1411 override for the architectures the Yocto Project supports: 1411 override for the architectures the Yocto Project supports:
1412 <literallayout class='monospaced'> 1412 <literallayout class='monospaced'>
1413 KBRANCH_DEFAULT = "standard/base" 1413 KBRANCH_DEFAULT = "standard/base"
1414 KBRANCH = "${KBRANCH_DEFAULT}" 1414 KBRANCH = "${KBRANCH_DEFAULT}"
1415 </literallayout> 1415 </literallayout>
1416 This branch exists in the <filename>linux-yocto-3.4</filename> kernel Git 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>. 1417 repository <ulink url='&YOCTO_GIT_URL;/cgit.cgi/linux-yocto-3.4/refs/heads'></ulink>.
1418 </para> 1418 </para>
1419 1419
1420 <para> 1420 <para>
1421 This variable is also used from the kernel's append file to identify the kernel 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. 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. 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 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 1425 <filename>meta-intel</filename> Git repository and is named
1426 <filename>meta-crownbay/recipes-kernel/linux/linux-yocto_3.4.bbappend</filename>. 1426 <filename>meta-crownbay/recipes-kernel/linux/linux-yocto_3.4.bbappend</filename>.
1427 Here are the related statements from the append file: 1427 Here are the related statements from the append file:
1428 <literallayout class='monospaced'> 1428 <literallayout class='monospaced'>
1429 COMPATIBLE_MACHINE_crownbay = "crownbay" 1429 COMPATIBLE_MACHINE_crownbay = "crownbay"
@@ -1434,9 +1434,9 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
1434 KMACHINE_crownbay-noemgd = "crownbay" 1434 KMACHINE_crownbay-noemgd = "crownbay"
1435 KBRANCH_crownbay-noemgd = "standard/crownbay" 1435 KBRANCH_crownbay-noemgd = "standard/crownbay"
1436 </literallayout> 1436 </literallayout>
1437 The <filename>KBRANCH_*</filename> statements identify the kernel branch to 1437 The <filename>KBRANCH_*</filename> statements identify the kernel branch to
1438 use when building for the Crown Bay BSP. 1438 use when building for the Crown Bay BSP.
1439 In this case there are two identical statements: one for each type of 1439 In this case there are two identical statements: one for each type of
1440 Crown Bay machine. 1440 Crown Bay machine.
1441 </para> 1441 </para>
1442 </glossdef> 1442 </glossdef>
@@ -1446,18 +1446,18 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
1446 <glossdef> 1446 <glossdef>
1447 <para>Includes additional metadata from the Yocto Project kernel Git repository. 1447 <para>Includes additional metadata from the Yocto Project kernel Git repository.
1448 In the OpenEmbedded build system, the default Board Support Packages (BSPs) 1448 In the OpenEmbedded build system, the default Board Support Packages (BSPs)
1449 metadata is provided through 1449 metadata is provided through
1450 the <filename>KMACHINE</filename> and <filename>KBRANCH</filename> variables. 1450 the <filename>KMACHINE</filename> and <filename>KBRANCH</filename> variables.
1451 You can use the <filename>KERNEL_FEATURES</filename> variable to further 1451 You can use the <filename>KERNEL_FEATURES</filename> variable to further
1452 add metadata for all BSPs.</para> 1452 add metadata for all BSPs.</para>
1453 <para>The metadata you add through this variable includes config fragments and 1453 <para>The metadata you add through this variable includes config fragments and
1454 features descriptions, 1454 features descriptions,
1455 which usually includes patches as well as config fragments. 1455 which usually includes patches as well as config fragments.
1456 You typically override the <filename>KERNEL_FEATURES</filename> variable 1456 You typically override the <filename>KERNEL_FEATURES</filename> variable
1457 for a specific machine. 1457 for a specific machine.
1458 In this way, you can provide validated, but optional, sets of kernel 1458 In this way, you can provide validated, but optional, sets of kernel
1459 configurations and features.</para> 1459 configurations and features.</para>
1460 <para>For example, the following adds <filename>netfilter</filename> to all 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> 1461 the Yocto Project kernels and adds sound support to the <filename>qemux86</filename>
1462 machine: 1462 machine:
1463 <literallayout class='monospaced'> 1463 <literallayout class='monospaced'>
@@ -1472,10 +1472,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
1472 1472
1473 <glossentry id='var-KERNEL_IMAGETYPE'><glossterm>KERNEL_IMAGETYPE</glossterm> 1473 <glossentry id='var-KERNEL_IMAGETYPE'><glossterm>KERNEL_IMAGETYPE</glossterm>
1474 <glossdef> 1474 <glossdef>
1475 <para>The type of kernel to build for a device, usually set by the 1475 <para>The type of kernel to build for a device, usually set by the
1476 machine configuration files and defaults to "zImage". 1476 machine configuration files and defaults to "zImage".
1477 This variable is used 1477 This variable is used
1478 when building the kernel and is passed to <filename>make</filename> as the target to 1478 when building the kernel and is passed to <filename>make</filename> as the target to
1479 build.</para> 1479 build.</para>
1480 </glossdef> 1480 </glossdef>
1481 </glossentry> 1481 </glossentry>
@@ -1486,22 +1486,22 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
1486 The machine as known by the kernel. 1486 The machine as known by the kernel.
1487 Sometimes the machine name used by the kernel does not match the machine name 1487 Sometimes the machine name used by the kernel does not match the machine name
1488 used by the OpenEmbedded build system. 1488 used by the OpenEmbedded build system.
1489 For example, the machine name that the OpenEmbedded build system understands as 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. 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>. 1491 The kernel understands that machine as <filename>arm_versatile926ejs</filename>.
1492 For cases like these, the <filename>KMACHINE</filename> variable maps the 1492 For cases like these, the <filename>KMACHINE</filename> variable maps the
1493 kernel machine name to the OpenEmbedded build system machine name. 1493 kernel machine name to the OpenEmbedded build system machine name.
1494 </para> 1494 </para>
1495 1495
1496 <para> 1496 <para>
1497 Kernel machine names are initially defined in the 1497 Kernel machine names are initially defined in the
1498 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'>Yocto Linux Kernel</ulink> in 1498 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'>Yocto Linux Kernel</ulink> in
1499 the <filename>meta</filename> branch. 1499 the <filename>meta</filename> branch.
1500 From the <filename>meta</filename> branch, look in 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. 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 1502 For example, from the <filename>meta</filename> branch in the
1503 <filename>linux-yocto-3.0</filename> kernel, the 1503 <filename>linux-yocto-3.0</filename> kernel, the
1504 <filename>meta/cfg/kernel-cache/bsp/cedartrail/cedartrail-standard.scc</filename> file 1504 <filename>meta/cfg/kernel-cache/bsp/cedartrail/cedartrail-standard.scc</filename> file
1505 has the following: 1505 has the following:
1506 <literallayout class='monospaced'> 1506 <literallayout class='monospaced'>
1507 define KMACHINE cedartrail 1507 define KMACHINE cedartrail
@@ -1511,7 +1511,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
1511 include ktypes/standard 1511 include ktypes/standard
1512 branch cedartrail 1512 branch cedartrail
1513 1513
1514 include cedartrail.scc 1514 include cedartrail.scc
1515 </literallayout> 1515 </literallayout>
1516 You can see that the kernel understands the machine name for the Cedar Trail BSP as 1516 You can see that the kernel understands the machine name for the Cedar Trail BSP as
1517 <filename>cedartrail</filename>. 1517 <filename>cedartrail</filename>.
@@ -1533,14 +1533,14 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
1533 KBRANCH_cedartrail-nopvr = "yocto/standard/cedartrail" 1533 KBRANCH_cedartrail-nopvr = "yocto/standard/cedartrail"
1534 KERNEL_FEATURES_append_cedartrail-nopvr += " cfg/smp.scc" 1534 KERNEL_FEATURES_append_cedartrail-nopvr += " cfg/smp.scc"
1535 </literallayout> 1535 </literallayout>
1536 The <filename>KMACHINE</filename> statements in the kernel's append file make sure that 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 1537 the OpenEmbedded build system and the Yocto Linux kernel understand the same machine
1538 names. 1538 names.
1539 </para> 1539 </para>
1540 1540
1541 <para> 1541 <para>
1542 This append file uses two <filename>KMACHINE</filename> statements. 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 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 1544 OpenEmbedded build system as <filename>cedartrail</filename> maps to the machine
1545 in the kernel also known as <filename>cedartrail</filename>: 1545 in the kernel also known as <filename>cedartrail</filename>:
1546 <literallayout class='monospaced'> 1546 <literallayout class='monospaced'>
@@ -1550,12 +1550,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
1550 1550
1551 <para> 1551 <para>
1552 The second statement is a good example of why the <filename>KMACHINE</filename> variable 1552 The second statement is a good example of why the <filename>KMACHINE</filename> variable
1553 is needed. 1553 is needed.
1554 In this example, the OpenEmbedded build system uses the <filename>cedartrail-nopvr</filename> 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 1555 machine name to refer to the Cedar Trail BSP that does not support the propriatory
1556 PowerVR driver. 1556 PowerVR driver.
1557 The kernel, however, uses the machine name <filename>cedartrail</filename>. 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 1558 Thus, the append file must map the <filename>cedartrail-nopvr</filename> machine name to
1559 the kernel's <filename>cedartrail</filename> name: 1559 the kernel's <filename>cedartrail</filename> name:
1560 <literallayout class='monospaced'> 1560 <literallayout class='monospaced'>
1561 KMACHINE_cedartrail-nopvr = "cedartrail" 1561 KMACHINE_cedartrail-nopvr = "cedartrail"
@@ -1563,9 +1563,9 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
1563 </para> 1563 </para>
1564 1564
1565 <para> 1565 <para>
1566 BSPs that ship with the Yocto Project release provide all mappings between the Yocto 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. 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 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. 1569 name you use is different than that used in the kernel.
1570 </para> 1570 </para>
1571 </glossdef> 1571 </glossdef>
@@ -1583,16 +1583,16 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
1583 to be compared against <filename>LAYERVERSION_anotherlayer</filename> in this case). 1583 to be compared against <filename>LAYERVERSION_anotherlayer</filename> in this case).
1584 An error will be produced if any dependency is missing or 1584 An error will be produced if any dependency is missing or
1585 the version numbers do not match exactly (if specified). 1585 the version numbers do not match exactly (if specified).
1586 This variable is used in the <filename>conf/layer.conf</filename> file 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. 1587 and must be suffixed with the name of the specific layer (e.g.
1588 <filename>LAYERDEPENDS_mylayer</filename>).</para> 1588 <filename>LAYERDEPENDS_mylayer</filename>).</para>
1589 </glossdef> 1589 </glossdef>
1590 </glossentry> 1590 </glossentry>
1591 1591
1592 <glossentry id='var-LAYERDIR'><glossterm>LAYERDIR</glossterm> 1592 <glossentry id='var-LAYERDIR'><glossterm>LAYERDIR</glossterm>
1593 <glossdef> 1593 <glossdef>
1594 <para>When used inside the <filename>layer.conf</filename> configuration 1594 <para>When used inside the <filename>layer.conf</filename> configuration
1595 file, this variable provides the path of the current layer. 1595 file, this variable provides the path of the current layer.
1596 This variable requires immediate expansion 1596 This variable requires immediate expansion
1597 (see the BitBake manual) as lazy expansion can result in 1597 (see the BitBake manual) as lazy expansion can result in
1598 the expansion happening in the wrong directory and therefore 1598 the expansion happening in the wrong directory and therefore
@@ -1605,7 +1605,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
1605 <para>Optionally specifies the version of a layer as a single number. 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 1606 You can use this within <filename>LAYERDEPENDS</filename> for another layer in order to
1607 depend on a specific version of the layer. 1607 depend on a specific version of the layer.
1608 This variable is used in the <filename>conf/layer.conf</filename> file 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. 1609 and must be suffixed with the name of the specific layer (e.g.
1610 <filename>LAYERVERSION_mylayer</filename>).</para> 1610 <filename>LAYERVERSION_mylayer</filename>).</para>
1611 </glossdef> 1611 </glossdef>
@@ -1615,9 +1615,9 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
1615 <glossdef> 1615 <glossdef>
1616 <para>Checksums of the license text in the recipe source code.</para> 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 1617 <para>This variable tracks changes in license text of the source
1618 code files. 1618 code files.
1619 If the license text is changed, it will trigger a build 1619 If the license text is changed, it will trigger a build
1620 failure, which gives the developer an opportunity to review any 1620 failure, which gives the developer an opportunity to review any
1621 license change.</para> 1621 license change.</para>
1622 <para> 1622 <para>
1623 This variable must be defined for all recipes (unless <filename>LICENSE</filename> 1623 This variable must be defined for all recipes (unless <filename>LICENSE</filename>
@@ -1636,14 +1636,14 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
1636 <itemizedlist> 1636 <itemizedlist>
1637 <listitem><para>Do not use spaces within individual 1637 <listitem><para>Do not use spaces within individual
1638 license names.</para></listitem> 1638 license names.</para></listitem>
1639 <listitem><para>Separate license names using 1639 <listitem><para>Separate license names using
1640 | (pipe) when there is a choice between licenses. 1640 | (pipe) when there is a choice between licenses.
1641 </para></listitem> 1641 </para></listitem>
1642 <listitem><para>Separate license names using 1642 <listitem><para>Separate license names using
1643 &amp; (ampersand) when multiple licenses exist 1643 &amp; (ampersand) when multiple licenses exist
1644 that cover different parts of the source. 1644 that cover different parts of the source.
1645 </para></listitem> 1645 </para></listitem>
1646 <listitem><para>You can use spaces between license 1646 <listitem><para>You can use spaces between license
1647 names.</para></listitem> 1647 names.</para></listitem>
1648 </itemizedlist> 1648 </itemizedlist>
1649 </para> 1649 </para>
@@ -1655,12 +1655,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
1655 LICENSE = "MPL-1 &amp; LGPLv2.1" 1655 LICENSE = "MPL-1 &amp; LGPLv2.1"
1656 LICENSE = "GPLv2+" 1656 LICENSE = "GPLv2+"
1657 </literallayout> 1657 </literallayout>
1658 The first example is from the recipes for Qt, which the user 1658 The first example is from the recipes for Qt, which the user
1659 may choose to distribute under either the LGPL version 1659 may choose to distribute under either the LGPL version
1660 2.1 or GPL version 3. 1660 2.1 or GPL version 3.
1661 The second example is from Cairo where two licenses cover 1661 The second example is from Cairo where two licenses cover
1662 different parts of the source code. 1662 different parts of the source code.
1663 The final example is from <filename>sysstat</filename>, 1663 The final example is from <filename>sysstat</filename>,
1664 which presents a single license. 1664 which presents a single license.
1665 </para> 1665 </para>
1666 </glossdef> 1666 </glossdef>
@@ -1669,10 +1669,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
1669 <glossentry id='var-LICENSE_PATH'><glossterm>LICENSE_PATH</glossterm> 1669 <glossentry id='var-LICENSE_PATH'><glossterm>LICENSE_PATH</glossterm>
1670 <glossdef> 1670 <glossdef>
1671 <para>Path to additional licenses used during the build. 1671 <para>Path to additional licenses used during the build.
1672 By default, the OpenEmbedded build system uses <filename>COMMON_LICENSE_DIR</filename> 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. 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 1674 The <filename>LICENSE_PATH</filename> variable allows you to extend that
1675 location to other areas that have additional licenses: 1675 location to other areas that have additional licenses:
1676 <literallayout class='monospaced'> 1676 <literallayout class='monospaced'>
1677 LICENSE_PATH += "/path/to/additional/common/licenses" 1677 LICENSE_PATH += "/path/to/additional/common/licenses"
1678 </literallayout></para> 1678 </literallayout></para>
@@ -1687,26 +1687,26 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
1687 <glossdef> 1687 <glossdef>
1688 <para> 1688 <para>
1689 Specifies the target device for which the image is built. 1689 Specifies the target device for which the image is built.
1690 You define <filename>MACHINE</filename> in the 1690 You define <filename>MACHINE</filename> in the
1691 <filename>local.conf</filename> file found in the 1691 <filename>local.conf</filename> file found in the
1692 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. 1692 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
1693 By default, <filename>MACHINE</filename> is set to 1693 By default, <filename>MACHINE</filename> is set to
1694 "qemux86", which is an x86-based architecture machine to 1694 "qemux86", which is an x86-based architecture machine to
1695 be emulated using QEMU: 1695 be emulated using QEMU:
1696 <literallayout class='monospaced'> 1696 <literallayout class='monospaced'>
1697 MACHINE ?= "qemux86" 1697 MACHINE ?= "qemux86"
1698 </literallayout> 1698 </literallayout>
1699 The variable corresponds to a machine configuration file of the 1699 The variable corresponds to a machine configuration file of the
1700 same name, through which machine-specific configurations are set. 1700 same name, through which machine-specific configurations are set.
1701 Thus, when <filename>MACHINE</filename> is set to "qemux86" there 1701 Thus, when <filename>MACHINE</filename> is set to "qemux86" there
1702 exists the corresponding <filename>qemux86.conf</filename> machine 1702 exists the corresponding <filename>qemux86.conf</filename> machine
1703 configuration file, which can be found in the 1703 configuration file, which can be found in the
1704 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> 1704 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
1705 in <filename>meta/conf/machine</filename>. 1705 in <filename>meta/conf/machine</filename>.
1706 </para> 1706 </para>
1707 1707
1708 <para> 1708 <para>
1709 The list of machines supported by the Yocto Project as 1709 The list of machines supported by the Yocto Project as
1710 shipped include the following: 1710 shipped include the following:
1711 <literallayout class='monospaced'> 1711 <literallayout class='monospaced'>
1712 MACHINE ?= "qemuarm" 1712 MACHINE ?= "qemuarm"
@@ -1721,10 +1721,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
1721 </literallayout> 1721 </literallayout>
1722 The last four are Yocto Project reference hardware boards, which 1722 The last four are Yocto Project reference hardware boards, which
1723 are provided in the <filename>meta-yocto-bsp</filename> layer. 1723 are provided in the <filename>meta-yocto-bsp</filename> layer.
1724 <note>Adding additional Board Support Package (BSP) layers 1724 <note>Adding additional Board Support Package (BSP) layers
1725 to your configuration adds new possible settings for 1725 to your configuration adds new possible settings for
1726 <filename>MACHINE</filename>. 1726 <filename>MACHINE</filename>.
1727 </note> 1727 </note>
1728 </para> 1728 </para>
1729 </glossdef> 1729 </glossdef>
1730 </glossentry> 1730 </glossentry>
@@ -1736,16 +1736,16 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
1736 A list of required machine-specific packages to install as part of 1736 A list of required machine-specific packages to install as part of
1737 the image being built. 1737 the image being built.
1738 The build process depends on these packages being present. 1738 The build process depends on these packages being present.
1739 Furthermore, because this is a "machine essential" variable, the list of 1739 Furthermore, because this is a "machine essential" variable, the list of
1740 packages are essential for the machine to boot. 1740 packages are essential for the machine to boot.
1741 The impact of this variable affects images based on 1741 The impact of this variable affects images based on
1742 <filename>packagegroup-core-boot</filename>, 1742 <filename>packagegroup-core-boot</filename>,
1743 including the <filename>core-image-minimal</filename> image. 1743 including the <filename>core-image-minimal</filename> image.
1744 </para> 1744 </para>
1745 <para> 1745 <para>
1746 This variable is similar to the 1746 This variable is similar to the
1747 <filename><link linkend='var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</link></filename> 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 1748 variable with the exception that the image being built has a build
1749 dependency on the variable's list of packages. 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. 1750 In other words, the image will not build if a file in this list is not found.
1751 </para> 1751 </para>
@@ -1768,16 +1768,16 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
1768 A list of recommended machine-specific packages to install as part of 1768 A list of recommended machine-specific packages to install as part of
1769 the image being built. 1769 the image being built.
1770 The build process does not depend on these packages being present. 1770 The build process does not depend on these packages being present.
1771 However, because this is a "machine essential" variable, the list of 1771 However, because this is a "machine essential" variable, the list of
1772 packages are essential for the machine to boot. 1772 packages are essential for the machine to boot.
1773 The impact of this variable affects images based on 1773 The impact of this variable affects images based on
1774 <filename>packagegroup-core-boot</filename>, 1774 <filename>packagegroup-core-boot</filename>,
1775 including the <filename>core-image-minimal</filename> image. 1775 including the <filename>core-image-minimal</filename> image.
1776 </para> 1776 </para>
1777 <para> 1777 <para>
1778 This variable is similar to the 1778 This variable is similar to the
1779 <filename><link linkend='var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</link></filename> 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 1780 variable with the exception that the image being built does not have a build
1781 dependency on the variable's list of packages. 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. 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 1783 Typically, this variable is used to handle essential kernel modules, whose
@@ -1790,20 +1790,20 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
1790 However, the driver can be built as a module or 1790 However, the driver can be built as a module or
1791 into the kernel depending on the kernel configuration. 1791 into the kernel depending on the kernel configuration.
1792 If the driver is built as a module, you want it to be installed. 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 1793 But, when the driver is built into the kernel, you still want the
1794 build to succeed. 1794 build to succeed.
1795 This variable sets up a "recommends" relationship so that in the latter case, 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. 1796 the build will not fail due to the missing package.
1797 To accomplish this, assuming the package for the module was called 1797 To accomplish this, assuming the package for the module was called
1798 <filename>kernel-module-ab123</filename>, you would use the 1798 <filename>kernel-module-ab123</filename>, you would use the
1799 following in the machine's <filename>.conf</filename> configuration 1799 following in the machine's <filename>.conf</filename> configuration
1800 file: 1800 file:
1801 <literallayout class='monospaced'> 1801 <literallayout class='monospaced'>
1802 MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-module-ab123" 1802 MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-module-ab123"
1803 </literallayout> 1803 </literallayout>
1804 </para> 1804 </para>
1805 <para> 1805 <para>
1806 Some examples of these machine essentials are flash, screen, keyboard, mouse, 1806 Some examples of these machine essentials are flash, screen, keyboard, mouse,
1807 or touchscreen drivers (depending on the machine). 1807 or touchscreen drivers (depending on the machine).
1808 </para> 1808 </para>
1809 </glossdef> 1809 </glossdef>
@@ -1812,21 +1812,21 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
1812 <glossentry id='var-MACHINE_EXTRA_RDEPENDS'><glossterm>MACHINE_EXTRA_RDEPENDS</glossterm> 1812 <glossentry id='var-MACHINE_EXTRA_RDEPENDS'><glossterm>MACHINE_EXTRA_RDEPENDS</glossterm>
1813 <glossdef> 1813 <glossdef>
1814 <para> 1814 <para>
1815 A list of machine-specific packages to install as part of the 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. 1816 image being built that are not essential for the machine to boot.
1817 However, the build process for more fully-featured images 1817 However, the build process for more fully-featured images
1818 depends on the packages being present. 1818 depends on the packages being present.
1819 </para> 1819 </para>
1820 <para> 1820 <para>
1821 This variable affects all images based on 1821 This variable affects all images based on
1822 <filename>packagegroup-base</filename>, which does not include the 1822 <filename>packagegroup-base</filename>, which does not include the
1823 <filename>core-image-minimal</filename> or <filename>core-image-basic</filename> 1823 <filename>core-image-minimal</filename> or <filename>core-image-basic</filename>
1824 images. 1824 images.
1825 </para> 1825 </para>
1826 <para> 1826 <para>
1827 The variable is similar to the 1827 The variable is similar to the
1828 <filename><link linkend='var-MACHINE_EXTRA_RRECOMMENDS'>MACHINE_EXTRA_RRECOMMENDS</link></filename> 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 1829 variable with the exception that the image being built has a build
1830 dependency on the variable's list of packages. 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. 1831 In other words, the image will not build if a file in this list is not found.
1832 </para> 1832 </para>
@@ -1834,8 +1834,8 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
1834 An example is a machine that has WiFi capability but is not essential 1834 An example is a machine that has WiFi capability but is not essential
1835 For the machine to boot the image. 1835 For the machine to boot the image.
1836 However, if you are building a more fully-featured image, you want to enable 1836 However, if you are building a more fully-featured image, you want to enable
1837 the WiFi. 1837 the WiFi.
1838 The package containing the firmware for the WiFi hardware is always 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 1839 expected to exist, so it is acceptable for the build process to depend upon
1840 finding the package. 1840 finding the package.
1841 In this case, assuming the package for the firmware was called 1841 In this case, assuming the package for the firmware was called
@@ -1852,20 +1852,20 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
1852 <glossdef> 1852 <glossdef>
1853 <para></para> 1853 <para></para>
1854 <para> 1854 <para>
1855 A list of machine-specific packages to install as part of the 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. 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. 1857 The image being built has no build dependency on this list of packages.
1858 </para> 1858 </para>
1859 <para> 1859 <para>
1860 This variable affects only images based on 1860 This variable affects only images based on
1861 <filename>packagegroup-base</filename>, which does not include the 1861 <filename>packagegroup-base</filename>, which does not include the
1862 <filename>core-image-minimal</filename> or <filename>core-image-basic</filename> 1862 <filename>core-image-minimal</filename> or <filename>core-image-basic</filename>
1863 images. 1863 images.
1864 </para> 1864 </para>
1865 <para> 1865 <para>
1866 This variable is similar to the 1866 This variable is similar to the
1867 <filename><link linkend='var-MACHINE_EXTRA_RDEPENDS'>MACHINE_EXTRA_RDEPENDS</link></filename> 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 1868 variable with the exception that the image being built does not have a build
1869 dependency on the variable's list of packages. 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. 1870 In other words, the image will build if a file in this list is not found.
1871 </para> 1871 </para>
@@ -1873,7 +1873,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
1873 An example is a machine that has WiFi capability but is not essential 1873 An example is a machine that has WiFi capability but is not essential
1874 For the machine to boot the image. 1874 For the machine to boot the image.
1875 However, if you are building a more fully-featured image, you want to enable 1875 However, if you are building a more fully-featured image, you want to enable
1876 WiFi. 1876 WiFi.
1877 In this case, the package containing the WiFi kernel module will not be produced 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 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. 1879 build to succeed instead of failing as a result of the package not being found.
@@ -1889,19 +1889,19 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
1889 1889
1890 <glossentry id='var-MACHINE_FEATURES'><glossterm>MACHINE_FEATURES</glossterm> 1890 <glossentry id='var-MACHINE_FEATURES'><glossterm>MACHINE_FEATURES</glossterm>
1891 <glossdef> 1891 <glossdef>
1892 <para>Specifies the list of hardware features the 1892 <para>Specifies the list of hardware features the
1893 <link linkend='var-MACHINE'>MACHINE</link> supports. 1893 <link linkend='var-MACHINE'>MACHINE</link> supports.
1894 For example, including the "bluetooth" feature causes the 1894 For example, including the "bluetooth" feature causes the
1895 <filename>bluez</filename> bluetooth daemon to be built and 1895 <filename>bluez</filename> bluetooth daemon to be built and
1896 added to the image. 1896 added to the image.
1897 It also causes the <filename>connman</filename> recipe 1897 It also causes the <filename>connman</filename> recipe
1898 to look at <filename>MACHINE_FEATURES</filename> and when it 1898 to look at <filename>MACHINE_FEATURES</filename> and when it
1899 finds "bluetooth" there it enables the bluetooth 1899 finds "bluetooth" there it enables the bluetooth
1900 support in ConnMan. 1900 support in ConnMan.
1901 </para> 1901 </para>
1902 1902
1903 <para> 1903 <para>
1904 For a list of features supported by the Yocto Project as shipped, 1904 For a list of features supported by the Yocto Project as shipped,
1905 see the "<link linkend='ref-features-machine'>Machine</link>" section. 1905 see the "<link linkend='ref-features-machine'>Machine</link>" section.
1906 </para> 1906 </para>
1907 </glossdef> 1907 </glossdef>
@@ -1909,18 +1909,18 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
1909 1909
1910 <glossentry id='var-MACHINE_FEATURES_BACKFILL'><glossterm>MACHINE_FEATURES_BACKFILL</glossterm> 1910 <glossentry id='var-MACHINE_FEATURES_BACKFILL'><glossterm>MACHINE_FEATURES_BACKFILL</glossterm>
1911 <glossdef> 1911 <glossdef>
1912 <para>Features to be added to 1912 <para>Features to be added to
1913 <filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename> 1913 <filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename>
1914 if not also present in 1914 if not also present in
1915 <filename><link linkend='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'>MACHINE_FEATURES_BACKFILL_CONSIDERED</link></filename>. 1915 <filename><link linkend='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'>MACHINE_FEATURES_BACKFILL_CONSIDERED</link></filename>.
1916 </para> 1916 </para>
1917 1917
1918 <para> 1918 <para>
1919 This variable is set in the <filename>meta/conf/bitbake.conf</filename> file. 1919 This variable is set in the <filename>meta/conf/bitbake.conf</filename> file.
1920 It is not intended to be user-configurable. 1920 It is not intended to be user-configurable.
1921 It is best to just reference the variable to see which machine features are 1921 It is best to just reference the variable to see which machine features are
1922 being backfilled for all machine configurations. 1922 being backfilled for all machine configurations.
1923 See the <link linkend='ref-features-backfill'>Feature backfilling</link> section for 1923 See the <link linkend='ref-features-backfill'>Feature backfilling</link> section for
1924 more information. 1924 more information.
1925 </para> 1925 </para>
1926 </glossdef> 1926 </glossdef>
@@ -1933,7 +1933,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
1933 that should not be backfilled (i.e. added to 1933 that should not be backfilled (i.e. added to
1934 <filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename>) 1934 <filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename>)
1935 during the build. 1935 during the build.
1936 See the <link linkend='ref-features-backfill'>Feature backfilling</link> section for 1936 See the <link linkend='ref-features-backfill'>Feature backfilling</link> section for
1937 more information. 1937 more information.
1938 </para> 1938 </para>
1939 </glossdef> 1939 </glossdef>
@@ -1949,13 +1949,13 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
1949 <glossdef> 1949 <glossdef>
1950 <para> 1950 <para>
1951 Specifies a prefix has been added to 1951 Specifies a prefix has been added to
1952 <link linkend='var-PN'><filename>PN</filename></link> to create a special version 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. 1953 of a recipe or package, such as a multilib version.
1954 The variable is used in places where the prefix needs to be 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 1955 added to or removed from a the name (e.g. the
1956 <link linkend='var-BPN'><filename>BPN</filename></link> variable). 1956 <link linkend='var-BPN'><filename>BPN</filename></link> variable).
1957 <filename>MLPREFIX</filename> gets set when a prefix has been 1957 <filename>MLPREFIX</filename> gets set when a prefix has been
1958 added to <filename>PN</filename>. 1958 added to <filename>PN</filename>.
1959 </para> 1959 </para>
1960 </glossdef> 1960 </glossdef>
1961 </glossentry> 1961 </glossentry>
@@ -1981,17 +1981,17 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
1981 <glossentry id='var-OE_TERMINAL'><glossterm>OE_TERMINAL</glossterm> 1981 <glossentry id='var-OE_TERMINAL'><glossterm>OE_TERMINAL</glossterm>
1982 <glossdef> 1982 <glossdef>
1983 <para> 1983 <para>
1984 Controls how the OpenEmbedded build system spawns 1984 Controls how the OpenEmbedded build system spawns
1985 interactive terminals on the host development system 1985 interactive terminals on the host development system
1986 (e.g. using the BitBake command with the 1986 (e.g. using the BitBake command with the
1987 <filename>-c devshell</filename> command-line option). 1987 <filename>-c devshell</filename> command-line option).
1988 For more information, see the 1988 For more information, see the
1989 "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-appdev-devshell'>Using a Development Shell</ulink>" section 1989 "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-appdev-devshell'>Using a Development Shell</ulink>" section
1990 in the Yocto Project Development Manual. 1990 in the Yocto Project Development Manual.
1991 </para> 1991 </para>
1992 1992
1993 <para> 1993 <para>
1994 You can use the following values for the 1994 You can use the following values for the
1995 <filename>OE_TERMINAL</filename> variable: 1995 <filename>OE_TERMINAL</filename> variable:
1996 <literallayout class='monospaced'> 1996 <literallayout class='monospaced'>
1997 auto 1997 auto
@@ -2000,10 +2000,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
2000 rxvt 2000 rxvt
2001 screen 2001 screen
2002 konsole 2002 konsole
2003 none 2003 none
2004 </literallayout> 2004 </literallayout>
2005 <note>Konsole support only works for KDE 3.x. 2005 <note>Konsole support only works for KDE 3.x.
2006 Also, "auto" is the default behavior for 2006 Also, "auto" is the default behavior for
2007 <filename>OE_TERMINAL</filename></note> 2007 <filename>OE_TERMINAL</filename></note>
2008 </para> 2008 </para>
2009 </glossdef> 2009 </glossdef>
@@ -2030,9 +2030,9 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
2030 2030
2031 <glossentry id='var-PACKAGE_BEFORE_PN'><glossterm>PACKAGE_BEFORE_PN</glossterm> 2031 <glossentry id='var-PACKAGE_BEFORE_PN'><glossterm>PACKAGE_BEFORE_PN</glossterm>
2032 <glossdef> 2032 <glossdef>
2033 <para>Enables easily adding packages to 2033 <para>Enables easily adding packages to
2034 <filename><link linkend='var-PACKAGES'>PACKAGES</link></filename> 2034 <filename><link linkend='var-PACKAGES'>PACKAGES</link></filename>
2035 before <filename>${PN}</filename> so that the packages can pick 2035 before <filename>${PN}</filename> so that the packages can pick
2036 up files that would normally be included in the default package.</para> 2036 up files that would normally be included in the default package.</para>
2037 </glossdef> 2037 </glossdef>
2038 </glossentry> 2038 </glossentry>
@@ -2040,15 +2040,15 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
2040 <glossentry id='var-PACKAGE_CLASSES'><glossterm>PACKAGE_CLASSES</glossterm> 2040 <glossentry id='var-PACKAGE_CLASSES'><glossterm>PACKAGE_CLASSES</glossterm>
2041 <glossdef> 2041 <glossdef>
2042 <para>This variable, which is set in the <filename>local.conf</filename> configuration 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 2043 file found in the <filename>conf</filename> folder of the
2044 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>, 2044 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>,
2045 specifies the package manager to use when packaging data. 2045 specifies the package manager to use when packaging data.
2046 You can provide one or more arguments for the variable with the first 2046 You can provide one or more arguments for the variable with the first
2047 argument being the package manager used to create images: 2047 argument being the package manager used to create images:
2048 <literallayout class='monospaced'> 2048 <literallayout class='monospaced'>
2049 PACKAGE_CLASSES ?= "package_rpm package_deb package_ipk" 2049 PACKAGE_CLASSES ?= "package_rpm package_deb package_ipk"
2050 </literallayout> 2050 </literallayout>
2051 For information on build performance effects as a result of the 2051 For information on build performance effects as a result of the
2052 package manager use, see 2052 package manager use, see
2053 <link linkend='ref-classes-package'>Packaging - <filename>package*.bbclass</filename></link> 2053 <link linkend='ref-classes-package'>Packaging - <filename>package*.bbclass</filename></link>
2054 in this manual. 2054 in this manual.
@@ -2067,33 +2067,33 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
2067 <glossentry id='var-PACKAGECONFIG'><glossterm>PACKAGECONFIG</glossterm> 2067 <glossentry id='var-PACKAGECONFIG'><glossterm>PACKAGECONFIG</glossterm>
2068 <glossdef> 2068 <glossdef>
2069 <para> 2069 <para>
2070 This variable provides a means of enabling or disabling 2070 This variable provides a means of enabling or disabling
2071 features of a recipe on a per-recipe basis. 2071 features of a recipe on a per-recipe basis.
2072 The <filename>PACKAGECONFIG</filename> 2072 The <filename>PACKAGECONFIG</filename>
2073 variable itself specifies a space-separated list of the 2073 variable itself specifies a space-separated list of the
2074 features to enable. 2074 features to enable.
2075 The features themselves are specified as flags on the 2075 The features themselves are specified as flags on the
2076 <filename>PACKAGECONFIG</filename> variable. 2076 <filename>PACKAGECONFIG</filename> variable.
2077 You can provide up to four arguments, which are separated by 2077 You can provide up to four arguments, which are separated by
2078 commas, to determine the behavior of each feature 2078 commas, to determine the behavior of each feature
2079 when it is enabled or disabled. 2079 when it is enabled or disabled.
2080 You can omit any argument you like but must retain the 2080 You can omit any argument you like but must retain the
2081 separating commas. 2081 separating commas.
2082 The arguments specify the following: 2082 The arguments specify the following:
2083 <orderedlist> 2083 <orderedlist>
2084 <listitem><para>Extra arguments 2084 <listitem><para>Extra arguments
2085 that should be added to the configure script argument list 2085 that should be added to the configure script argument list
2086 (<link linkend='var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></link>) 2086 (<link linkend='var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></link>)
2087 if the feature is enabled.</para></listitem> 2087 if the feature is enabled.</para></listitem>
2088 <listitem><para>Extra arguments 2088 <listitem><para>Extra arguments
2089 that should be added to <filename>EXTRA_OECONF</filename> 2089 that should be added to <filename>EXTRA_OECONF</filename>
2090 if the feature is disabled. 2090 if the feature is disabled.
2091 </para></listitem> 2091 </para></listitem>
2092 <listitem><para>Additional build dependencies 2092 <listitem><para>Additional build dependencies
2093 (<link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>) 2093 (<link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>)
2094 that should be added if the feature is enabled. 2094 that should be added if the feature is enabled.
2095 </para></listitem> 2095 </para></listitem>
2096 <listitem><para>Additional runtime dependencies 2096 <listitem><para>Additional runtime dependencies
2097 (<link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>) 2097 (<link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>)
2098 that should be added if the feature is enabled. 2098 that should be added if the feature is enabled.
2099 </para></listitem> 2099 </para></listitem>
@@ -2101,25 +2101,25 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
2101 </para> 2101 </para>
2102 2102
2103 <para> 2103 <para>
2104 Consider the following example taken from the 2104 Consider the following example taken from the
2105 <filename>librsvg</filename> recipe. 2105 <filename>librsvg</filename> recipe.
2106 In this example the feature is <filename>croco</filename>, which 2106 In this example the feature is <filename>croco</filename>, which
2107 has three arguments that determine the feature's behavior. 2107 has three arguments that determine the feature's behavior.
2108 <literallayout class='monospaced'> 2108 <literallayout class='monospaced'>
2109 PACKAGECONFIG ??= "croco" 2109 PACKAGECONFIG ??= "croco"
2110 PACKAGECONFIG[croco] = "--with-croco,--without-croco,libcroco" 2110 PACKAGECONFIG[croco] = "--with-croco,--without-croco,libcroco"
2111 </literallayout> 2111 </literallayout>
2112 The <filename>--with-croco</filename> and 2112 The <filename>--with-croco</filename> and
2113 <filename>libcroco</filename> arguments apply only if 2113 <filename>libcroco</filename> arguments apply only if
2114 the feature is enabled. 2114 the feature is enabled.
2115 In this case, <filename>--with-croco</filename> is 2115 In this case, <filename>--with-croco</filename> is
2116 added to the configure script argument list and 2116 added to the configure script argument list and
2117 <filename>libcroco</filename> is added to 2117 <filename>libcroco</filename> is added to
2118 <filename><link linkend='var-DEPENDS'>DEPENDS</link></filename>. 2118 <filename><link linkend='var-DEPENDS'>DEPENDS</link></filename>.
2119 On the other hand, if the feature is disabled say through 2119 On the other hand, if the feature is disabled say through
2120 a <filename>.bbappend</filename> file in another layer, then 2120 a <filename>.bbappend</filename> file in another layer, then
2121 the second argument <filename>--without-croco</filename> is 2121 the second argument <filename>--without-croco</filename> is
2122 added to the configure script rather than 2122 added to the configure script rather than
2123 <filename>--with-croco</filename>. 2123 <filename>--with-croco</filename>.
2124 </para> 2124 </para>
2125 </glossdef> 2125 </glossdef>
@@ -2138,29 +2138,29 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
2138 <glossentry id='var-PACKAGES_DYNAMIC'><glossterm>PACKAGES_DYNAMIC</glossterm> 2138 <glossentry id='var-PACKAGES_DYNAMIC'><glossterm>PACKAGES_DYNAMIC</glossterm>
2139 <glossdef> 2139 <glossdef>
2140 <para> 2140 <para>
2141 A promise that your recipe satisfies runtime dependencies 2141 A promise that your recipe satisfies runtime dependencies
2142 for optional modules that are found in other recipes. 2142 for optional modules that are found in other recipes.
2143 <filename>PACKAGES_DYNAMIC</filename> 2143 <filename>PACKAGES_DYNAMIC</filename>
2144 does not actually satisfy the dependencies, it only states that 2144 does not actually satisfy the dependencies, it only states that
2145 they should be satisfied. 2145 they should be satisfied.
2146 For example, if a hard, runtime dependency 2146 For example, if a hard, runtime dependency
2147 (<filename>RDEPENDS</filename>) of another package is satisfied 2147 (<filename>RDEPENDS</filename>) of another package is satisfied
2148 at build time through the <filename>PACKAGES_DYNAMIC</filename> 2148 at build time through the <filename>PACKAGES_DYNAMIC</filename>
2149 variable, but a package with the module name is never actually 2149 variable, but a package with the module name is never actually
2150 produced, then the other package will be broken. 2150 produced, then the other package will be broken.
2151 Thus, if you attempt to include that package in an image, 2151 Thus, if you attempt to include that package in an image,
2152 you will get a dependency failure from the packaging system 2152 you will get a dependency failure from the packaging system
2153 during <filename>do_rootfs</filename>. 2153 during <filename>do_rootfs</filename>.
2154 Typically, if there is a chance that such a situation can 2154 Typically, if there is a chance that such a situation can
2155 occur and the package that is not created is valid 2155 occur and the package that is not created is valid
2156 without the dependency being satisfied, then you should use 2156 without the dependency being satisfied, then you should use
2157 <filename>RRECOMMENDS</filename> (a soft runtime dependency) 2157 <filename>RRECOMMENDS</filename> (a soft runtime dependency)
2158 instead of <filename>RDEPENDS</filename>. 2158 instead of <filename>RDEPENDS</filename>.
2159 </para> 2159 </para>
2160 2160
2161 <para> 2161 <para>
2162 For an example of how to use the <filename>PACKAGES_DYNAMIC</filename> 2162 For an example of how to use the <filename>PACKAGES_DYNAMIC</filename>
2163 variable when you are splitting packages, see the 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 2164 "<ulink url='&YOCTO_DOCS_DEV_URL;#handling-optional-module-packaging'>Handling Optional Module Packaging</ulink>" section
2165 in the Yocto Project Development Manual. 2165 in the Yocto Project Development Manual.
2166 </para> 2166 </para>
@@ -2169,11 +2169,11 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
2169 2169
2170 <glossentry id='var-PARALLEL_MAKE'><glossterm>PARALLEL_MAKE</glossterm> 2170 <glossentry id='var-PARALLEL_MAKE'><glossterm>PARALLEL_MAKE</glossterm>
2171 <glossdef> 2171 <glossdef>
2172 <para>Specifies extra options that are passed to the <filename>make</filename> command during the 2172 <para>Specifies extra options that are passed to the <filename>make</filename> command during the
2173 compile tasks. 2173 compile tasks.
2174 This variable is usually in the form <filename>-j 4</filename>, where the number 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. 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 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> 2177 this variable to twice the number of cores on the host.</para>
2178 </glossdef> 2178 </glossdef>
2179 </glossentry> 2179 </glossentry>
@@ -2194,21 +2194,21 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
2194 <glossdef> 2194 <glossdef>
2195 <para>This variable can have two separate functions depending on the context: a recipe 2195 <para>This variable can have two separate functions depending on the context: a recipe
2196 name or a resulting package name.</para> 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 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. 2198 by the OpenEmbedded build system as input to create a package.
2199 The name is normally extracted from the recipe file name. 2199 The name is normally extracted from the recipe file name.
2200 For example, if the recipe is named 2200 For example, if the recipe is named
2201 <filename>expat_2.0.1.bb</filename>, then the default value of <filename>PN</filename> 2201 <filename>expat_2.0.1.bb</filename>, then the default value of <filename>PN</filename>
2202 will be "expat".</para> 2202 will be "expat".</para>
2203 <para> 2203 <para>
2204 The variable refers to a package name in the context of a file created or produced by the 2204 The variable refers to a package name in the context of a file created or produced by the
2205 OpenEmbedded build system.</para> 2205 OpenEmbedded build system.</para>
2206 <para>If applicable, the <filename>PN</filename> variable also contains any special 2206 <para>If applicable, the <filename>PN</filename> variable also contains any special
2207 suffix or prefix. 2207 suffix or prefix.
2208 For example, using <filename>bash</filename> to build packages for the native 2208 For example, using <filename>bash</filename> to build packages for the native
2209 machine, <filename>PN</filename> is <filename>bash-native</filename>. 2209 machine, <filename>PN</filename> is <filename>bash-native</filename>.
2210 Using <filename>bash</filename> to build packages for the target and for Multilib, 2210 Using <filename>bash</filename> to build packages for the target and for Multilib,
2211 <filename>PN</filename> would be <filename>bash</filename> and 2211 <filename>PN</filename> would be <filename>bash</filename> and
2212 <filename>lib64-bash</filename>, respectively. 2212 <filename>lib64-bash</filename>, respectively.
2213 </para> 2213 </para>
2214 </glossdef> 2214 </glossdef>
@@ -2216,7 +2216,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
2216 2216
2217 <glossentry id='var-PR'><glossterm>PR</glossterm> 2217 <glossentry id='var-PR'><glossterm>PR</glossterm>
2218 <glossdef> 2218 <glossdef>
2219 <para>The revision of the recipe. 2219 <para>The revision of the recipe.
2220 The default value for this variable is "r0". 2220 The default value for this variable is "r0".
2221 </para> 2221 </para>
2222 </glossdef> 2222 </glossdef>
@@ -2224,10 +2224,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
2224 2224
2225 <glossentry id='var-PRINC'><glossterm>PRINC</glossterm> 2225 <glossentry id='var-PRINC'><glossterm>PRINC</glossterm>
2226 <glossdef> 2226 <glossdef>
2227 <para>Causes the <filename>PR</filename> variable of 2227 <para>Causes the <filename>PR</filename> variable of
2228 <filename>.bbappend</filename> files to dynamically increment. 2228 <filename>.bbappend</filename> files to dynamically increment.
2229 This increment minimizes the impact of layer ordering.</para> 2229 This increment minimizes the impact of layer ordering.</para>
2230 <para>In order to ensure multiple <filename>.bbappend</filename> files can co-exist, 2230 <para>In order to ensure multiple <filename>.bbappend</filename> files can co-exist,
2231 <filename>PRINC</filename> should be self referencing. 2231 <filename>PRINC</filename> should be self referencing.
2232 This variable defaults to 0.</para> 2232 This variable defaults to 0.</para>
2233 <para>Following is an example that increments <filename>PR</filename> by two: 2233 <para>Following is an example that increments <filename>PR</filename> by two:
@@ -2235,8 +2235,8 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
2235 PRINC := "${@int(PRINC) + 2}" 2235 PRINC := "${@int(PRINC) + 2}"
2236 </literallayout> 2236 </literallayout>
2237 It is adviseable not to use strings such as ".= '.1'" with the variable because 2237 It is adviseable not to use strings such as ".= '.1'" with the variable because
2238 this usage is very sensitive to layer ordering. 2238 this usage is very sensitive to layer ordering.
2239 Explicit assignments should be avoided as they cannot adequately represent multiple 2239 Explicit assignments should be avoided as they cannot adequately represent multiple
2240 <filename>.bbappend</filename> files.</para> 2240 <filename>.bbappend</filename> files.</para>
2241 </glossdef> 2241 </glossdef>
2242 </glossentry> 2242 </glossentry>
@@ -2245,11 +2245,11 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
2245 <glossdef> 2245 <glossdef>
2246 <para>The version of the recipe. 2246 <para>The version of the recipe.
2247 The version is normally extracted from the recipe filename. 2247 The version is normally extracted from the recipe filename.
2248 For example, if the recipe is named 2248 For example, if the recipe is named
2249 <filename>expat_2.0.1.bb</filename>, then the default value of <filename>PV</filename> 2249 <filename>expat_2.0.1.bb</filename>, then the default value of <filename>PV</filename>
2250 will be "2.0.1". 2250 will be "2.0.1".
2251 <filename>PV</filename> is generally not overridden within 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 2252 a recipe unless it is building an unstable (i.e. development) version from a source code repository
2253 (e.g. Git or Subversion). 2253 (e.g. Git or Subversion).
2254 </para> 2254 </para>
2255 </glossdef> 2255 </glossdef>
@@ -2258,9 +2258,9 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
2258 <glossentry id='var-PE'><glossterm>PE</glossterm> 2258 <glossentry id='var-PE'><glossterm>PE</glossterm>
2259 <glossdef> 2259 <glossdef>
2260 <para> 2260 <para>
2261 the epoch of the recipe. 2261 the epoch of the recipe.
2262 The default value is "0". 2262 The default value is "0".
2263 The field is used to make upgrades possible when the versioning scheme changes in 2263 The field is used to make upgrades possible when the versioning scheme changes in
2264 some backwards incompatible way. 2264 some backwards incompatible way.
2265 </para> 2265 </para>
2266 </glossdef> 2266 </glossdef>
@@ -2270,10 +2270,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
2270 <glossdef> 2270 <glossdef>
2271 <para> 2271 <para>
2272 If multiple recipes provide an item, this variable 2272 If multiple recipes provide an item, this variable
2273 determines which recipe should be given preference. 2273 determines which recipe should be given preference.
2274 The variable must always be suffixed with the name of the 2274 The variable must always be suffixed with the name of the
2275 provided item, and should be set to the 2275 provided item, and should be set to the
2276 <filename>PN</filename> of the recipe 2276 <filename>PN</filename> of the recipe
2277 to which you want to give precedence. 2277 to which you want to give precedence.
2278 Here is an example: 2278 Here is an example:
2279 <literallayout class='monospaced'> 2279 <literallayout class='monospaced'>
@@ -2288,17 +2288,17 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
2288 <para> 2288 <para>
2289 If there are multiple versions of recipes available, this 2289 If there are multiple versions of recipes available, this
2290 variable determines which recipe should be given preference. 2290 variable determines which recipe should be given preference.
2291 The variable must always be suffixed with the <filename>PN</filename> 2291 The variable must always be suffixed with the <filename>PN</filename>
2292 for which to select, and should be set to the 2292 for which to select, and should be set to the
2293 <filename>PV</filename> to which you want to give precedence. 2293 <filename>PV</filename> to which you want to give precedence.
2294 You can use the "<filename>%</filename>" character as a wildcard 2294 You can use the "<filename>%</filename>" character as a wildcard
2295 to match any number of characters, which can be useful when 2295 to match any number of characters, which can be useful when
2296 specifying versions that contain long revision number that could 2296 specifying versions that contain long revision number that could
2297 potentially change. 2297 potentially change.
2298 Here are two examples: 2298 Here are two examples:
2299 <literallayout class='monospaced'> 2299 <literallayout class='monospaced'>
2300 PREFERRED_VERSION_python = "2.6.6" 2300 PREFERRED_VERSION_python = "2.6.6"
2301 PREFERRED_VERSION_linux-yocto = "3.0+git%" 2301 PREFERRED_VERSION_linux-yocto = "3.0+git%"
2302 </literallayout> 2302 </literallayout>
2303 </para> 2303 </para>
2304 </glossdef> 2304 </glossdef>
@@ -2317,7 +2317,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
2317 Note that the package will not be installed if the conflicting packages are not 2317 Note that the package will not be installed if the conflicting packages are not
2318 first removed.</para> 2318 first removed.</para>
2319 <para> 2319 <para>
2320 Like all package-controlling variables, you must always use them in 2320 Like all package-controlling variables, you must always use them in
2321 conjunction with a package name override. 2321 conjunction with a package name override.
2322 Here is an example: 2322 Here is an example:
2323 <literallayout class='monospaced'> 2323 <literallayout class='monospaced'>
@@ -2330,59 +2330,59 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
2330 <glossentry id='var-RDEPENDS'><glossterm>RDEPENDS</glossterm> 2330 <glossentry id='var-RDEPENDS'><glossterm>RDEPENDS</glossterm>
2331 <glossdef> 2331 <glossdef>
2332 <para> 2332 <para>
2333 Lists a package's run-time dependencies (i.e. other packages) 2333 Lists a package's run-time dependencies (i.e. other packages)
2334 that must be installed for the package to be built. 2334 that must be installed for the package to be built.
2335 In other words, in order for the package to be built and 2335 In other words, in order for the package to be built and
2336 run correctly, it depends on the listed packages. 2336 run correctly, it depends on the listed packages.
2337 If a package in this list cannot be found, it is probable 2337 If a package in this list cannot be found, it is probable
2338 that a dependency error would occur before the build. 2338 that a dependency error would occur before the build.
2339 </para> 2339 </para>
2340 2340
2341 <para> 2341 <para>
2342 The names of the variables you list with 2342 The names of the variables you list with
2343 <filename>RDEPENDS</filename> must be the names of other 2343 <filename>RDEPENDS</filename> must be the names of other
2344 packages as listed in the 2344 packages as listed in the
2345 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link> 2345 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>
2346 variable. 2346 variable.
2347 You should not list recipe names (<filename>PN</filename>). 2347 You should not list recipe names (<filename>PN</filename>).
2348 </para> 2348 </para>
2349 2349
2350 <para> 2350 <para>
2351 Because the <filename>RDEPENDS</filename> variable applies 2351 Because the <filename>RDEPENDS</filename> variable applies
2352 to packages being built, you should 2352 to packages being built, you should
2353 always attach a package name to the variable to specify the 2353 always attach a package name to the variable to specify the
2354 particular run-time package that has the dependency. 2354 particular run-time package that has the dependency.
2355 For example, suppose you are building a development package 2355 For example, suppose you are building a development package
2356 that depends on the <filename>perl</filename> package. 2356 that depends on the <filename>perl</filename> package.
2357 In this case, you would use the following 2357 In this case, you would use the following
2358 <filename>RDEPENDS</filename> statement: 2358 <filename>RDEPENDS</filename> statement:
2359 <literallayout class='monospaced'> 2359 <literallayout class='monospaced'>
2360 RDEPENDS_${PN}-dev += "perl" 2360 RDEPENDS_${PN}-dev += "perl"
2361 </literallayout> 2361 </literallayout>
2362 In the example, the package name 2362 In the example, the package name
2363 (<filename>${PN}-dev</filename>) must appear as it would 2363 (<filename>${PN}-dev</filename>) must appear as it would
2364 in the 2364 in the
2365 <filename><link linkend='var-PACKAGES'>PACKAGES</link></filename> 2365 <filename><link linkend='var-PACKAGES'>PACKAGES</link></filename>
2366 namespace before any renaming of the output package by 2366 namespace before any renaming of the output package by
2367 classes like <filename>debian.bbclass</filename>. 2367 classes like <filename>debian.bbclass</filename>.
2368 </para> 2368 </para>
2369 2369
2370 <para> 2370 <para>
2371 In many cases you do not need to explicitly add dependencies 2371 In many cases you do not need to explicitly add dependencies
2372 to <filename>RDEPENDS</filename> since some automatic 2372 to <filename>RDEPENDS</filename> since some automatic
2373 handling occurs: 2373 handling occurs:
2374 <itemizedlist> 2374 <itemizedlist>
2375 <listitem><para><emphasis><filename>shlibdeps</filename></emphasis>: If 2375 <listitem><para><emphasis><filename>shlibdeps</filename></emphasis>: If
2376 a run-time package contains a shared library 2376 a run-time package contains a shared library
2377 (<filename>.so</filename>), the build 2377 (<filename>.so</filename>), the build
2378 processes the library in order to determine other 2378 processes the library in order to determine other
2379 libraries to which it is dynamically linked. 2379 libraries to which it is dynamically linked.
2380 The build process adds these libraries to 2380 The build process adds these libraries to
2381 <filename>RDEPENDS</filename> when creating the run-time 2381 <filename>RDEPENDS</filename> when creating the run-time
2382 package.</para></listitem> 2382 package.</para></listitem>
2383 <listitem><para><emphasis><filename>pcdeps</filename></emphasis>: If 2383 <listitem><para><emphasis><filename>pcdeps</filename></emphasis>: If
2384 the package ships a <filename>pkg-config</filename> 2384 the package ships a <filename>pkg-config</filename>
2385 information file, the build process uses this file 2385 information file, the build process uses this file
2386 to add items to the <filename>RDEPENDS</filename> 2386 to add items to the <filename>RDEPENDS</filename>
2387 variable to create the run-time packages. 2387 variable to create the run-time packages.
2388 </para></listitem> 2388 </para></listitem>
@@ -2394,11 +2394,11 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
2394 <glossentry id='var-RRECOMMENDS'><glossterm>RRECOMMENDS</glossterm> 2394 <glossentry id='var-RRECOMMENDS'><glossterm>RRECOMMENDS</glossterm>
2395 <glossdef> 2395 <glossdef>
2396 <para> 2396 <para>
2397 A list of packages that extend the usability of a package being 2397 A list of packages that extend the usability of a package being
2398 built. 2398 built.
2399 The package being built does not depend on this list of packages in 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. 2400 order to successfully build, but needs them for the extended usability.
2401 To specify runtime dependencies for packages, see the 2401 To specify runtime dependencies for packages, see the
2402 <filename><link linkend='var-RDEPENDS'>RDEPENDS</link></filename> variable. 2402 <filename><link linkend='var-RDEPENDS'>RDEPENDS</link></filename> variable.
2403 </para> 2403 </para>
2404 <para> 2404 <para>
@@ -2409,8 +2409,8 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
2409 process continues without an error. 2409 process continues without an error.
2410 </para> 2410 </para>
2411 <para> 2411 <para>
2412 Because the <filename>RRECOMMENDS</filename> variable applies to packages 2412 Because the <filename>RRECOMMENDS</filename> variable applies to packages
2413 being built, you should 2413 being built, you should
2414 always attach an override to the variable to specify the particular package 2414 always attach an override to the variable to specify the particular package
2415 whose usability is being extended. 2415 whose usability is being extended.
2416 For example, suppose you are building a development package that is extended 2416 For example, suppose you are building a development package that is extended
@@ -2419,9 +2419,9 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
2419 <literallayout class='monospaced'> 2419 <literallayout class='monospaced'>
2420 RRECOMMENDS_${PN}-dev += "&lt;wireless_package_name&gt;" 2420 RRECOMMENDS_${PN}-dev += "&lt;wireless_package_name&gt;"
2421 </literallayout> 2421 </literallayout>
2422 In the example, the package name (<filename>${PN}-dev</filename>) must 2422 In the example, the package name (<filename>${PN}-dev</filename>) must
2423 appear as it would in the 2423 appear as it would in the
2424 <filename><link linkend='var-PACKAGES'>PACKAGES</link></filename> namespace before any 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>. 2425 renaming of the output package by classes like <filename>debian.bbclass</filename>.
2426 </para> 2426 </para>
2427 </glossdef> 2427 </glossdef>
@@ -2442,22 +2442,22 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
2442 <para> 2442 <para>
2443 The location in the <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> 2443 The location in the <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
2444 where unpacked package source code resides. 2444 where unpacked package source code resides.
2445 This location is within the working directory 2445 This location is within the working directory
2446 (<filename><link linkend='var-WORKDIR'>WORKDIR</link></filename>), which 2446 (<filename><link linkend='var-WORKDIR'>WORKDIR</link></filename>), which
2447 is not static. 2447 is not static.
2448 The unpacked source location depends on the package name 2448 The unpacked source location depends on the package name
2449 (<filename><link linkend='var-PN'>PN</link></filename>) and 2449 (<filename><link linkend='var-PN'>PN</link></filename>) and
2450 package version (<filename><link linkend='var-PV'>PV</link></filename>) as 2450 package version (<filename><link linkend='var-PV'>PV</link></filename>) as
2451 follows: 2451 follows:
2452 <literallayout class='monospaced'> 2452 <literallayout class='monospaced'>
2453 ${WORKDIR}/${PN}-${PV} 2453 ${WORKDIR}/${PN}-${PV}
2454 </literallayout> 2454 </literallayout>
2455 As an example, assume a 2455 As an example, assume a
2456 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> top-level 2456 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> top-level
2457 folder named <filename>poky</filename> 2457 folder named <filename>poky</filename>
2458 and a default <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> 2458 and a default <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
2459 at <filename>poky/build</filename>. 2459 at <filename>poky/build</filename>.
2460 In this case, the working directory the build system uses to build 2460 In this case, the working directory the build system uses to build
2461 the <filename>db</filename> package is the following: 2461 the <filename>db</filename> package is the following:
2462 <literallayout class='monospaced'> 2462 <literallayout class='monospaced'>
2463 ~/poky/build/tmp/work/qemux86-poky-linux/db-5.1.19-r3/db-5.1.19 2463 ~/poky/build/tmp/work/qemux86-poky-linux/db-5.1.19-r3/db-5.1.19
@@ -2468,9 +2468,9 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
2468 2468
2469 <glossentry id='var-SDKIMAGE_FEATURES'><glossterm>SDKIMAGE_FEATURES</glossterm> 2469 <glossentry id='var-SDKIMAGE_FEATURES'><glossterm>SDKIMAGE_FEATURES</glossterm>
2470 <glossdef> 2470 <glossdef>
2471 <para>Equivalent to 2471 <para>Equivalent to
2472 <filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename>. 2472 <filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename>.
2473 However, this variable applies to the SDK generated from an image using 2473 However, this variable applies to the SDK generated from an image using
2474 <filename>bitbake -c populate_sdk imagename</filename>). 2474 <filename>bitbake -c populate_sdk imagename</filename>).
2475 </para> 2475 </para>
2476 </glossdef> 2476 </glossdef>
@@ -2486,10 +2486,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
2486 <glossentry id='var-SELECTED_OPTIMIZATION'><glossterm>SELECTED_OPTIMIZATION</glossterm> 2486 <glossentry id='var-SELECTED_OPTIMIZATION'><glossterm>SELECTED_OPTIMIZATION</glossterm>
2487 <glossdef> 2487 <glossdef>
2488 <para> 2488 <para>
2489 The variable takes the value of 2489 The variable takes the value of
2490 <filename><link linkend='var-FULL_OPTIMIZATION'>FULL_OPTIMIZATION</link></filename> 2490 <filename><link linkend='var-FULL_OPTIMIZATION'>FULL_OPTIMIZATION</link></filename>
2491 unless <filename><link linkend='var-DEBUG_BUILD'>DEBUG_BUILD</link></filename> = "1". 2491 unless <filename><link linkend='var-DEBUG_BUILD'>DEBUG_BUILD</link></filename> = "1".
2492 In this case the value of 2492 In this case the value of
2493 <filename><link linkend='var-DEBUG_OPTIMIZATION'>DEBUG_OPTIMIZATION</link></filename> is used. 2493 <filename><link linkend='var-DEBUG_OPTIMIZATION'>DEBUG_OPTIMIZATION</link></filename> is used.
2494 </para> 2494 </para>
2495 </glossdef> 2495 </glossdef>
@@ -2498,7 +2498,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
2498 2498
2499 <glossentry id='var-SERIAL_CONSOLE'><glossterm>SERIAL_CONSOLE</glossterm> 2499 <glossentry id='var-SERIAL_CONSOLE'><glossterm>SERIAL_CONSOLE</glossterm>
2500 <glossdef> 2500 <glossdef>
2501 <para>The speed and device for the serial port used to attach the serial console. 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" 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 2503 parameter and after booting occurs <filename>getty</filename> is started on that port
2504 so remote login is possible.</para> 2504 so remote login is possible.</para>
@@ -2508,7 +2508,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
2508 <glossentry id='var-SITEINFO_ENDIANNESS'><glossterm>SITEINFO_ENDIANNESS</glossterm> 2508 <glossentry id='var-SITEINFO_ENDIANNESS'><glossterm>SITEINFO_ENDIANNESS</glossterm>
2509 <glossdef> 2509 <glossdef>
2510 <para> 2510 <para>
2511 Specifies the endian byte order of the target system. 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. 2512 The value should be either "le" for little-endian or "be" for big-endian.
2513 </para> 2513 </para>
2514 </glossdef> 2514 </glossdef>
@@ -2526,7 +2526,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
2526 <glossentry id='var-SPECIAL_PKGSUFFIX'><glossterm>SPECIAL_PKGSUFFIX</glossterm> 2526 <glossentry id='var-SPECIAL_PKGSUFFIX'><glossterm>SPECIAL_PKGSUFFIX</glossterm>
2527 <glossdef> 2527 <glossdef>
2528 <para> 2528 <para>
2529 A list of prefixes for <link linkend='var-PN'><filename>PN</filename></link> used by the 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. 2530 OpenEmbedded build system to create variants of recipes or packages.
2531 The list specifies the prefixes to strip off during certain circumstances 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. 2532 such as the generation of the <link linkend='var-BPN'><filename>BPN</filename></link> variable.
@@ -2539,7 +2539,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
2539 <para>The list of source files - local or remote. 2539 <para>The list of source files - local or remote.
2540 This variable tells the OpenEmbedded build system which bits to pull 2540 This variable tells the OpenEmbedded build system which bits to pull
2541 in for the build and how to pull them in. 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 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. 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 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 2545 two patches, and include a custom file, the recipe would include four
@@ -2547,120 +2547,120 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
2547 <para>The following list explains the available URI protocols: 2547 <para>The following list explains the available URI protocols:
2548 <itemizedlist> 2548 <itemizedlist>
2549 <listitem><para><emphasis><filename>file://</filename> -</emphasis> Fetches files, which is usually 2549 <listitem><para><emphasis><filename>file://</filename> -</emphasis> Fetches files, which is usually
2550 a file shipped with the metadata, from the local machine. 2550 a file shipped with the metadata, from the local machine.
2551 The path is relative to the 2551 The path is relative to the
2552 <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link> 2552 <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>
2553 variable. 2553 variable.
2554 Thus, the build system searches, in order, from the following directories, 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 2555 which are assumed to be a subdirectories of the directory in which the
2556 recipe file resides: 2556 recipe file resides:
2557 <itemizedlist> 2557 <itemizedlist>
2558 <listitem><para><emphasis><filename>${PN}</filename> -</emphasis> The recipe name 2558 <listitem><para><emphasis><filename>${PN}</filename> -</emphasis> The recipe name
2559 with any special suffix or prefix, if applicable. 2559 with any special suffix or prefix, if applicable.
2560 For example, using <filename>bash</filename> to build for the native 2560 For example, using <filename>bash</filename> to build for the native
2561 machine, <filename>PN</filename> is <filename>bash-native</filename>. 2561 machine, <filename>PN</filename> is <filename>bash-native</filename>.
2562 Using <filename>bash</filename> to build for the target and for Multilib, 2562 Using <filename>bash</filename> to build for the target and for Multilib,
2563 <filename>PN</filename> would be <filename>bash</filename> and 2563 <filename>PN</filename> would be <filename>bash</filename> and
2564 <filename>lib64-bash</filename>, respectively. 2564 <filename>lib64-bash</filename>, respectively.
2565 </para></listitem> 2565 </para></listitem>
2566 <listitem><para><emphasis><filename>${PF}</filename> - </emphasis> 2566 <listitem><para><emphasis><filename>${PF}</filename> - </emphasis>
2567 <filename>${PN}-${EXTENDPE}${PV}-${PR}</filename>. 2567 <filename>${PN}-${EXTENDPE}${PV}-${PR}</filename>.
2568 The recipe name including all version and revision numbers 2568 The recipe name including all version and revision numbers
2569 (i.e. <filename>eglibc-2.13-r20+svnr15508/</filename> and 2569 (i.e. <filename>eglibc-2.13-r20+svnr15508/</filename> and
2570 <filename>bash-4.2-r1/</filename>).</para></listitem> 2570 <filename>bash-4.2-r1/</filename>).</para></listitem>
2571 <listitem><para><emphasis><filename>${P}</filename> -</emphasis> 2571 <listitem><para><emphasis><filename>${P}</filename> -</emphasis>
2572 <filename>${PN}-${PV}</filename>. 2572 <filename>${PN}-${PV}</filename>.
2573 The recipe name and version (i.e. <filename>bash-4.2</filename>). 2573 The recipe name and version (i.e. <filename>bash-4.2</filename>).
2574 </para></listitem> 2574 </para></listitem>
2575 <listitem><para><emphasis><filename>${BPN}</filename> -</emphasis> The 2575 <listitem><para><emphasis><filename>${BPN}</filename> -</emphasis> The
2576 base recipe name without any special suffix or version numbers. 2576 base recipe name without any special suffix or version numbers.
2577 </para></listitem> 2577 </para></listitem>
2578 <listitem><para><emphasis><filename>${BP}</filename> -</emphasis> 2578 <listitem><para><emphasis><filename>${BP}</filename> -</emphasis>
2579 <filename>${BPN}-${PV}</filename>. 2579 <filename>${BPN}-${PV}</filename>.
2580 The base recipe name and version but without any special 2580 The base recipe name and version but without any special
2581 package name suffix.</para></listitem> 2581 package name suffix.</para></listitem>
2582 <listitem><para><emphasis>Files -</emphasis> Files beneath the directory in which the recipe 2582 <listitem><para><emphasis>Files -</emphasis> Files beneath the directory in which the recipe
2583 resides.</para></listitem> 2583 resides.</para></listitem>
2584 <listitem><para><emphasis>Directory -</emphasis> The directory itself in which the recipe 2584 <listitem><para><emphasis>Directory -</emphasis> The directory itself in which the recipe
2585 resides.</para></listitem> 2585 resides.</para></listitem>
2586 </itemizedlist></para></listitem> 2586 </itemizedlist></para></listitem>
2587 <listitem><para><emphasis><filename>bzr://</filename> -</emphasis> Fetches files from a 2587 <listitem><para><emphasis><filename>bzr://</filename> -</emphasis> Fetches files from a
2588 Bazaar revision control repository.</para></listitem> 2588 Bazaar revision control repository.</para></listitem>
2589 <listitem><para><emphasis><filename>git://</filename> -</emphasis> Fetches files from a 2589 <listitem><para><emphasis><filename>git://</filename> -</emphasis> Fetches files from a
2590 Git revision control repository.</para></listitem> 2590 Git revision control repository.</para></listitem>
2591 <listitem><para><emphasis><filename>osc://</filename> -</emphasis> Fetches files from 2591 <listitem><para><emphasis><filename>osc://</filename> -</emphasis> Fetches files from
2592 an OSC (OpenSuse Build service) revision control repository.</para></listitem> 2592 an OSC (OpenSuse Build service) revision control repository.</para></listitem>
2593 <listitem><para><emphasis><filename>repo://</filename> -</emphasis> Fetches files from 2593 <listitem><para><emphasis><filename>repo://</filename> -</emphasis> Fetches files from
2594 a repo (Git) repository.</para></listitem> 2594 a repo (Git) repository.</para></listitem>
2595 <listitem><para><emphasis><filename>svk://</filename> -</emphasis> Fetches files from 2595 <listitem><para><emphasis><filename>svk://</filename> -</emphasis> Fetches files from
2596 an SVK revision control repository.</para></listitem> 2596 an SVK revision control repository.</para></listitem>
2597 <listitem><para><emphasis><filename>http://</filename> -</emphasis> Fetches files from 2597 <listitem><para><emphasis><filename>http://</filename> -</emphasis> Fetches files from
2598 the Internet using <filename>http</filename>.</para></listitem> 2598 the Internet using <filename>http</filename>.</para></listitem>
2599 <listitem><para><emphasis><filename>https://</filename> -</emphasis> Fetches files 2599 <listitem><para><emphasis><filename>https://</filename> -</emphasis> Fetches files
2600 from the Internet using <filename>https</filename>.</para></listitem> 2600 from the Internet using <filename>https</filename>.</para></listitem>
2601 <listitem><para><emphasis><filename>ftp://</filename> -</emphasis> Fetches files 2601 <listitem><para><emphasis><filename>ftp://</filename> -</emphasis> Fetches files
2602 from the Internet using <filename>ftp</filename>.</para></listitem> 2602 from the Internet using <filename>ftp</filename>.</para></listitem>
2603 <listitem><para><emphasis><filename>cvs://</filename> -</emphasis> Fetches files from 2603 <listitem><para><emphasis><filename>cvs://</filename> -</emphasis> Fetches files from
2604 a CVS revision control repository.</para></listitem> 2604 a CVS revision control repository.</para></listitem>
2605 <listitem><para><emphasis><filename>hg://</filename> -</emphasis> Fetches files from 2605 <listitem><para><emphasis><filename>hg://</filename> -</emphasis> Fetches files from
2606 a Mercurial (<filename>hg</filename>) revision control repository.</para></listitem> 2606 a Mercurial (<filename>hg</filename>) revision control repository.</para></listitem>
2607 <listitem><para><emphasis><filename>p4://</filename> -</emphasis> Fetches files from 2607 <listitem><para><emphasis><filename>p4://</filename> -</emphasis> Fetches files from
2608 a Perforce (<filename>p4</filename>) revision control repository.</para></listitem> 2608 a Perforce (<filename>p4</filename>) revision control repository.</para></listitem>
2609 <listitem><para><emphasis><filename>ssh://</filename> -</emphasis> Fetches files from 2609 <listitem><para><emphasis><filename>ssh://</filename> -</emphasis> Fetches files from
2610 a secure shell.</para></listitem> 2610 a secure shell.</para></listitem>
2611 <listitem><para><emphasis><filename>svn://</filename> -</emphasis> Fetches files from 2611 <listitem><para><emphasis><filename>svn://</filename> -</emphasis> Fetches files from
2612 a Subversion (<filename>svn</filename>) revision control repository.</para></listitem> 2612 a Subversion (<filename>svn</filename>) revision control repository.</para></listitem>
2613 </itemizedlist> 2613 </itemizedlist>
2614 </para> 2614 </para>
2615 <para>Standard and recipe-specific options for <filename>SRC_URI</filename> exist. 2615 <para>Standard and recipe-specific options for <filename>SRC_URI</filename> exist.
2616 Here are standard options: 2616 Here are standard options:
2617 <itemizedlist> 2617 <itemizedlist>
2618 <listitem><para><emphasis><filename>apply</filename> -</emphasis> Whether to apply 2618 <listitem><para><emphasis><filename>apply</filename> -</emphasis> Whether to apply
2619 the patch or not. 2619 the patch or not.
2620 The default action is to apply the patch.</para></listitem> 2620 The default action is to apply the patch.</para></listitem>
2621 <listitem><para><emphasis><filename>striplevel</filename> -</emphasis> Which 2621 <listitem><para><emphasis><filename>striplevel</filename> -</emphasis> Which
2622 striplevel to use when applying the patch. 2622 striplevel to use when applying the patch.
2623 The default level is 1.</para></listitem> 2623 The default level is 1.</para></listitem>
2624 </itemizedlist> 2624 </itemizedlist>
2625 </para> 2625 </para>
2626 <para>Here are options specific to recipes building code from a revision control system: 2626 <para>Here are options specific to recipes building code from a revision control system:
2627 <itemizedlist> 2627 <itemizedlist>
2628 <listitem><para><emphasis><filename>mindate</filename> -</emphasis> Only applies 2628 <listitem><para><emphasis><filename>mindate</filename> -</emphasis> Only applies
2629 the patch if <link linkend='var-SRCDATE'><filename>SRCDATE</filename></link> 2629 the patch if <link linkend='var-SRCDATE'><filename>SRCDATE</filename></link>
2630 is equal to or greater than <filename>mindate</filename>.</para></listitem> 2630 is equal to or greater than <filename>mindate</filename>.</para></listitem>
2631 <listitem><para><emphasis><filename>maxdate</filename> -</emphasis> Only applies 2631 <listitem><para><emphasis><filename>maxdate</filename> -</emphasis> Only applies
2632 the patch if <link linkend='var-SRCDATE'><filename>SRCDATE</filename></link> 2632 the patch if <link linkend='var-SRCDATE'><filename>SRCDATE</filename></link>
2633 is not later than <filename>mindate</filename>.</para></listitem> 2633 is not later than <filename>mindate</filename>.</para></listitem>
2634 <listitem><para><emphasis><filename>minrev</filename> -</emphasis> Only applies 2634 <listitem><para><emphasis><filename>minrev</filename> -</emphasis> Only applies
2635 the patch if <link linkend='var-SRCREV'><filename>SRCREV</filename></link> 2635 the patch if <link linkend='var-SRCREV'><filename>SRCREV</filename></link>
2636 is equal to or greater than <filename>minrev</filename>.</para></listitem> 2636 is equal to or greater than <filename>minrev</filename>.</para></listitem>
2637 <listitem><para><emphasis><filename>maxrev</filename> -</emphasis> Only applies 2637 <listitem><para><emphasis><filename>maxrev</filename> -</emphasis> Only applies
2638 the patch if <link linkend='var-SRCREV'><filename>SRCREV</filename></link> 2638 the patch if <link linkend='var-SRCREV'><filename>SRCREV</filename></link>
2639 is not later than <filename>maxrev</filename>.</para></listitem> 2639 is not later than <filename>maxrev</filename>.</para></listitem>
2640 <listitem><para><emphasis><filename>rev</filename> -</emphasis> Only applies the 2640 <listitem><para><emphasis><filename>rev</filename> -</emphasis> Only applies the
2641 patch if <link linkend='var-SRCREV'><filename>SRCREV</filename></link> 2641 patch if <link linkend='var-SRCREV'><filename>SRCREV</filename></link>
2642 is equal to <filename>rev</filename>.</para></listitem> 2642 is equal to <filename>rev</filename>.</para></listitem>
2643 <listitem><para><emphasis><filename>notrev</filename> -</emphasis> Only applies 2643 <listitem><para><emphasis><filename>notrev</filename> -</emphasis> Only applies
2644 the patch if <link linkend='var-SRCREV'><filename>SRCREV</filename></link> 2644 the patch if <link linkend='var-SRCREV'><filename>SRCREV</filename></link>
2645 is not equal to <filename>rev</filename>.</para></listitem> 2645 is not equal to <filename>rev</filename>.</para></listitem>
2646 </itemizedlist> 2646 </itemizedlist>
2647 </para> 2647 </para>
2648 <para>Here are some additional options worth mentioning: 2648 <para>Here are some additional options worth mentioning:
2649 <itemizedlist> 2649 <itemizedlist>
2650 <listitem><para><emphasis><filename>unpack</filename> -</emphasis> Controls 2650 <listitem><para><emphasis><filename>unpack</filename> -</emphasis> Controls
2651 whether or not to unpack the file if it is an archive. 2651 whether or not to unpack the file if it is an archive.
2652 The default action is to upack the file.</para></listitem> 2652 The default action is to upack the file.</para></listitem>
2653 <listitem><para><emphasis><filename>subdir</filename> -</emphasis> Places the file 2653 <listitem><para><emphasis><filename>subdir</filename> -</emphasis> Places the file
2654 (or extracts its contents) into the specified 2654 (or extracts its contents) into the specified
2655 subdirectory of <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>. 2655 subdirectory of <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>.
2656 This option is useful for unusual tarballs or other archives that 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. 2657 don't have their files already in a subdirectory within the archive.
2658 </para></listitem> 2658 </para></listitem>
2659 <listitem><para><emphasis><filename>name</filename> -</emphasis> Specifies a 2659 <listitem><para><emphasis><filename>name</filename> -</emphasis> Specifies a
2660 name to be used for association with <filename>SRC_URI</filename> checksums 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>. 2661 when you have more than one file specified in <filename>SRC_URI</filename>.
2662 </para></listitem> 2662 </para></listitem>
2663 <listitem><para><emphasis><filename>downloadfilename</filename> -</emphasis> Specifies 2663 <listitem><para><emphasis><filename>downloadfilename</filename> -</emphasis> Specifies
2664 the filename used when storing the downloaded file.</para></listitem> 2664 the filename used when storing the downloaded file.</para></listitem>
2665 </itemizedlist> 2665 </itemizedlist>
2666 </para> 2666 </para>
@@ -2671,11 +2671,11 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
2671 <glossdef> 2671 <glossdef>
2672 <para></para> 2672 <para></para>
2673 <para> 2673 <para>
2674 By default, the OpenEmbedded build system automatically detects whether 2674 By default, the OpenEmbedded build system automatically detects whether
2675 <filename><link linkend='var-SRC_URI'>SRC_URI</link></filename> 2675 <filename><link linkend='var-SRC_URI'>SRC_URI</link></filename>
2676 contains files that are machine-specific. 2676 contains files that are machine-specific.
2677 If so, the build system automatically changes 2677 If so, the build system automatically changes
2678 <filename><link linkend='var-PACKAGE_ARCH'>PACKAGE_ARCH</link></filename>. 2678 <filename><link linkend='var-PACKAGE_ARCH'>PACKAGE_ARCH</link></filename>.
2679 Setting this variable to "0" disables this behavior. 2679 Setting this variable to "0" disables this behavior.
2680 </para> 2680 </para>
2681 </glossdef> 2681 </glossdef>
@@ -2695,7 +2695,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
2695 <para> 2695 <para>
2696 The revision of the source code used to build the package. 2696 The revision of the source code used to build the package.
2697 This variable applies to Subversion, Git, Mercurial and Bazaar 2697 This variable applies to Subversion, Git, Mercurial and Bazaar
2698 only. 2698 only.
2699 Note that if you wish to build a fixed revision and you wish 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 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 2701 BitBake parses your recipe, you should specify a <filename>SRCREV</filename> that is a
@@ -2713,30 +2713,30 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
2713 <glossentry id='var-SSTATE_MIRRORS'><glossterm>SSTATE_MIRRORS</glossterm> 2713 <glossentry id='var-SSTATE_MIRRORS'><glossterm>SSTATE_MIRRORS</glossterm>
2714 <glossdef> 2714 <glossdef>
2715 <para> 2715 <para>
2716 Configures the OpenEmbedded build system to search other 2716 Configures the OpenEmbedded build system to search other
2717 mirror locations for prebuilt cache data objects before 2717 mirror locations for prebuilt cache data objects before
2718 building out the data. 2718 building out the data.
2719 This variable works like fetcher 2719 This variable works like fetcher
2720 <filename>MIRRORS</filename>/<filename>PREMIRRORS</filename> 2720 <filename>MIRRORS</filename>/<filename>PREMIRRORS</filename>
2721 and points to the cache locations to check for the shared 2721 and points to the cache locations to check for the shared
2722 objects. 2722 objects.
2723 </para> 2723 </para>
2724 2724
2725 <para> 2725 <para>
2726 You can specify a filesystem directory or a remote URL such 2726 You can specify a filesystem directory or a remote URL such
2727 as HTTP or FTP. 2727 as HTTP or FTP.
2728 The locations you specify need to contain the shared state 2728 The locations you specify need to contain the shared state
2729 cache (sstate-cache) results from previous builds. 2729 cache (sstate-cache) results from previous builds.
2730 The sstate-cache you point to can also be from builds on 2730 The sstate-cache you point to can also be from builds on
2731 other machines. 2731 other machines.
2732 </para> 2732 </para>
2733 2733
2734 <para> 2734 <para>
2735 If a mirror uses the same structure as 2735 If a mirror uses the same structure as
2736 <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link>, 2736 <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link>,
2737 you need to add 2737 you need to add
2738 "PATH" at the end as shown in the examples below. 2738 "PATH" at the end as shown in the examples below.
2739 The build system substitues the correct path within the 2739 The build system substitues the correct path within the
2740 directory structure. 2740 directory structure.
2741 <literallayout class='monospaced'> 2741 <literallayout class='monospaced'>
2742 SSTATE_MIRRORS ?= "\ 2742 SSTATE_MIRRORS ?= "\
@@ -2761,14 +2761,14 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
2761 <para> 2761 <para>
2762 Specifies the base path used to create recipe stamp files. 2762 Specifies the base path used to create recipe stamp files.
2763 The path to an actual stamp file is constructed by evaluating this 2763 The path to an actual stamp file is constructed by evaluating this
2764 string and then appending additional information. 2764 string and then appending additional information.
2765 Currently, the default assignment for <filename>STAMP</filename> 2765 Currently, the default assignment for <filename>STAMP</filename>
2766 as set in the <filename>meta/conf/bitbake.conf</filename> file 2766 as set in the <filename>meta/conf/bitbake.conf</filename> file
2767 is: 2767 is:
2768 <literallayout class='monospaced'> 2768 <literallayout class='monospaced'>
2769 STAMP = "${TMPDIR}/stamps/${MULTIMACH_TARGET_SYS}/${PN}-${EXTENDPE}${PV}-${PR}" 2769 STAMP = "${TMPDIR}/stamps/${MULTIMACH_TARGET_SYS}/${PN}-${EXTENDPE}${PV}-${PR}"
2770 </literallayout> 2770 </literallayout>
2771 See <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>, 2771 See <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>,
2772 <link linkend='var-MULTIMACH_TARGET_SYS'><filename>MULTIMACH_TARGET_SYS</filename></link>, 2772 <link linkend='var-MULTIMACH_TARGET_SYS'><filename>MULTIMACH_TARGET_SYS</filename></link>,
2773 <link linkend='var-PN'><filename>PN</filename></link>, 2773 <link linkend='var-PN'><filename>PN</filename></link>,
2774 <link linkend='var-EXTENDPE'><filename>EXTENDPE</filename></link>, 2774 <link linkend='var-EXTENDPE'><filename>EXTENDPE</filename></link>,
@@ -2781,12 +2781,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
2781 2781
2782 <glossentry id='var-SUMMARY'><glossterm>SUMMARY</glossterm> 2782 <glossentry id='var-SUMMARY'><glossterm>SUMMARY</glossterm>
2783 <glossdef> 2783 <glossdef>
2784 <para>The short (72 characters or less) summary of the binary package for packaging 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 2785 systems such as <filename>opkg</filename>, <filename>rpm</filename> or
2786 <filename>dpkg</filename>. 2786 <filename>dpkg</filename>.
2787 By default, <filename>SUMMARY</filename> is used to define 2787 By default, <filename>SUMMARY</filename> is used to define
2788 the <link linkend='var-DESCRIPTION'><filename>DESCRIPTION</filename></link> 2788 the <link linkend='var-DESCRIPTION'><filename>DESCRIPTION</filename></link>
2789 variable if <filename>DESCRIPTION</filename> is not set 2789 variable if <filename>DESCRIPTION</filename> is not set
2790 in the recipe. 2790 in the recipe.
2791 </para> 2791 </para>
2792 </glossdef> 2792 </glossdef>
@@ -2798,18 +2798,18 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
2798 2798
2799 <glossentry id='var-T'><glossterm>T</glossterm> 2799 <glossentry id='var-T'><glossterm>T</glossterm>
2800 <glossdef> 2800 <glossdef>
2801 <para>This variable points to a directory were Bitbake places temporary 2801 <para>This variable points to a directory were Bitbake places temporary
2802 files when building a particular package. 2802 files when building a particular package.
2803 It is typically set as follows: 2803 It is typically set as follows:
2804 <literallayout class='monospaced'> 2804 <literallayout class='monospaced'>
2805 T = ${WORKDIR}/temp 2805 T = ${WORKDIR}/temp
2806 </literallayout> 2806 </literallayout>
2807 The <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link> 2807 The <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>
2808 is the directory into which Bitbake unpacks and builds the package. 2808 is the directory into which Bitbake unpacks and builds the package.
2809 The default <filename>bitbake.conf</filename> file sets this variable.</para> 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 2810 <para>The <filename>T</filename> variable is not to be confused with
2811 the <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link> variable, 2811 the <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link> variable,
2812 which points to the root of the directory tree where Bitbake 2812 which points to the root of the directory tree where Bitbake
2813 places the output of an entire build. 2813 places the output of an entire build.
2814 </para> 2814 </para>
2815 </glossdef> 2815 </glossdef>
@@ -2817,7 +2817,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
2817 2817
2818 <glossentry id='var-TARGET_ARCH'><glossterm>TARGET_ARCH</glossterm> 2818 <glossentry id='var-TARGET_ARCH'><glossterm>TARGET_ARCH</glossterm>
2819 <glossdef> 2819 <glossdef>
2820 <para>The architecture of the device being built. 2820 <para>The architecture of the device being built.
2821 While a number of values are possible, the OpenEmbedded build system primarily supports 2821 While a number of values are possible, the OpenEmbedded build system primarily supports
2822 <filename>arm</filename> and <filename>i586</filename>.</para> 2822 <filename>arm</filename> and <filename>i586</filename>.</para>
2823 </glossdef> 2823 </glossdef>
@@ -2826,8 +2826,8 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
2826 <glossentry id='var-TARGET_CFLAGS'><glossterm>TARGET_CFLAGS</glossterm> 2826 <glossentry id='var-TARGET_CFLAGS'><glossterm>TARGET_CFLAGS</glossterm>
2827 <glossdef> 2827 <glossdef>
2828 <para> 2828 <para>
2829 Flags passed to the C compiler for the target system. 2829 Flags passed to the C compiler for the target system.
2830 This variable evaluates to the same as 2830 This variable evaluates to the same as
2831 <filename><link linkend='var-CFLAGS'>CFLAGS</link></filename>. 2831 <filename><link linkend='var-CFLAGS'>CFLAGS</link></filename>.
2832 </para> 2832 </para>
2833 </glossdef> 2833 </glossdef>
@@ -2836,7 +2836,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
2836 2836
2837 <glossentry id='var-TARGET_FPU'><glossterm>TARGET_FPU</glossterm> 2837 <glossentry id='var-TARGET_FPU'><glossterm>TARGET_FPU</glossterm>
2838 <glossdef> 2838 <glossdef>
2839 <para>Specifies the method for handling FPU code. 2839 <para>Specifies the method for handling FPU code.
2840 For FPU-less targets, which include most ARM CPUs, the variable must be 2840 For FPU-less targets, which include most ARM CPUs, the variable must be
2841 set to "soft". 2841 set to "soft".
2842 If not, the kernel emulation gets used, which results in a performance penalty.</para> 2842 If not, the kernel emulation gets used, which results in a performance penalty.</para>
@@ -2845,9 +2845,9 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
2845 2845
2846 <glossentry id='var-TARGET_OS'><glossterm>TARGET_OS</glossterm> 2846 <glossentry id='var-TARGET_OS'><glossterm>TARGET_OS</glossterm>
2847 <glossdef> 2847 <glossdef>
2848 <para>Specifies the target's operating system. 2848 <para>Specifies the target's operating system.
2849 The variable can be set to "linux" for <filename>eglibc</filename>-based systems and 2849 The variable can be set to "linux" for <filename>eglibc</filename>-based systems and
2850 to "linux-uclibc" for <filename>uclibc</filename>. 2850 to "linux-uclibc" for <filename>uclibc</filename>.
2851 For ARM/EABI targets, there are also "linux-gnueabi" and 2851 For ARM/EABI targets, there are also "linux-gnueabi" and
2852 "linux-uclibc-gnueabi" values possible.</para> 2852 "linux-uclibc-gnueabi" values possible.</para>
2853 </glossdef> 2853 </glossdef>
@@ -2864,7 +2864,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
2864 <para> 2864 <para>
2865 You can select <filename>eglibc</filename> or <filename>uclibc</filename>. 2865 You can select <filename>eglibc</filename> or <filename>uclibc</filename>.
2866 <note> 2866 <note>
2867 This release of the Yocto Project does not support the 2867 This release of the Yocto Project does not support the
2868 <filename>glibc</filename> implementation of <filename>libc</filename>. 2868 <filename>glibc</filename> implementation of <filename>libc</filename>.
2869 </note> 2869 </note>
2870 </para> 2870 </para>
@@ -2874,7 +2874,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
2874 <glossentry id='var-TCMODE'><glossterm>TCMODE</glossterm> 2874 <glossentry id='var-TCMODE'><glossterm>TCMODE</glossterm>
2875 <glossdef> 2875 <glossdef>
2876 <para> 2876 <para>
2877 The toolchain selector. 2877 The toolchain selector.
2878 This variable replaces <filename>POKYMODE</filename>, which is no longer 2878 This variable replaces <filename>POKYMODE</filename>, which is no longer
2879 supported. 2879 supported.
2880 </para> 2880 </para>
@@ -2882,39 +2882,39 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
2882 The <filename>TCMODE</filename> variable selects the external toolchain 2882 The <filename>TCMODE</filename> variable selects the external toolchain
2883 built using the OpenEmbedded build system or a few supported combinations of 2883 built using the OpenEmbedded build system or a few supported combinations of
2884 the upstream GCC or CodeSourcery Labs toolchain. 2884 the upstream GCC or CodeSourcery Labs toolchain.
2885 The variable identifies the <filename>tcmode-*</filename> files used in 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 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>. 2887 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
2888 </para> 2888 </para>
2889 <para> 2889 <para>
2890 By default, <filename>TCMODE</filename> is set to "default", which 2890 By default, <filename>TCMODE</filename> is set to "default", which
2891 chooses the <filename>tcmode-default.inc</filename> file. 2891 chooses the <filename>tcmode-default.inc</filename> file.
2892 The variable is similar to 2892 The variable is similar to
2893 <link linkend='var-TCLIBC'><filename>TCLIBC</filename></link>, which controls 2893 <link linkend='var-TCLIBC'><filename>TCLIBC</filename></link>, which controls
2894 the variant of the GNU standard C library (<filename>libc</filename>) 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>. 2895 used during the build process: <filename>eglibc</filename> or <filename>uclibc</filename>.
2896 </para> 2896 </para>
2897 </glossdef> 2897 </glossdef>
2898 </glossentry> 2898 </glossentry>
2899 2899
2900 <glossentry id='var-TMPDIR'><glossterm>TMPDIR</glossterm> 2900 <glossentry id='var-TMPDIR'><glossterm>TMPDIR</glossterm>
2901 <glossdef> 2901 <glossdef>
2902 <para> 2902 <para>
2903 This variable is the temporary directory the OpenEmbedded build system 2903 This variable is the temporary directory the OpenEmbedded build system
2904 uses when it does its work building images. 2904 uses when it does its work building images.
2905 By default, the <filename>TMPDIR</filename> variable is named 2905 By default, the <filename>TMPDIR</filename> variable is named
2906 <filename>tmp</filename> within the 2906 <filename>tmp</filename> within the
2907 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. 2907 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
2908 </para> 2908 </para>
2909 2909
2910 <para> 2910 <para>
2911 If you want to establish this directory in a location other than the 2911 If you want to establish this directory in a location other than the
2912 default, you can uncomment the following statement in the 2912 default, you can uncomment the following statement in the
2913 <filename>conf/local.conf</filename> file in the 2913 <filename>conf/local.conf</filename> file in the
2914 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>: 2914 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>:
2915 <literallayout class='monospaced'> 2915 <literallayout class='monospaced'>
2916 #TMPDIR = "${TOPDIR}/tmp" 2916 #TMPDIR = "${TOPDIR}/tmp"
2917 </literallayout> 2917 </literallayout>
2918 </para> 2918 </para>
2919 </glossdef> 2919 </glossdef>
2920 </glossentry> 2920 </glossentry>
@@ -2922,10 +2922,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
2922 <glossentry id='var-TOPDIR'><glossterm>TOPDIR</glossterm> 2922 <glossentry id='var-TOPDIR'><glossterm>TOPDIR</glossterm>
2923 <glossdef> 2923 <glossdef>
2924 <para> 2924 <para>
2925 This variable is the 2925 This variable is the
2926 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. 2926 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
2927 BitBake automatically sets this variable. 2927 BitBake automatically sets this variable.
2928 The OpenEmbedded build system uses the Build Directory when building images. 2928 The OpenEmbedded build system uses the Build Directory when building images.
2929 </para> 2929 </para>
2930 </glossdef> 2930 </glossdef>
2931 </glossentry> 2931 </glossentry>
@@ -2943,7 +2943,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
2943 <glossentry id='var-WORKDIR'><glossterm>WORKDIR</glossterm> 2943 <glossentry id='var-WORKDIR'><glossterm>WORKDIR</glossterm>
2944 <glossdef> 2944 <glossdef>
2945 <para> 2945 <para>
2946 The pathname of the working directory in which the OpenEmbedded build system 2946 The pathname of the working directory in which the OpenEmbedded build system
2947 builds a recipe. 2947 builds a recipe.
2948 This directory is located within the 2948 This directory is located within the
2949 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link> directory structure and changes 2949 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link> directory structure and changes
@@ -2964,17 +2964,17 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
2964 </para> 2964 </para>
2965 2965
2966 <para> 2966 <para>
2967 For packages that are not dependent on a particular machine, 2967 For packages that are not dependent on a particular machine,
2968 <filename>WORKDIR</filename> is defined as follows: 2968 <filename>WORKDIR</filename> is defined as follows:
2969 <literallayout class='monospaced'> 2969 <literallayout class='monospaced'>
2970 ${TMPDIR}/work/${PACKAGE_ARCH}-poky-${TARGET_OS}/${PN}-${PV}-${PR} 2970 ${TMPDIR}/work/${PACKAGE_ARCH}-poky-${TARGET_OS}/${PN}-${PV}-${PR}
2971 </literallayout> 2971 </literallayout>
2972 As an example, assume a 2972 As an example, assume a
2973 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> top-level 2973 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> top-level
2974 folder name <filename>poky</filename> and a default 2974 folder name <filename>poky</filename> and a default
2975 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> 2975 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
2976 at <filename>poky/build</filename>. 2976 at <filename>poky/build</filename>.
2977 In this case, the working directory the build system uses to build 2977 In this case, the working directory the build system uses to build
2978 the <filename>v86d</filename> package is the following: 2978 the <filename>v86d</filename> package is the following:
2979 <literallayout class='monospaced'> 2979 <literallayout class='monospaced'>
2980 ~/poky/build/tmp/work/qemux86-poky-linux/v86d-01.9-r0 2980 ~/poky/build/tmp/work/qemux86-poky-linux/v86d-01.9-r0
@@ -2987,11 +2987,11 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
2987 <literallayout class='monospaced'> 2987 <literallayout class='monospaced'>
2988 ${TMPDIR}/work/${MACHINE}-poky-${TARGET_OS}/${PN}-${PV}-${PR} 2988 ${TMPDIR}/work/${MACHINE}-poky-${TARGET_OS}/${PN}-${PV}-${PR}
2989 </literallayout> 2989 </literallayout>
2990 As an example, again assume a Source Directory top-level folder 2990 As an example, again assume a Source Directory top-level folder
2991 named <filename>poky</filename> and a default Build Directory 2991 named <filename>poky</filename> and a default Build Directory
2992 at <filename>poky/build</filename>. 2992 at <filename>poky/build</filename>.
2993 In this case, the working directory the build system uses to build 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 2994 the <filename>acl</filename> recipe, which is being built for a
2995 MIPS-based device, is the following: 2995 MIPS-based device, is the following:
2996 <literallayout class='monospaced'> 2996 <literallayout class='monospaced'>
2997 ~/poky/build/tmp/work/mips-poky-linux/acl-2.2.51-r2 2997 ~/poky/build/tmp/work/mips-poky-linux/acl-2.2.51-r2
@@ -3013,6 +3013,6 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
3013 3013
3014</glossary> 3014</glossary>
3015</chapter> 3015</chapter>
3016<!-- 3016<!--
3017vim: expandtab tw=80 ts=4 3017vim: expandtab tw=80 ts=4
3018--> 3018-->
diff --git a/documentation/poky-ref-manual/ref-varlocality.xml b/documentation/poky-ref-manual/ref-varlocality.xml
index a9db35fe4b..ae8f75c2f5 100644
--- a/documentation/poky-ref-manual/ref-varlocality.xml
+++ b/documentation/poky-ref-manual/ref-varlocality.xml
@@ -6,10 +6,10 @@
6 <title>Variable Context</title> 6 <title>Variable Context</title>
7 7
8 <para> 8 <para>
9 While most variables can be used in almost any context such as 9 While most variables can be used in almost any context such as
10 <filename>.conf</filename>, <filename>.bbclass</filename>, 10 <filename>.conf</filename>, <filename>.bbclass</filename>,
11 <filename>.inc</filename>, and <filename>.bb</filename> files, 11 <filename>.inc</filename>, and <filename>.bb</filename> files,
12 some variables are often associated with a particular locality or context. 12 some variables are often associated with a particular locality or context.
13 This chapter describes some common associations. 13 This chapter describes some common associations.
14 </para> 14 </para>
15 15
@@ -80,7 +80,7 @@
80 <title>Local</title> 80 <title>Local</title>
81 81
82 <para> 82 <para>
83 This section lists variables whose context is the local configuration through the 83 This section lists variables whose context is the local configuration through the
84 <filename>local.conf</filename> file. 84 <filename>local.conf</filename> file.
85 <itemizedlist> 85 <itemizedlist>
86 <listitem><para><filename><link linkend='var-DISTRO'>DISTRO</link></filename> 86 <listitem><para><filename><link linkend='var-DISTRO'>DISTRO</link></filename>
@@ -188,6 +188,6 @@
188 </section> 188 </section>
189 </section> 189 </section>
190</chapter> 190</chapter>
191<!-- 191<!--
192vim: expandtab tw=80 ts=4 spell spelllang=en_gb 192vim: expandtab tw=80 ts=4 spell spelllang=en_gb
193--> 193-->
diff --git a/documentation/poky-ref-manual/resources.xml b/documentation/poky-ref-manual/resources.xml
index 8c47b18ec7..a6916064f6 100644
--- a/documentation/poky-ref-manual/resources.xml
+++ b/documentation/poky-ref-manual/resources.xml
@@ -9,7 +9,7 @@
9 <title>Introduction</title> 9 <title>Introduction</title>
10 <para> 10 <para>
11 The Yocto Project team is happy for people to experiment with the Yocto Project. 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. 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, 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>" 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. 15 list item in the Yocto Project Development Manual.
@@ -20,7 +20,7 @@
20 <title>Tracking Bugs</title> 20 <title>Tracking Bugs</title>
21 21
22 <para> 22 <para>
23 If you find problems with the Yocto Project, you should report them using the 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>. 24 Bugzilla application at <ulink url='&YOCTO_BUGZILLA_URL;'></ulink>.
25 </para> 25 </para>
26</section> 26</section>
@@ -75,18 +75,18 @@
75 The company where the Yocto Project build system Poky was first developed. 75 The company where the Yocto Project build system Poky was first developed.
76 OpenedHand has since been acquired by Intel Corporation.</para></listitem> --> 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> 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 78 The company who acquired OpenedHand in 2008 and began development on the
79 Yocto Project.</para></listitem> 79 Yocto Project.</para></listitem>
80 <listitem><para><emphasis><ulink url='&OE_HOME_URL;'>OpenEmbedded</ulink>:</emphasis> 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 81 The upstream, generic, embedded distribution used as the basis for the build system in the
82 Yocto Project. 82 Yocto Project.
83 Poky derives from and contributes back to the OpenEmbedded project.</para></listitem> 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/'> 84 <listitem><para><emphasis><ulink url='http://developer.berlios.de/projects/bitbake/'>
85 BitBake</ulink>:</emphasis> The tool used to process metadata.</para></listitem> 85 BitBake</ulink>:</emphasis> The tool used to process metadata.</para></listitem>
86 <listitem><para><emphasis>BitBake User Manual:</emphasis> 86 <listitem><para><emphasis>BitBake User Manual:</emphasis>
87 A comprehensive guide to the BitBake tool. 87 A comprehensive guide to the BitBake tool.
88 You can find the BitBake User Manual in the <filename>bitbake/doc/manual</filename> 88 You can find the BitBake User Manual in the <filename>bitbake/doc/manual</filename>
89 directory, which is found in the 89 directory, which is found in the
90 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. 90 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
91 </para></listitem> 91 </para></listitem>
92 <listitem><para><emphasis><ulink url='http://wiki.qemu.org/Index.html'>QEMU</ulink>: 92 <listitem><para><emphasis><ulink url='http://wiki.qemu.org/Index.html'>QEMU</ulink>:
@@ -100,7 +100,7 @@
100 100
101 <para> 101 <para>
102 The Yocto Project gladly accepts contributions. 102 The Yocto Project gladly accepts contributions.
103 You can submit changes to the project either by creating and sending pull requests, 103 You can submit changes to the project either by creating and sending pull requests,
104 or by submitting patches through email. 104 or by submitting patches through email.
105 For information on how to do both, see the 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>" 106 "<ulink url='&YOCTO_DOCS_DEV_URL;#how-to-submit-a-change'>How to Submit a Change</ulink>"
@@ -109,6 +109,6 @@
109</section> 109</section>
110 110
111</chapter> 111</chapter>
112<!-- 112<!--
113vim: expandtab tw=80 ts=4 113vim: expandtab tw=80 ts=4
114--> 114-->
diff --git a/documentation/poky-ref-manual/technical-details.xml b/documentation/poky-ref-manual/technical-details.xml
index 042a96ed87..72689a0e22 100644
--- a/documentation/poky-ref-manual/technical-details.xml
+++ b/documentation/poky-ref-manual/technical-details.xml
@@ -6,7 +6,7 @@
6<title>Technical Details</title> 6<title>Technical Details</title>
7 7
8 <para> 8 <para>
9 This chapter provides technical details for various parts of the Yocto Project. 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. 10 Currently, topics include Yocto Project components and shared state (sstate) cache.
11 </para> 11 </para>
12 12
@@ -14,21 +14,21 @@
14 <title>Yocto Project Components</title> 14 <title>Yocto Project Components</title>
15 15
16 <para> 16 <para>
17 The BitBake task executor together with various types of configuration files form the 17 The BitBake task executor together with various types of configuration files form the
18 OpenEmbedded Core. 18 OpenEmbedded Core.
19 This section overviews the BitBake task executor and the 19 This section overviews the BitBake task executor and the
20 configuration files by describing what they are used for and how they interact. 20 configuration files by describing what they are used for and how they interact.
21 </para> 21 </para>
22 22
23 <para> 23 <para>
24 BitBake handles the parsing and execution of the data files. 24 BitBake handles the parsing and execution of the data files.
25 The data itself is of various types: 25 The data itself is of various types:
26 <itemizedlist> 26 <itemizedlist>
27 <listitem><para><emphasis>Recipes:</emphasis> Provides details about particular 27 <listitem><para><emphasis>Recipes:</emphasis> Provides details about particular
28 pieces of software</para></listitem> 28 pieces of software</para></listitem>
29 <listitem><para><emphasis>Class Data:</emphasis> An abstraction of common build 29 <listitem><para><emphasis>Class Data:</emphasis> An abstraction of common build
30 information (e.g. how to build a Linux kernel).</para></listitem> 30 information (e.g. how to build a Linux kernel).</para></listitem>
31 <listitem><para><emphasis>Configuration Data:</emphasis> Defines machine-specific settings, 31 <listitem><para><emphasis>Configuration Data:</emphasis> Defines machine-specific settings,
32 policy decisions, etc. 32 policy decisions, etc.
33 Configuration data acts as the glue to bind everything together.</para></listitem> 33 Configuration data acts as the glue to bind everything together.</para></listitem>
34 </itemizedlist> 34 </itemizedlist>
@@ -37,17 +37,17 @@
37 section in the Yocto Project Development Manual. 37 section in the Yocto Project Development Manual.
38 </para> 38 </para>
39 39
40 <para> 40 <para>
41 BitBake knows how to combine multiple data sources together and refers to each data source 41 BitBake knows how to combine multiple data sources together and refers to each data source
42 as a layer. 42 as a layer.
43 For information on layers, see the 43 For information on layers, see the
44 "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and 44 "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and
45 Creating Layers</ulink>" section of the Yocto Project Development Manual. 45 Creating Layers</ulink>" section of the Yocto Project Development Manual.
46 </para> 46 </para>
47 47
48 <para> 48 <para>
49 Following are some brief details on these core components. 49 Following are some brief details on these core components.
50 For more detailed information on these components see the 50 For more detailed information on these components see the
51 "<link linkend='ref-structure'>Directory Structure</link>" chapter. 51 "<link linkend='ref-structure'>Directory Structure</link>" chapter.
52 </para> 52 </para>
53 53
@@ -57,7 +57,7 @@
57 <para> 57 <para>
58 BitBake is the tool at the heart of the OpenEmbedded build system and is responsible 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, 59 for parsing the metadata, generating a list of tasks from it,
60 and then executing those tasks. 60 and then executing those tasks.
61 To see a list of the options BitBake supports, use the following help command: 61 To see a list of the options BitBake supports, use the following help command:
62 <literallayout class='monospaced'> 62 <literallayout class='monospaced'>
63 $ bitbake --help 63 $ bitbake --help
@@ -66,8 +66,8 @@
66 66
67 <para> 67 <para>
68 The most common usage for BitBake is <filename>bitbake &lt;packagename&gt;</filename>, where 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 69 <filename>packagename</filename> is the name of the package you want to build
70 (referred to as the "target" in this manual). 70 (referred to as the "target" in this manual).
71 The target often equates to the first part of a <filename>.bb</filename> filename. 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 72 So, to run the <filename>matchbox-desktop_1.2.3.bb</filename> file, you
73 might type the following: 73 might type the following:
@@ -76,15 +76,15 @@
76 </literallayout> 76 </literallayout>
77 Several different versions of <filename>matchbox-desktop</filename> might exist. 77 Several different versions of <filename>matchbox-desktop</filename> might exist.
78 BitBake chooses the one selected by the distribution configuration. 78 BitBake chooses the one selected by the distribution configuration.
79 You can get more details about how BitBake chooses between different 79 You can get more details about how BitBake chooses between different
80 target versions and providers in the 80 target versions and providers in the
81 "<link linkend='ref-bitbake-providers'>Preferences and Providers</link>" section. 81 "<link linkend='ref-bitbake-providers'>Preferences and Providers</link>" section.
82 </para> 82 </para>
83 83
84 <para> 84 <para>
85 BitBake also tries to execute any dependent tasks first. 85 BitBake also tries to execute any dependent tasks first.
86 So for example, before building <filename>matchbox-desktop</filename>, BitBake 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 87 would build a cross compiler and <filename>eglibc</filename> if they had not already
88 been built. 88 been built.
89 <note>This release of the Yocto Project does not support the <filename>glibc</filename> 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 90 GNU version of the Unix standard C library. By default, the OpenEmbedded build system
@@ -92,12 +92,12 @@
92 </para> 92 </para>
93 93
94 <para> 94 <para>
95 A useful BitBake option to consider is the <filename>-k</filename> or 95 A useful BitBake option to consider is the <filename>-k</filename> or
96 <filename>--continue</filename> option. 96 <filename>--continue</filename> option.
97 This option instructs BitBake to try and continue processing the job as much 97 This option instructs BitBake to try and continue processing the job as much
98 as possible even after encountering an error. 98 as possible even after encountering an error.
99 When an error occurs, the target that 99 When an error occurs, the target that
100 failed and those that depend on it cannot be remade. 100 failed and those that depend on it cannot be remade.
101 However, when you use this option other dependencies can still be processed. 101 However, when you use this option other dependencies can still be processed.
102 </para> 102 </para>
103 </section> 103 </section>
@@ -106,17 +106,17 @@
106 <title>Metadata (Recipes)</title> 106 <title>Metadata (Recipes)</title>
107 107
108 <para> 108 <para>
109 The <filename>.bb</filename> files are usually referred to as "recipes." 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. 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 111 The information includes the location from which to download the source patches
112 (if any are needed), which special configuration options to apply, 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. 113 how to compile the source files, and how to package the compiled output.
114 </para> 114 </para>
115 115
116 <para> 116 <para>
117 The term "package" can also be used to describe recipes. 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 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), 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. 120 this document avoids using the term "package" when referring to recipes.
121 </para> 121 </para>
122 </section> 122 </section>
@@ -126,7 +126,7 @@
126 126
127 <para> 127 <para>
128 Class files (<filename>.bbclass</filename>) contain information that is useful to share 128 Class files (<filename>.bbclass</filename>) contain information that is useful to share
129 between metadata files. 129 between metadata files.
130 An example is the Autotools class, which contains 130 An example is the Autotools class, which contains
131 common settings for any application that Autotools uses. 131 common settings for any application that Autotools uses.
132 The "<link linkend='ref-classes'>Classes</link>" chapter provides details 132 The "<link linkend='ref-classes'>Classes</link>" chapter provides details
@@ -139,8 +139,8 @@
139 139
140 <para> 140 <para>
141 The configuration files (<filename>.conf</filename>) define various configuration variables 141 The configuration files (<filename>.conf</filename>) define various configuration variables
142 that govern the OpenEmbedded build process. 142 that govern the OpenEmbedded build process.
143 These files fall into several areas that define machine configuration options, 143 These files fall into several areas that define machine configuration options,
144 distribution configuration options, compiler tuning options, general common configuration 144 distribution configuration options, compiler tuning options, general common configuration
145 options and user configuration options (<filename>local.conf</filename>, which is found 145 options and user configuration options (<filename>local.conf</filename>, which is found
146 in the <ulink url='build-directory'>Build Directory</ulink>). 146 in the <ulink url='build-directory'>Build Directory</ulink>).
@@ -152,19 +152,19 @@
152 <title>Shared State Cache</title> 152 <title>Shared State Cache</title>
153 153
154 <para> 154 <para>
155 By design, the OpenEmbedded build system builds everything from scratch unless 155 By design, the OpenEmbedded build system builds everything from scratch unless
156 BitBake can determine that parts don't need to be rebuilt. 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 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. 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 159 When developers hit problems, they typically default back to building from scratch
160 so they know the state of things from the start. 160 so they know the state of things from the start.
161 </para> 161 </para>
162 162
163 <para> 163 <para>
164 Building an image from scratch is both an advantage and a disadvantage to the process. 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 165 As mentioned in the previous paragraph, building from scratch ensures that
166 everything is current and starts from a known state. 166 everything is current and starts from a known state.
167 However, building from scratch also takes much longer as it generally means 167 However, building from scratch also takes much longer as it generally means
168 rebuilding things that don't necessarily need rebuilt. 168 rebuilding things that don't necessarily need rebuilt.
169 </para> 169 </para>
170 170
@@ -181,15 +181,15 @@
181 </para> 181 </para>
182 182
183 <para> 183 <para>
184 For the first question, the build system detects changes in the "inputs" to a given task by 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. 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 186 If the checksum changes, the system assumes the inputs have changed and the task needs to be
187 rerun. 187 rerun.
188 For the second question, the shared state (sstate) code tracks which tasks add which output 188 For the second question, the shared state (sstate) code tracks which tasks add which output
189 to the build process. 189 to the build process.
190 This means the output from a given task can be removed, upgraded or otherwise manipulated. 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 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 192 assuming the build system can fetch the sstate objects from remote locations and
193 install them if they are deemed to be valid. 193 install them if they are deemed to be valid.
194 </para> 194 </para>
195 195
@@ -202,18 +202,18 @@
202 <title>Overall Architecture</title> 202 <title>Overall Architecture</title>
203 203
204 <para> 204 <para>
205 When determining what parts of the system need to be built, BitBake 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. 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. 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. 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> 209 In this case, <filename>do_install</filename> and <filename>do_package</filename>
210 output are still valid. 210 output are still valid.
211 However, with a per-recipe approach, the build would not include the 211 However, with a per-recipe approach, the build would not include the
212 <filename>.deb</filename> files. 212 <filename>.deb</filename> files.
213 Consequently, you would have to invalidate the whole build and rerun it. 213 Consequently, you would have to invalidate the whole build and rerun it.
214 Rerunning everything is not the best situation. 214 Rerunning everything is not the best situation.
215 Also in this case, the core must be "taught" much about specific tasks. 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 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. 217 in layers or as external recipes without touching the packaged-staging core.
218 </para> 218 </para>
219 </section> 219 </section>
@@ -222,37 +222,37 @@
222 <title>Checksums (Signatures)</title> 222 <title>Checksums (Signatures)</title>
223 223
224 <para> 224 <para>
225 The shared state code uses a checksum, which is a unique signature of a task's 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. 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 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. 228 needs to detect all the inputs to a given task.
229 For shell tasks, this turns out to be fairly easy because 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 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 231 it is possible to create a checksum that gives you a good idea of when
232 the task's data changes. 232 the task's data changes.
233 </para> 233 </para>
234 234
235 <para> 235 <para>
236 To complicate the problem, there are things that should not be included in 236 To complicate the problem, there are things that should not be included in
237 the checksum. 237 the checksum.
238 First, there is the actual specific build path of a given task - 238 First, there is the actual specific build path of a given task -
239 the <filename>WORKDIR</filename>. 239 the <filename>WORKDIR</filename>.
240 It does not matter if the working directory changes because it should not 240 It does not matter if the working directory changes because it should not
241 affect the output for target packages. 241 affect the output for target packages.
242 Also, the build process has the objective of making native/cross packages relocatable. 242 Also, the build process has the objective of making native/cross packages relocatable.
243 The checksum therefore needs to exclude <filename>WORKDIR</filename>. 243 The checksum therefore needs to exclude <filename>WORKDIR</filename>.
244 The simplistic approach for excluding the working directory is to set 244 The simplistic approach for excluding the working directory is to set
245 <filename>WORKDIR</filename> to some fixed value and create the checksum 245 <filename>WORKDIR</filename> to some fixed value and create the checksum
246 for the "run" script. 246 for the "run" script.
247 </para> 247 </para>
248 248
249 <para> 249 <para>
250 Another problem results from the "run" scripts containing functions that 250 Another problem results from the "run" scripts containing functions that
251 might or might not get called. 251 might or might not get called.
252 The incremental build solution contains code that figures out dependencies 252 The incremental build solution contains code that figures out dependencies
253 between shell functions. 253 between shell functions.
254 This code is used to prune the "run" scripts down to the minimum set, 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 255 thereby alleviating this problem and making the "run" scripts much more
256 readable as a bonus. 256 readable as a bonus.
257 </para> 257 </para>
258 258
@@ -260,62 +260,62 @@
260 So far we have solutions for shell scripts. 260 So far we have solutions for shell scripts.
261 What about python tasks? 261 What about python tasks?
262 The same approach applies even though these tasks are more difficult. 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 263 The process needs to figure out what variables a python function accesses
264 and what functions it calls. 264 and what functions it calls.
265 Again, the incremental build solution contains code that first figures out 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 266 the variable and function dependencies, and then creates a checksum for the data
267 used as the input to the task. 267 used as the input to the task.
268 </para> 268 </para>
269 269
270 <para> 270 <para>
271 Like the <filename>WORKDIR</filename> case, situations exist where dependencies 271 Like the <filename>WORKDIR</filename> case, situations exist where dependencies
272 should be ignored. 272 should be ignored.
273 For these cases, you can instruct the build process to ignore a dependency 273 For these cases, you can instruct the build process to ignore a dependency
274 by using a line like the following: 274 by using a line like the following:
275 <literallayout class='monospaced'> 275 <literallayout class='monospaced'>
276 PACKAGE_ARCHS[vardepsexclude] = "MACHINE" 276 PACKAGE_ARCHS[vardepsexclude] = "MACHINE"
277 </literallayout> 277 </literallayout>
278 This example ensures that the <filename>PACKAGE_ARCHS</filename> variable does not 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. 279 depend on the value of <filename>MACHINE</filename>, even if it does reference it.
280 </para> 280 </para>
281 281
282 <para> 282 <para>
283 Equally, there are cases where we need to add dependencies BitBake is not able to find. 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: 284 You can accomplish this by using a line like the following:
285 <literallayout class='monospaced'> 285 <literallayout class='monospaced'>
286 PACKAGE_ARCHS[vardeps] = "MACHINE" 286 PACKAGE_ARCHS[vardeps] = "MACHINE"
287 </literallayout> 287 </literallayout>
288 This example explicitly adds the <filename>MACHINE</filename> variable as a 288 This example explicitly adds the <filename>MACHINE</filename> variable as a
289 dependency for <filename>PACKAGE_ARCHS</filename>. 289 dependency for <filename>PACKAGE_ARCHS</filename>.
290 </para> 290 </para>
291 291
292 <para> 292 <para>
293 Consider a case with inline python, for example, where BitBake is not 293 Consider a case with inline python, for example, where BitBake is not
294 able to figure out dependencies. 294 able to figure out dependencies.
295 When running in debug mode (i.e. using <filename>-DDD</filename>), BitBake 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 296 produces output when it discovers something for which it cannot figure out
297 dependencies. 297 dependencies.
298 The Yocto Project team has currently not managed to cover those 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. 299 in detail and is aware of the need to fix this situation.
300 </para> 300 </para>
301 301
302 <para> 302 <para>
303 Thus far, this section has limited discussion to the direct inputs into a task. 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 304 Information based on direct inputs is referred to as the "basehash" in the
305 code. 305 code.
306 However, there is still the question of a task's indirect inputs - the 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. 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 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. 309 of all the tasks on which the particular task depends.
310 Choosing which dependencies to add is a policy decision. 310 Choosing which dependencies to add is a policy decision.
311 However, the effect is to generate a master checksum that combines the basehash 311 However, the effect is to generate a master checksum that combines the basehash
312 and the hashes of the task's dependencies. 312 and the hashes of the task's dependencies.
313 </para> 313 </para>
314 314
315 <para> 315 <para>
316 At the code level, there are a variety of ways both the basehash and the 316 At the code level, there are a variety of ways both the basehash and the
317 dependent task hashes can be influenced. 317 dependent task hashes can be influenced.
318 Within the BitBake configuration file, we can give BitBake some extra information 318 Within the BitBake configuration file, we can give BitBake some extra information
319 to help it construct the basehash. 319 to help it construct the basehash.
320 The following statements effectively result in a list of global variable 320 The following statements effectively result in a list of global variable
321 dependency excludes - variables never included in any checksum: 321 dependency excludes - variables never included in any checksum:
@@ -325,42 +325,42 @@
325 BB_HASHBASE_WHITELIST += "FILE_DIRNAME HOME LOGNAME SHELL TERM USER" 325 BB_HASHBASE_WHITELIST += "FILE_DIRNAME HOME LOGNAME SHELL TERM USER"
326 BB_HASHBASE_WHITELIST += "FILESPATH USERNAME STAGING_DIR_HOST STAGING_DIR_TARGET" 326 BB_HASHBASE_WHITELIST += "FILESPATH USERNAME STAGING_DIR_HOST STAGING_DIR_TARGET"
327 </literallayout> 327 </literallayout>
328 The previous example actually excludes 328 The previous example actually excludes
329 <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link> 329 <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>
330 since it is actually constructed as a path within 330 since it is actually constructed as a path within
331 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>, which is on 331 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>, which is on
332 the whitelist. 332 the whitelist.
333 </para> 333 </para>
334 334
335 <para> 335 <para>
336 The rules for deciding which hashes of dependent tasks to include through 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 337 dependency chains are more complex and are generally accomplished with a
338 python function. 338 python function.
339 The code in <filename>meta/lib/oe/sstatesig.py</filename> shows two examples 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 340 of this and also illustrates how you can insert your own policy into the system
341 if so desired. 341 if so desired.
342 This file defines the two basic signature generators <filename>OE-Core</filename> 342 This file defines the two basic signature generators <filename>OE-Core</filename>
343 uses: "OEBasic" and "OEBasicHash". 343 uses: "OEBasic" and "OEBasicHash".
344 By default, there is a dummy "noop" signature handler enabled in BitBake. 344 By default, there is a dummy "noop" signature handler enabled in BitBake.
345 This means that behavior is unchanged from previous versions. 345 This means that behavior is unchanged from previous versions.
346 <filename>OE-Core</filename> uses the "OEBasic" signature handler by default 346 <filename>OE-Core</filename> uses the "OEBasic" signature handler by default
347 through this setting in the <filename>bitbake.conf</filename> file: 347 through this setting in the <filename>bitbake.conf</filename> file:
348 <literallayout class='monospaced'> 348 <literallayout class='monospaced'>
349 BB_SIGNATURE_HANDLER ?= "OEBasic" 349 BB_SIGNATURE_HANDLER ?= "OEBasic"
350 </literallayout> 350 </literallayout>
351 The "OEBasicHash" <filename>BB_SIGNATURE_HANDLER</filename> is the same as the 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. 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 353 This results in any metadata change that changes the task hash, automatically
354 causing the task to be run again. 354 causing the task to be run again.
355 This removes the need to bump <link linkend='var-PR'><filename>PR</filename></link> 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. 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> 357 Currently, this behavior is not the default behavior for <filename>OE-Core</filename>
358 but is the default in <filename>poky</filename>. 358 but is the default in <filename>poky</filename>.
359 </para> 359 </para>
360 360
361 <para> 361 <para>
362 It is also worth noting that the end result of these signature generators is to 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. 363 make some dependency and hash information available to the build.
364 This information includes: 364 This information includes:
365 <literallayout class='monospaced'> 365 <literallayout class='monospaced'>
366 BB_BASEHASH_task-&lt;taskname&gt; - the base hashes for each task in the recipe 366 BB_BASEHASH_task-&lt;taskname&gt; - the base hashes for each task in the recipe
@@ -375,15 +375,15 @@
375 <title>Shared State</title> 375 <title>Shared State</title>
376 376
377 <para> 377 <para>
378 Checksums and dependencies, as discussed in the previous section, solve half the 378 Checksums and dependencies, as discussed in the previous section, solve half the
379 problem. 379 problem.
380 The other part of the problem is being able to use checksum information during the build 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. 381 and being able to reuse or rebuild specific components.
382 </para> 382 </para>
383 383
384 <para> 384 <para>
385 The shared state class (<filename>sstate.bbclass</filename>) 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. 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. 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 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. 389 somewhere - the build process doesn't need to worry about its source.
@@ -392,17 +392,17 @@
392 <para> 392 <para>
393 There are two types of output, one is just about creating a directory 393 There are two types of output, one is just about creating a directory
394 in <filename>WORKDIR</filename>. 394 in <filename>WORKDIR</filename>.
395 A good example is the output of either <filename>do_install</filename> or 395 A good example is the output of either <filename>do_install</filename> or
396 <filename>do_package</filename>. 396 <filename>do_package</filename>.
397 The other type of output occurs when a set of data is merged into a shared directory 397 The other type of output occurs when a set of data is merged into a shared directory
398 tree such as the sysroot. 398 tree such as the sysroot.
399 </para> 399 </para>
400 400
401 <para> 401 <para>
402 The Yocto Project team has tried to keep the details of the implementation hidden in 402 The Yocto Project team has tried to keep the details of the implementation hidden in
403 <filename>sstate.bbclass</filename>. 403 <filename>sstate.bbclass</filename>.
404 From a user's perspective, adding shared state wrapping to a task 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 405 is as simple as this <filename>do_deploy</filename> example taken from
406 <filename>do_deploy.bbclass</filename>: 406 <filename>do_deploy.bbclass</filename>:
407 <literallayout class='monospaced'> 407 <literallayout class='monospaced'>
408 DEPLOYDIR = "${WORKDIR}/deploy-${PN}" 408 DEPLOYDIR = "${WORKDIR}/deploy-${PN}"
@@ -418,13 +418,13 @@
418 </literallayout> 418 </literallayout>
419 In the example, we add some extra flags to the task, a name field ("deploy"), an 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 420 input directory where the task sends data, and the output
421 directory where the data from the task should eventually be copied. 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 422 We also add a <filename>_setscene</filename> variant of the task and add the task
423 name to the <filename>SSTATETASKS</filename> list. 423 name to the <filename>SSTATETASKS</filename> list.
424 </para> 424 </para>
425 425
426 <para> 426 <para>
427 If you have a directory whose contents you need to preserve, you can do this with 427 If you have a directory whose contents you need to preserve, you can do this with
428 a line like the following: 428 a line like the following:
429 <literallayout class='monospaced'> 429 <literallayout class='monospaced'>
430 do_package[sstate-plaindirs] = "${PKGD} ${PKGDEST}" 430 do_package[sstate-plaindirs] = "${PKGD} ${PKGDEST}"
@@ -441,21 +441,21 @@
441 </para> 441 </para>
442 442
443 <para> 443 <para>
444 Behind the scenes, the shared state code works by looking in 444 Behind the scenes, the shared state code works by looking in
445 <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link> and 445 <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link> and
446 <link linkend='var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></link> 446 <link linkend='var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></link>
447 for shared state files. 447 for shared state files.
448 Here is an example: 448 Here is an example:
449 <literallayout class='monospaced'> 449 <literallayout class='monospaced'>
450 SSTATE_MIRRORS ?= "\ 450 SSTATE_MIRRORS ?= "\
451 file://.* http://someserver.tld/share/sstate/PATH \n \ 451 file://.* http://someserver.tld/share/sstate/PATH \n \
452 file://.* file:///some/local/dir/sstate/PATH" 452 file://.* file:///some/local/dir/sstate/PATH"
453 </literallayout> 453 </literallayout>
454 <note> 454 <note>
455 The shared state directory (<filename>SSTATE_DIR</filename>) is 455 The shared state directory (<filename>SSTATE_DIR</filename>) is
456 organized into two-character subdirectories, where the subdirectory 456 organized into two-character subdirectories, where the subdirectory
457 names are based on the first two characters of the hash. 457 names are based on the first two characters of the hash.
458 If the shared state directory structure for a mirror has the 458 If the shared state directory structure for a mirror has the
459 same structure as <filename>SSTATE_DIR</filename>, you must 459 same structure as <filename>SSTATE_DIR</filename>, you must
460 specify "PATH" as part of the URI to enable the build system 460 specify "PATH" as part of the URI to enable the build system
461 to map to the appropriate subdirectory. 461 to map to the appropriate subdirectory.
@@ -465,8 +465,8 @@
465 <para> 465 <para>
466 The shared state package validity can be detected just by looking at the 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 467 filename since the filename contains the task checksum (or signature) as
468 described earlier in this section. 468 described earlier in this section.
469 If a valid shared state package is found, the build process downloads it 469 If a valid shared state package is found, the build process downloads it
470 and uses it to accelerate the task. 470 and uses it to accelerate the task.
471 </para> 471 </para>
472 472
@@ -474,19 +474,19 @@
474 The build processes uses the <filename>*_setscene</filename> tasks 474 The build processes uses the <filename>*_setscene</filename> tasks
475 for the task acceleration phase. 475 for the task acceleration phase.
476 BitBake goes through this phase before the main execution code and tries 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. 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 478 If a shared state package for a task is available, the shared state
479 package is used. 479 package is used.
480 This means the task and any tasks on which it is dependent are not 480 This means the task and any tasks on which it is dependent are not
481 executed. 481 executed.
482 </para> 482 </para>
483 483
484 <para> 484 <para>
485 As a real world example, the aim is when building an IPK-based image, 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 486 only the <filename>do_package_write_ipk</filename> tasks would have their
487 shared state packages fetched and extracted. 487 shared state packages fetched and extracted.
488 Since the sysroot is not used, it would never get 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 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. 490 recipe-based approach, which would have to install the output from every task.
491 </para> 491 </para>
492 </section> 492 </section>
@@ -495,9 +495,9 @@
495 <title>Tips and Tricks</title> 495 <title>Tips and Tricks</title>
496 496
497 <para> 497 <para>
498 The code in the build system that supports incremental builds is not 498 The code in the build system that supports incremental builds is not
499 simple code. 499 simple code.
500 This section presents some tips and tricks that help you work around 500 This section presents some tips and tricks that help you work around
501 issues related to shared state code. 501 issues related to shared state code.
502 </para> 502 </para>
503 503
@@ -505,25 +505,25 @@
505 <title>Debugging</title> 505 <title>Debugging</title>
506 506
507 <para> 507 <para>
508 When things go wrong, debugging needs to be straightforward. 508 When things go wrong, debugging needs to be straightforward.
509 Because of this, the Yocto Project team included strong debugging 509 Because of this, the Yocto Project team included strong debugging
510 tools: 510 tools:
511 <itemizedlist> 511 <itemizedlist>
512 <listitem><para>Whenever a shared state package is written out, so is a 512 <listitem><para>Whenever a shared state package is written out, so is a
513 corresponding <filename>.siginfo</filename> file. 513 corresponding <filename>.siginfo</filename> file.
514 This practice results in a pickled python database of all 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 515 the metadata that went into creating the hash for a given shared state
516 package.</para></listitem> 516 package.</para></listitem>
517 <listitem><para>If BitBake is run with the <filename>--dump-signatures</filename> 517 <listitem><para>If BitBake is run with the <filename>--dump-signatures</filename>
518 (or <filename>-S</filename>) option, BitBake dumps out 518 (or <filename>-S</filename>) option, BitBake dumps out
519 <filename>.siginfo</filename> files in 519 <filename>.siginfo</filename> files in
520 the stamp directory for every task it would have executed instead of 520 the stamp directory for every task it would have executed instead of
521 building the specified target package.</para></listitem> 521 building the specified target package.</para></listitem>
522 <listitem><para>There is a <filename>bitbake-diffsigs</filename> command that 522 <listitem><para>There is a <filename>bitbake-diffsigs</filename> command that
523 can process these <filename>.siginfo</filename> files. 523 can process these <filename>.siginfo</filename> files.
524 If one file is specified, it will dump out the dependency 524 If one file is specified, it will dump out the dependency
525 information in the file. 525 information in the file.
526 If two files are specified, it will compare the two files and dump out 526 If two files are specified, it will compare the two files and dump out
527 the differences between the two. 527 the differences between the two.
528 This allows the question of "What changed between X and Y?" to be 528 This allows the question of "What changed between X and Y?" to be
529 answered easily.</para></listitem> 529 answered easily.</para></listitem>
@@ -538,41 +538,41 @@
538 The shared state code uses checksums and shared state 538 The shared state code uses checksums and shared state
539 cache to avoid unnecessarily rebuilding tasks. 539 cache to avoid unnecessarily rebuilding tasks.
540 As with all schemes, this one has some drawbacks. 540 As with all schemes, this one has some drawbacks.
541 It is possible that you could make implicit changes that are not factored 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. 542 into the checksum calculation, but do affect a task's output.
543 A good example is perhaps when a tool changes its 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. 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", 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. 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, 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. 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 549 In this case, the build process would use the cached items rather than running the
550 task again. 550 task again.
551 Obviously, these types of implicit changes can cause problems. 551 Obviously, these types of implicit changes can cause problems.
552 </para> 552 </para>
553 553
554 <para> 554 <para>
555 To avoid these problems during the build, you need to understand the effects of any 555 To avoid these problems during the build, you need to understand the effects of any
556 change you make. 556 change you make.
557 Note that any changes you make directly to a function automatically are factored into 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. 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 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. 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 561 Once you are aware of such a change, you can take steps to invalidate the cache
562 and force the task to run. 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. 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 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. 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 566 The change is purely cosmetic, but it causes the checksum to be recalculated and
567 forces the task to be run again. 567 forces the task to be run again.
568 </para> 568 </para>
569 569
570 <note> 570 <note>
571 For an example of a commit that makes a cosmetic change to invalidate 571 For an example of a commit that makes a cosmetic change to invalidate
572 a shared state, see this 572 a shared state, see this
573 <ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/commit/meta/classes/package.bbclass?id=737f8bbb4f27b4837047cb9b4fbfe01dfde36d54'>commit</ulink>. 573 <ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/commit/meta/classes/package.bbclass?id=737f8bbb4f27b4837047cb9b4fbfe01dfde36d54'>commit</ulink>.
574 </note> 574 </note>
575 </section> 575 </section>
576 </section> 576 </section>
577</section> 577</section>
578 578
@@ -580,24 +580,24 @@
580 <title>x32</title> 580 <title>x32</title>
581 581
582 <para> 582 <para>
583 x32 is a new processor-specific Application Binary Interface (psABI) for x86_64. 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. 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. 585 The interface determines what registers are used and what the sizes are for various C data types.
586 </para> 586 </para>
587 587
588 <para> 588 <para>
589 Some processing environments prefer using 32-bit applications even when running 589 Some processing environments prefer using 32-bit applications even when running
590 on Intel 64-bit platforms. 590 on Intel 64-bit platforms.
591 Consider the i386 psABI, which is a very old 32-bit ABI for 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, 592 The i386 psABI does not provide efficient use and access of the Intel 64-bit processor resources,
593 leaving the system underutilized. 593 leaving the system underutilized.
594 Now consider the x86_64 psABI. 594 Now consider the x86_64 psABI.
595 This ABI is newer and uses 64-bits for data sizes and program pointers. 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, 596 The extra bits increase the footprint size of the programs, libraries,
597 and also increases the memory and file system size requirements. 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 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. 599 more efficiently while keeping the memory footprint of the applications low.
600 Extra bits are used for registers but not for addressing mechanisms. 600 Extra bits are used for registers but not for addressing mechanisms.
601 </para> 601 </para>
602 602
603 <section id='support'> 603 <section id='support'>
@@ -608,14 +608,14 @@
608 release supports current development specifications of x32 psABI. 608 release supports current development specifications of x32 psABI.
609 As of this release of the Yocto Project, x32 psABI support exists as follows: 609 As of this release of the Yocto Project, x32 psABI support exists as follows:
610 <itemizedlist> 610 <itemizedlist>
611 <listitem><para>You can create packages and images in x32 psABI format on x86_64 architecture targets. 611 <listitem><para>You can create packages and images in x32 psABI format on x86_64 architecture targets.
612 </para></listitem> 612 </para></listitem>
613 <listitem><para>You can use the x32 psABI support through the <filename>meta-x32</filename> 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> 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 615 <listitem><para>The toolchain from the <filename>experimental/meta-x32</filename> layer
616 is used for building x32 psABI program binaries.</para></listitem> 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> 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 618 <listitem><para>You can create and boot <filename>core-image-minimal</filename> and
619 <filename>core-image-sato</filename> images.</para></listitem> 619 <filename>core-image-sato</filename> images.</para></listitem>
620 </itemizedlist> 620 </itemizedlist>
621 </para> 621 </para>
@@ -625,18 +625,18 @@
625 <title>Future Development and Limitations</title> 625 <title>Future Development and Limitations</title>
626 626
627 <para> 627 <para>
628 As of this Yocto Project release, the x32 psABI kernel and library interfaces 628 As of this Yocto Project release, the x32 psABI kernel and library interfaces
629 specifications are not finalized. 629 specifications are not finalized.
630 </para> 630 </para>
631 631
632 <para> 632 <para>
633 Future Plans for the x32 psABI in the Yocto Project include the following: 633 Future Plans for the x32 psABI in the Yocto Project include the following:
634 <itemizedlist> 634 <itemizedlist>
635 <listitem><para>Enhance and fix the few remaining recipes so they 635 <listitem><para>Enhance and fix the few remaining recipes so they
636 work with and support x32 toolchains.</para></listitem> 636 work with and support x32 toolchains.</para></listitem>
637 <listitem><para>Enhance RPM Package Manager (RPM) support for x32 binaries.</para></listitem> 637 <listitem><para>Enhance RPM Package Manager (RPM) support for x32 binaries.</para></listitem>
638 <listitem><para>Support larger images.</para></listitem> 638 <listitem><para>Support larger images.</para></listitem>
639 <listitem><para>Integrate x32 recipes, toolchain, and kernel changes from 639 <listitem><para>Integrate x32 recipes, toolchain, and kernel changes from
640 <filename>experimental/meta-x32</filename> into OE-core.</para></listitem> 640 <filename>experimental/meta-x32</filename> into OE-core.</para></listitem>
641 </itemizedlist> 641 </itemizedlist>
642 </para> 642 </para>
@@ -650,7 +650,7 @@
650 Yocto Project, you can follow these steps to use the x32 spABI: 650 Yocto Project, you can follow these steps to use the x32 spABI:
651 <itemizedlist> 651 <itemizedlist>
652 <listitem><para>Add the <filename>experimental/meta-x32</filename> layer to your local 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>. 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 654 You can find the <filename>experimental/meta-x32</filename> source repository at
655 <ulink url='&YOCTO_GIT_URL;'></ulink>.</para></listitem> 655 <ulink url='&YOCTO_GIT_URL;'></ulink>.</para></listitem>
656 <listitem><para>Edit your <filename>conf/bblayers.conf</filename> file so that it includes 656 <listitem><para>Edit your <filename>conf/bblayers.conf</filename> file so that it includes
@@ -677,8 +677,8 @@
677 or 'INVALID'), True) or 'lib'}" 677 or 'INVALID'), True) or 'lib'}"
678 #MACHINE = "atom-pc" 678 #MACHINE = "atom-pc"
679 #DEFAULTTUNE = "core2-64-x32" 679 #DEFAULTTUNE = "core2-64-x32"
680 </literallayout></para></listitem> 680 </literallayout></para></listitem>
681 <listitem><para>As usual, use BitBake to build an image that supports the x32 psABI. 681 <listitem><para>As usual, use BitBake to build an image that supports the x32 psABI.
682 Here is an example: 682 Here is an example:
683 <literallayout class='monospaced'> 683 <literallayout class='monospaced'>
684 $ bitake core-image-sato 684 $ bitake core-image-sato
@@ -696,15 +696,15 @@
696 <title>Licenses</title> 696 <title>Licenses</title>
697 697
698 <para> 698 <para>
699 This section describes the mechanism by which the OpenEmbedded build system 699 This section describes the mechanism by which the OpenEmbedded build system
700 tracks changes to licensing text. 700 tracks changes to licensing text.
701 The section also describes how to enable commercially licensed recipes, 701 The section also describes how to enable commercially licensed recipes,
702 which by default are disabled. 702 which by default are disabled.
703 </para> 703 </para>
704 704
705 <para> 705 <para>
706 For information that can help you maintain compliance with various open 706 For information that can help you maintain compliance with various open
707 source licensing during the lifecycle of the product, see the 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 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. 709 in the Yocto Project Development Manual.
710 </para> 710 </para>
@@ -713,8 +713,8 @@
713 <title>Tracking License Changes</title> 713 <title>Tracking License Changes</title>
714 714
715 <para> 715 <para>
716 The license of an upstream project might change in the future. 716 The license of an upstream project might change in the future.
717 In order to prevent these changes going unnoticed, the 717 In order to prevent these changes going unnoticed, the
718 <filename><link linkend='var-LIC_FILES_CHKSUM'>LIC_FILES_CHKSUM</link></filename> 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 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. 720 configure step, and if the checksums do not match, the build will fail.
@@ -736,15 +736,15 @@
736 </para> 736 </para>
737 737
738 <para> 738 <para>
739 The build system uses the 739 The build system uses the
740 <filename><link linkend='var-S'>S</link></filename> variable as the 740 <filename><link linkend='var-S'>S</link></filename> variable as the
741 default directory used when searching files listed in 741 default directory used when searching files listed in
742 <filename>LIC_FILES_CHKSUM</filename>. 742 <filename>LIC_FILES_CHKSUM</filename>.
743 The previous example employs the default directory. 743 The previous example employs the default directory.
744 </para> 744 </para>
745 745
746 <para> 746 <para>
747 You can also use relative paths as shown in the following example: 747 You can also use relative paths as shown in the following example:
748 <literallayout class='monospaced'> 748 <literallayout class='monospaced'>
749 LIC_FILES_CHKSUM = "file://src/ls.c;startline=5;endline=16;\ 749 LIC_FILES_CHKSUM = "file://src/ls.c;startline=5;endline=16;\
750 md5=bb14ed3c4cda583abc85401304b5cd4e" 750 md5=bb14ed3c4cda583abc85401304b5cd4e"
@@ -753,14 +753,14 @@
753 </para> 753 </para>
754 754
755 <para> 755 <para>
756 In this example, the first line locates a file in 756 In this example, the first line locates a file in
757 <filename>${S}/src/ls.c</filename>. 757 <filename>${S}/src/ls.c</filename>.
758 The second line refers to a file in 758 The second line refers to a file in
759 <filename><link linkend='var-WORKDIR'>WORKDIR</link></filename>, which is the parent 759 <filename><link linkend='var-WORKDIR'>WORKDIR</link></filename>, which is the parent
760 of <filename><link linkend='var-S'>S</link></filename>. 760 of <filename><link linkend='var-S'>S</link></filename>.
761 </para> 761 </para>
762 <para> 762 <para>
763 Note that this variable is mandatory for all recipes, unless the 763 Note that this variable is mandatory for all recipes, unless the
764 <filename>LICENSE</filename> variable is set to "CLOSED". 764 <filename>LICENSE</filename> variable is set to "CLOSED".
765 </para> 765 </para>
766 </section> 766 </section>
@@ -768,48 +768,48 @@
768 <section id="usingpoky-LIC_FILES_CHKSUM-explanation-of-syntax"> 768 <section id="usingpoky-LIC_FILES_CHKSUM-explanation-of-syntax">
769 <title>Explanation of Syntax</title> 769 <title>Explanation of Syntax</title>
770 <para> 770 <para>
771 As mentioned in the previous section, the 771 As mentioned in the previous section, the
772 <filename>LIC_FILES_CHKSUM</filename> variable lists all the 772 <filename>LIC_FILES_CHKSUM</filename> variable lists all the
773 important files that contain the license text for the source code. 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 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" 775 file (specified by beginning and ending line numbers with the "beginline" and "endline"
776 parameters, respectively). 776 parameters, respectively).
777 The latter is useful for source files with a license notice header, 777 The latter is useful for source files with a license notice header,
778 README documents, and so forth. 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 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. 780 first line of the file.
781 Similarly, if you do not use the "endline" parameter, it is assumed that the license text 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. 782 ends with the last line of the file.
783 </para> 783 </para>
784 784
785 <para> 785 <para>
786 The "md5" parameter stores the md5 checksum of the license text. 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 787 If the license text changes in any way as compared to this parameter
788 then a mismatch occurs. 788 then a mismatch occurs.
789 This mismatch triggers a build failure and notifies the developer. 789 This mismatch triggers a build failure and notifies the developer.
790 Notification allows the developer to review and address the license text changes. 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 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. 792 checksum is placed in the build log and can be easily copied to the recipe.
793 </para> 793 </para>
794 794
795 <para> 795 <para>
796 There is no limit to how many files you can specify using the 796 There is no limit to how many files you can specify using the
797 <filename>LIC_FILES_CHKSUM</filename> variable. 797 <filename>LIC_FILES_CHKSUM</filename> variable.
798 Generally, however, every project requires a few specifications for license tracking. 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 799 Many projects have a "COPYING" file that stores the license information for all the source
800 code files. 800 code files.
801 This practice allows you to just track the "COPYING" file as long as it is kept up to date. 801 This practice allows you to just track the "COPYING" file as long as it is kept up to date.
802 </para> 802 </para>
803 803
804 <tip> 804 <tip>
805 If you specify an empty or invalid "md5" parameter, BitBake returns an md5 mis-match 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. 806 error and displays the correct "md5" parameter value during the build.
807 The correct parameter is also captured in the build log. 807 The correct parameter is also captured in the build log.
808 </tip> 808 </tip>
809 809
810 <tip> 810 <tip>
811 If the whole file contains only license text, you do not need to use the "beginline" and 811 If the whole file contains only license text, you do not need to use the "beginline" and
812 "endline" parameters. 812 "endline" parameters.
813 </tip> 813 </tip>
814 </section> 814 </section>
815 </section> 815 </section>
@@ -820,10 +820,10 @@
820 <para> 820 <para>
821 By default, the OpenEmbedded build system disables 821 By default, the OpenEmbedded build system disables
822 components that have commercial or other special licensing 822 components that have commercial or other special licensing
823 requirements. 823 requirements.
824 Such requirements are defined on a 824 Such requirements are defined on a
825 recipe-by-recipe basis through the <filename>LICENSE_FLAGS</filename> variable 825 recipe-by-recipe basis through the <filename>LICENSE_FLAGS</filename> variable
826 definition in the affected recipe. 826 definition in the affected recipe.
827 For instance, the 827 For instance, the
828 <filename>$HOME/poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly</filename> 828 <filename>$HOME/poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly</filename>
829 recipe contains the following statement: 829 recipe contains the following statement:
@@ -839,7 +839,7 @@
839 definition to be enabled and included in an image, it 839 definition to be enabled and included in an image, it
840 needs to have a matching entry in the global 840 needs to have a matching entry in the global
841 <filename>LICENSE_FLAGS_WHITELIST</filename> variable, which is a variable 841 <filename>LICENSE_FLAGS_WHITELIST</filename> variable, which is a variable
842 typically defined in your <filename>local.conf</filename> file. 842 typically defined in your <filename>local.conf</filename> file.
843 For example, to enable 843 For example, to enable
844 the <filename>$HOME/poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly</filename> 844 the <filename>$HOME/poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly</filename>
845 package, you could add either the string 845 package, you could add either the string
@@ -867,7 +867,7 @@
867 the initial underscore character or characters. 867 the initial underscore character or characters.
868 A partial string will match 868 A partial string will match
869 any license that contains the given string as the first 869 any license that contains the given string as the first
870 portion of its license. 870 portion of its license.
871 For example, the following 871 For example, the following
872 whitelist string will also match both of the packages 872 whitelist string will also match both of the packages
873 previously mentioned as well as any other packages that have 873 previously mentioned as well as any other packages that have
@@ -879,7 +879,7 @@
879 879
880 <section id="license-flag-matching"> 880 <section id="license-flag-matching">
881 <title>License Flag Matching</title> 881 <title>License Flag Matching</title>
882 882
883 <para> 883 <para>
884 The definition of 'matching' in reference to a 884 The definition of 'matching' in reference to a
885 recipe's <filename>LICENSE_FLAGS</filename> setting is simple. 885 recipe's <filename>LICENSE_FLAGS</filename> setting is simple.
@@ -891,7 +891,7 @@
891 Before a flag 891 Before a flag
892 defined by a particular recipe is tested against the 892 defined by a particular recipe is tested against the
893 contents of the <filename>LICENSE_FLAGS_WHITELIST</filename> variable, the 893 contents of the <filename>LICENSE_FLAGS_WHITELIST</filename> variable, the
894 string <filename>_${PN}</filename> (with 894 string <filename>_${PN}</filename> (with
895 <link linkend='var-PN'><filename>PN</filename></link> expanded of course) is 895 <link linkend='var-PN'><filename>PN</filename></link> expanded of course) is
896 appended to the flag, thus automatically making each 896 appended to the flag, thus automatically making each
897 <filename>LICENSE_FLAGS</filename> value recipe-specific. 897 <filename>LICENSE_FLAGS</filename> value recipe-specific.
@@ -907,7 +907,7 @@
907 You can broaden the match by 907 You can broaden the match by
908 putting any "_"-separated beginning subset of a 908 putting any "_"-separated beginning subset of a
909 <filename>LICENSE_FLAGS</filename> flag in the whitelist, which will also 909 <filename>LICENSE_FLAGS</filename> flag in the whitelist, which will also
910 match. 910 match.
911 For example, simply specifying "commercial" in 911 For example, simply specifying "commercial" in
912 the whitelist would match any expanded <filename>LICENSE_FLAGS</filename> 912 the whitelist would match any expanded <filename>LICENSE_FLAGS</filename>
913 definition starting with "commercial" such as 913 definition starting with "commercial" such as
@@ -923,7 +923,7 @@
923 <para> 923 <para>
924 Broadening the match allows for a range of specificity for the items 924 Broadening the match allows for a range of specificity for the items
925 in the whitelist, from more general to perfectly 925 in the whitelist, from more general to perfectly
926 specific. 926 specific.
927 So you have the choice of exhaustively 927 So you have the choice of exhaustively
928 enumerating each license flag in the whitelist to 928 enumerating each license flag in the whitelist to
929 allow only those specific recipes into the image, or 929 allow only those specific recipes into the image, or
@@ -935,7 +935,7 @@
935 <para> 935 <para>
936 This scheme works even if the flag already 936 This scheme works even if the flag already
937 has <filename>_${PN}</filename> appended - the extra <filename>_${PN}</filename> is 937 has <filename>_${PN}</filename> appended - the extra <filename>_${PN}</filename> is
938 redundant, but does not affect the outcome. 938 redundant, but does not affect the outcome.
939 For example, a license flag of "commercial_1.2_foo" would 939 For example, a license flag of "commercial_1.2_foo" would
940 turn into "commercial_1.2_foo_foo" and would match 940 turn into "commercial_1.2_foo_foo" and would match
941 both the general "commercial" and the specific 941 both the general "commercial" and the specific
@@ -944,8 +944,8 @@
944 "commercial_1.2_foo_foo" and "commercial_1.2", which 944 "commercial_1.2_foo_foo" and "commercial_1.2", which
945 does not make much sense regarding use in the whitelist. 945 does not make much sense regarding use in the whitelist.
946 </para> 946 </para>
947 947
948 <para> 948 <para>
949 For a versioned string, you could instead specify 949 For a versioned string, you could instead specify
950 "commercial_foo_1.2", which would turn into 950 "commercial_foo_1.2", which would turn into
951 "commercial_foo_1.2_foo". 951 "commercial_foo_1.2_foo".
@@ -993,8 +993,8 @@
993 </para> 993 </para>
994 994
995 <para> 995 <para>
996 Specifying audio and video plug-ins as part of the 996 Specifying audio and video plug-ins as part of the
997 <filename>COMMERCIAL_AUDIO_PLUGINS</filename> and 997 <filename>COMMERCIAL_AUDIO_PLUGINS</filename> and
998 <filename>COMMERCIAL_VIDEO_PLUGINS</filename> statements 998 <filename>COMMERCIAL_VIDEO_PLUGINS</filename> statements
999 or commercial qt components as part of 999 or commercial qt components as part of
1000 the <filename>COMMERCIAL_QT</filename> statement (along 1000 the <filename>COMMERCIAL_QT</filename> statement (along
@@ -1006,6 +1006,6 @@
1006 </section> 1006 </section>
1007</section> 1007</section>
1008</chapter> 1008</chapter>
1009<!-- 1009<!--
1010vim: expandtab tw=80 ts=4 1010vim: expandtab tw=80 ts=4
1011--> 1011-->
diff --git a/documentation/poky-ref-manual/usingpoky.xml b/documentation/poky-ref-manual/usingpoky.xml
index e5b5edb846..286b5fa783 100644
--- a/documentation/poky-ref-manual/usingpoky.xml
+++ b/documentation/poky-ref-manual/usingpoky.xml
@@ -17,8 +17,8 @@
17 <para> 17 <para>
18 This section provides a summary of the build process and provides information 18 This section provides a summary of the build process and provides information
19 for less obvious aspects of the build process. 19 for less obvious aspects of the build process.
20 For general information on how to build an image using the OpenEmbedded build 20 For general information on how to build an image using the OpenEmbedded build
21 system, see the 21 system, see the
22 "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>" 22 "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>"
23 section of the Yocto Project Quick Start. 23 section of the Yocto Project Quick Start.
24 </para> 24 </para>
@@ -35,12 +35,12 @@
35 </para> 35 </para>
36 36
37 <para> 37 <para>
38 The <filename>build_dir</filename> is optional and specifies the directory the 38 The <filename>build_dir</filename> is optional and specifies the directory the
39 OpenEmbedded build system uses for the build - 39 OpenEmbedded build system uses for the build -
40 the <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. 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> 41 If you do not specify a Build Directory it defaults to <filename>build</filename>
42 in your current working directory. 42 in your current working directory.
43 A common practice is to use a different Build Directory for different targets. 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> 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. 45 target, and <filename>~/build/arm</filename> for a <filename>qemuarm</filename> target.
46 See <link linkend="structure-core-script">&OE_INIT_FILE;</link> 46 See <link linkend="structure-core-script">&OE_INIT_FILE;</link>
@@ -55,13 +55,13 @@
55 </para> 55 </para>
56 56
57 <para> 57 <para>
58 The <filename>target</filename> is the name of the recipe you want to build. 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>, 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 60 <filename>/meta/recipes-sato/images</filename>, etc. all found in the
61 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. 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 62 Or, the target can be the name of a recipe for a specific piece of software such as
63 <application>busybox</application>. 63 <application>busybox</application>.
64 For more details about the images the OpenEmbedded build system supports, see the 64 For more details about the images the OpenEmbedded build system supports, see the
65 "<link linkend="ref-images">Images</link>" chapter. 65 "<link linkend="ref-images">Images</link>" chapter.
66 </para> 66 </para>
67 67
@@ -76,9 +76,9 @@
76 <title>Building an Image Using GPL Components</title> 76 <title>Building an Image Using GPL Components</title>
77 77
78 <para> 78 <para>
79 When building an image using GPL components, you need to maintain your original 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 80 settings and not switch back and forth applying different versions of the GNU
81 General Public License. 81 General Public License.
82 If you rebuild using different versions of GPL, dependency errors might occur 82 If you rebuild using different versions of GPL, dependency errors might occur
83 due to some components not being rebuilt. 83 due to some components not being rebuilt.
84 </para> 84 </para>
@@ -89,11 +89,11 @@
89 <title>Installing and Using the Result</title> 89 <title>Installing and Using the Result</title>
90 90
91 <para> 91 <para>
92 Once an image has been built, it often needs to be installed. 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 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 94 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> in
95 <filename class="directory">tmp/deploy/images</filename>. 95 <filename class="directory">tmp/deploy/images</filename>.
96 For information on how to run pre-built images such as <filename>qemux86</filename> 96 For information on how to run pre-built images such as <filename>qemux86</filename>
97 and <filename>qemuarm</filename>, see the 97 and <filename>qemuarm</filename>, see the
98 "<ulink url='&YOCTO_DOCS_QS_URL;#using-pre-built'>Using Pre-Built Binaries and QEMU</ulink>" 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. 99 section in the Yocto Project Quick Start.
@@ -106,25 +106,25 @@
106 <title>Debugging Build Failures</title> 106 <title>Debugging Build Failures</title>
107 107
108 <para> 108 <para>
109 The exact method for debugging build failures depends on the nature of the 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. 110 problem and on the system's area from which the bug originates.
111 Standard debugging practices such as comparison against the last 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 112 known working version with examination of the changes and the re-application of steps
113 to identify the one causing the problem are 113 to identify the one causing the problem are
114 valid for the Yocto Project just as they are for any other system. 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, 115 Even though it is impossible to detail every possible potential failure,
116 this section provides some general tips to aid in debugging. 116 this section provides some general tips to aid in debugging.
117 </para> 117 </para>
118 118
119 <section id='usingpoky-debugging-taskfailures'> 119 <section id='usingpoky-debugging-taskfailures'>
120 <title>Task Failures</title> 120 <title>Task Failures</title>
121 121
122 <para>The log file for shell tasks is available in 122 <para>The log file for shell tasks is available in
123 <filename>${WORKDIR}/temp/log.do_taskname.pid</filename>. 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 124 For example, the <filename>compile</filename> task for the QEMU minimal image for the x86
125 machine (<filename>qemux86</filename>) might be 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>. 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 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. 128 <filename>run.do_taskname.pid</filename> file located in the same directory.
129 </para> 129 </para>
130 130
@@ -137,17 +137,17 @@
137 <title>Running Specific Tasks</title> 137 <title>Running Specific Tasks</title>
138 138
139 <para> 139 <para>
140 Any given package consists of a set of tasks. 140 Any given package consists of a set of tasks.
141 The standard BitBake behavior in most cases is: <filename>fetch</filename>, 141 The standard BitBake behavior in most cases is: <filename>fetch</filename>,
142 <filename>unpack</filename>, 142 <filename>unpack</filename>,
143 <filename>patch</filename>, <filename>configure</filename>, 143 <filename>patch</filename>, <filename>configure</filename>,
144 <filename>compile</filename>, <filename>install</filename>, <filename>package</filename>, 144 <filename>compile</filename>, <filename>install</filename>, <filename>package</filename>,
145 <filename>package_write</filename>, and <filename>build</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 146 The default task is <filename>build</filename> and any tasks on which it depends
147 build first. 147 build first.
148 Some tasks exist, such as <filename>devshell</filename>, that are not part of the 148 Some tasks exist, such as <filename>devshell</filename>, that are not part of the
149 default build chain. 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 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: 151 <filename>-c</filename> option in BitBake as follows:
152 <literallayout class='monospaced'> 152 <literallayout class='monospaced'>
153 $ bitbake matchbox-desktop -c devshell 153 $ bitbake matchbox-desktop -c devshell
@@ -155,8 +155,8 @@
155 </para> 155 </para>
156 156
157 <para> 157 <para>
158 If you wish to rerun a task, use the <filename>-f</filename> force option. 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 159 For example, the following sequence forces recompilation after changing files in the
160 working directory. 160 working directory.
161 <literallayout class='monospaced'> 161 <literallayout class='monospaced'>
162 $ bitbake matchbox-desktop 162 $ bitbake matchbox-desktop
@@ -173,7 +173,7 @@
173 <para> 173 <para>
174 This sequence first builds <filename>matchbox-desktop</filename> and then recompiles it. 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. 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 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. 177 understands that the other tasks also need to be run again.
178 </para> 178 </para>
179 179
@@ -191,13 +191,13 @@
191 <title>Dependency Graphs</title> 191 <title>Dependency Graphs</title>
192 192
193 <para> 193 <para>
194 Sometimes it can be hard to see why BitBake wants to build some other packages before a given 194 Sometimes it can be hard to see why BitBake wants to build some other packages before a given
195 package you have specified. 195 package you have specified.
196 The <filename>bitbake -g targetname</filename> command creates the 196 The <filename>bitbake -g targetname</filename> command creates the
197 <filename>depends.dot</filename>, <filename>package-depends.dot</filename>, 197 <filename>depends.dot</filename>, <filename>package-depends.dot</filename>,
198 and <filename>task-depends.dot</filename> files in the current directory. 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. 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 200 You can use the <filename>bitbake -g -u depexp targetname</filename> command to
201 display the results in a more human-readable form. 201 display the results in a more human-readable form.
202 </para> 202 </para>
203 </section> 203 </section>
@@ -208,7 +208,7 @@
208 <para> 208 <para>
209 You can see debug output from BitBake by using the <filename>-D</filename> option. 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 210 The debug output gives more information about what BitBake
211 is doing and the reason behind it. 211 is doing and the reason behind it.
212 Each <filename>-D</filename> option you use increases the logging level. 212 Each <filename>-D</filename> option you use increases the logging level.
213 The most common usage is <filename>-DDD</filename>. 213 The most common usage is <filename>-DDD</filename>.
214 </para> 214 </para>
@@ -217,7 +217,7 @@
217 The output from <filename>bitbake -DDD -v targetname</filename> can reveal why 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 218 BitBake chose a certain version of a package or why BitBake
219 picked a certain provider. 219 picked a certain provider.
220 This command could also help you in a situation where you think BitBake did something 220 This command could also help you in a situation where you think BitBake did something
221 unexpected. 221 unexpected.
222 </para> 222 </para>
223 </section> 223 </section>
@@ -226,9 +226,9 @@
226 <title>Building with No Dependencies</title> 226 <title>Building with No Dependencies</title>
227 <para> 227 <para>
228 If you really want to build a specific <filename>.bb</filename> file, you can use 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>. 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 230 This command form does not check for dependencies so you should use it
231 only when you know its dependencies already exist. 231 only when you know its dependencies already exist.
232 You can also specify fragments of the filename. 232 You can also specify fragments of the filename.
233 In this case, BitBake checks for a unique match. 233 In this case, BitBake checks for a unique match.
234 </para> 234 </para>
@@ -243,31 +243,31 @@
243 to show the environment from parsing a single recipe file only. 243 to show the environment from parsing a single recipe file only.
244 </para> 244 </para>
245 </section> 245 </section>
246 246
247 <section id='recipe-logging-mechanisms'> 247 <section id='recipe-logging-mechanisms'>
248 <title>Recipe Logging Mechanisms</title> 248 <title>Recipe Logging Mechanisms</title>
249 <para> 249 <para>
250 Best practices exist while writing recipes that both log build progress and 250 Best practices exist while writing recipes that both log build progress and
251 act on build conditions such as warnings and errors. 251 act on build conditions such as warnings and errors.
252 Both Python and Bash language bindings exist for the logging mechanism: 252 Both Python and Bash language bindings exist for the logging mechanism:
253 <itemizedlist> 253 <itemizedlist>
254 <listitem><para><emphasis>Python:</emphasis> For Python functions, BitBake 254 <listitem><para><emphasis>Python:</emphasis> For Python functions, BitBake
255 supports several loglevels: <filename>bb.fatal</filename>, 255 supports several loglevels: <filename>bb.fatal</filename>,
256 <filename>bb.error</filename>, <filename>bb.warn</filename>, 256 <filename>bb.error</filename>, <filename>bb.warn</filename>,
257 <filename>bb.note</filename>, <filename>bb.plain</filename>, 257 <filename>bb.note</filename>, <filename>bb.plain</filename>,
258 and <filename>bb.debug</filename>.</para></listitem> 258 and <filename>bb.debug</filename>.</para></listitem>
259 <listitem><para><emphasis>Bash:</emphasis> For Bash functions, the same set 259 <listitem><para><emphasis>Bash:</emphasis> For Bash functions, the same set
260 of loglevels exist and are accessed with a similar syntax: 260 of loglevels exist and are accessed with a similar syntax:
261 <filename>bbfatal</filename>, <filename>bberror</filename>, 261 <filename>bbfatal</filename>, <filename>bberror</filename>,
262 <filename>bbwarn</filename>, <filename>bbnote</filename>, 262 <filename>bbwarn</filename>, <filename>bbnote</filename>,
263 <filename>bbplain</filename>, and <filename>bbdebug</filename>.</para></listitem> 263 <filename>bbplain</filename>, and <filename>bbdebug</filename>.</para></listitem>
264 </itemizedlist> 264 </itemizedlist>
265 </para> 265 </para>
266 266
267 <para> 267 <para>
268 For guidance on how logging is handled in both Python and Bash recipes, see the 268 For guidance on how logging is handled in both Python and Bash recipes, see the
269 <filename>logging.bbclass</filename> file in the 269 <filename>logging.bbclass</filename> file in the
270 <filename>meta/classes</filename> folder of the 270 <filename>meta/classes</filename> folder of the
271 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. 271 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
272 </para> 272 </para>
273 273
@@ -275,14 +275,14 @@
275 <title>Logging With Python</title> 275 <title>Logging With Python</title>
276 <para> 276 <para>
277 When creating recipes using Python and inserting code that handles build logs 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 278 keep in mind the goal is to have informative logs while keeping the console as
279 "silent" as possible. 279 "silent" as possible.
280 Also, if you want status messages in the log use the "debug" loglevel. 280 Also, if you want status messages in the log use the "debug" loglevel.
281 </para> 281 </para>
282 282
283 <para> 283 <para>
284 Following is an example written in Python. 284 Following is an example written in Python.
285 The code handles logging for a function that determines the number of tasks 285 The code handles logging for a function that determines the number of tasks
286 needed to be run: 286 needed to be run:
287 <literallayout class='monospaced'> 287 <literallayout class='monospaced'>
288 python do_listtasks() { 288 python do_listtasks() {
@@ -307,8 +307,8 @@
307 <title>Logging With Bash</title> 307 <title>Logging With Bash</title>
308 <para> 308 <para>
309 When creating recipes using Bash and inserting code that handles build 309 When creating recipes using Bash and inserting code that handles build
310 logs you have the same goals - informative with minimal console output. 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 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. 312 recipes written in Python described in the previous section.
313 </para> 313 </para>
314 314
@@ -337,22 +337,22 @@
337 </para> 337 </para>
338 </section> 338 </section>
339 </section> 339 </section>
340 340
341 <section id='usingpoky-debugging-others'> 341 <section id='usingpoky-debugging-others'>
342 <title>Other Tips</title> 342 <title>Other Tips</title>
343 343
344 <para> 344 <para>
345 Here are some other tips that you might find useful: 345 Here are some other tips that you might find useful:
346 <itemizedlist> 346 <itemizedlist>
347 <listitem><para>When adding new packages, it is worth watching for 347 <listitem><para>When adding new packages, it is worth watching for
348 undesirable items making their way into compiler command lines. 348 undesirable items making their way into compiler command lines.
349 For example, you do not want references to local system files like 349 For example, you do not want references to local system files like
350 <filename>/usr/lib/</filename> or <filename>/usr/include/</filename>. 350 <filename>/usr/lib/</filename> or <filename>/usr/include/</filename>.
351 </para></listitem> 351 </para></listitem>
352 <listitem><para>If you want to remove the psplash boot splashscreen, 352 <listitem><para>If you want to remove the psplash boot splashscreen,
353 add <filename>psplash=false</filename> to the kernel command line. 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. 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 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). 356 switching the virtual console (e.g. Fn+Left or Fn+Right on a Zaurus).
357 </para></listitem> 357 </para></listitem>
358 </itemizedlist> 358 </itemizedlist>
@@ -365,25 +365,25 @@
365 365
366 <para> 366 <para>
367 A build's quality can be influenced by many things. 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 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 369 package or you experiment with some new configuration options, subtle changes
370 can occur that you might not detect until later. 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. 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 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. 373 dependency on another library, which is auto-detected.
374 If that library has already been built when the software is building, 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 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 376 into your image along with the new software even if you did not want the
377 library. 377 library.
378 </para> 378 </para>
379 379
380 <para> 380 <para>
381 The <filename>buildhistory</filename> class exists to help you maintain 381 The <filename>buildhistory</filename> class exists to help you maintain
382 the quality of your build output. 382 the quality of your build output.
383 You can use the class to highlight unexpected and possibly unwanted 383 You can use the class to highlight unexpected and possibly unwanted
384 changes in the build output. 384 changes in the build output.
385 When you enable build history it records information about the contents of 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 386 each package and image and then commits that information to a local Git
387 repository where you can examine the information. 387 repository where you can examine the information.
388 </para> 388 </para>
389 389
@@ -396,7 +396,7 @@
396 </para></listitem> 396 </para></listitem>
397 <listitem><para>How to limit the information used for build history 397 <listitem><para>How to limit the information used for build history
398 </para></listitem> 398 </para></listitem>
399 <listitem><para>How to examine the build history from both a 399 <listitem><para>How to examine the build history from both a
400 command-line and web interface</para></listitem> 400 command-line and web interface</para></listitem>
401 </itemizedlist> 401 </itemizedlist>
402 </para> 402 </para>
@@ -406,41 +406,41 @@
406 406
407 <para> 407 <para>
408 Build history is disabled by default. 408 Build history is disabled by default.
409 To enable it, add the following statements to the end of your 409 To enable it, add the following statements to the end of your
410 <filename>conf/local.conf</filename> file found in the 410 <filename>conf/local.conf</filename> file found in the
411 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>: 411 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>:
412 <literallayout class='monospaced'> 412 <literallayout class='monospaced'>
413 INHERIT += "buildhistory" 413 INHERIT += "buildhistory"
414 BUILDHISTORY_COMMIT = "1" 414 BUILDHISTORY_COMMIT = "1"
415 </literallayout> 415 </literallayout>
416 Enabling build history as previously described 416 Enabling build history as previously described
417 causes the build process to collect build 417 causes the build process to collect build
418 output information and commit it to a local 418 output information and commit it to a local
419 <ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink> repository. 419 <ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink> repository.
420 <note> 420 <note>
421 Enabling build history increases your build times slightly, 421 Enabling build history increases your build times slightly,
422 particularly for images, and increases the amount of disk 422 particularly for images, and increases the amount of disk
423 space used during the build. 423 space used during the build.
424 </note> 424 </note>
425 </para> 425 </para>
426 426
427 <para> 427 <para>
428 You can disable build history by removing the previous statements 428 You can disable build history by removing the previous statements
429 from your <filename>conf/local.conf</filename> file. 429 from your <filename>conf/local.conf</filename> file.
430 However, you should realize that enabling and disabling 430 However, you should realize that enabling and disabling
431 build history in this manner can change the 431 build history in this manner can change the
432 <filename>do_package</filename> task checksums, which if you 432 <filename>do_package</filename> task checksums, which if you
433 are using the OEBasicHash signature generator (the default 433 are using the OEBasicHash signature generator (the default
434 for many current distro configurations including 434 for many current distro configurations including
435 <filename>DISTRO = "poky"</filename> and 435 <filename>DISTRO = "poky"</filename> and
436 <filename>DISTRO = ""</filename>) will result in the packaging 436 <filename>DISTRO = ""</filename>) will result in the packaging
437 tasks being re-run during the subsequent build. 437 tasks being re-run during the subsequent build.
438 </para> 438 </para>
439 439
440 <para> 440 <para>
441 To disable the build history functionality without causing the 441 To disable the build history functionality without causing the
442 packaging tasks to be re-run, add just this statement to your 442 packaging tasks to be re-run, add just this statement to your
443 <filename>conf/local.conf</filename> file: 443 <filename>conf/local.conf</filename> file:
444 <literallayout class='monospaced'> 444 <literallayout class='monospaced'>
445 BUILDHISTORY_FEATURES = "" 445 BUILDHISTORY_FEATURES = ""
446 </literallayout> 446 </literallayout>
@@ -451,19 +451,19 @@
451 <title>Understanding What the Build History Contains</title> 451 <title>Understanding What the Build History Contains</title>
452 452
453 <para> 453 <para>
454 Build history information is kept in 454 Build history information is kept in
455 <link linkend='var-TMPDIR'><filename>$TMPDIR</filename></link><filename>/buildhistory</filename> 455 <link linkend='var-TMPDIR'><filename>$TMPDIR</filename></link><filename>/buildhistory</filename>
456 in the Build Directory. 456 in the Build Directory.
457 The following is an example abbreviated listing: 457 The following is an example abbreviated listing:
458 <imagedata fileref="figures/buildhistory.png" align="center" width="6in" depth="4in" /> 458 <imagedata fileref="figures/buildhistory.png" align="center" width="6in" depth="4in" />
459 </para> 459 </para>
460 460
461 <section id='build-history-package-information'> 461 <section id='build-history-package-information'>
462 <title>Build History Package Information</title> 462 <title>Build History Package Information</title>
463 463
464 <para> 464 <para>
465 The history for each package contains a text file that has 465 The history for each package contains a text file that has
466 name-value pairs with information about the package. 466 name-value pairs with information about the package.
467 For example, <filename>buildhistory/packages/core2-poky-linux/busybox/busybox/latest</filename> 467 For example, <filename>buildhistory/packages/core2-poky-linux/busybox/busybox/latest</filename>
468 contains the following: 468 contains the following:
469 <literallayout class='monospaced'> 469 <literallayout class='monospaced'>
@@ -474,21 +474,21 @@
474 PKGSIZE = 564701 474 PKGSIZE = 564701
475 FILES = /usr/bin/* /usr/sbin/* /usr/libexec/* /usr/lib/lib*.so.* \ 475 FILES = /usr/bin/* /usr/sbin/* /usr/libexec/* /usr/lib/lib*.so.* \
476 /etc /com /var /bin/* /sbin/* /lib/*.so.* /usr/share/busybox \ 476 /etc /com /var /bin/* /sbin/* /lib/*.so.* /usr/share/busybox \
477 /usr/lib/busybox/* /usr/share/pixmaps /usr/share/applications \ 477 /usr/lib/busybox/* /usr/share/pixmaps /usr/share/applications \
478 /usr/share/idl /usr/share/omf /usr/share/sounds /usr/lib/bonobo/servers 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 479 FILELIST = /etc/busybox.links /etc/init.d/hwclock.sh /bin/busybox /bin/sh
480 </literallayout> 480 </literallayout>
481 Most of these name-value pairs corresponds to variables used 481 Most of these name-value pairs corresponds to variables used
482 to produce the package. 482 to produce the package.
483 The exceptions are <filename>FILELIST</filename>, which is the 483 The exceptions are <filename>FILELIST</filename>, which is the
484 actual list of files in the package, and 484 actual list of files in the package, and
485 <filename>PKGSIZE</filename>, which is the total size of files 485 <filename>PKGSIZE</filename>, which is the total size of files
486 in the package in bytes. 486 in the package in bytes.
487 </para> 487 </para>
488 488
489 <para> 489 <para>
490 There is also a file corresponding to the recipe from which the 490 There is also a file corresponding to the recipe from which the
491 package came (e.g. 491 package came (e.g.
492 <filename>buildhistory/packages/core2-poky-linux/busybox/latest</filename>): 492 <filename>buildhistory/packages/core2-poky-linux/busybox/latest</filename>):
493 <literallayout class='monospaced'> 493 <literallayout class='monospaced'>
494 PV = 1.19.3 494 PV = 1.19.3
@@ -509,18 +509,18 @@
509 The files produced for each image are as follows: 509 The files produced for each image are as follows:
510 <itemizedlist> 510 <itemizedlist>
511 <listitem><para><emphasis>build-id:</emphasis> 511 <listitem><para><emphasis>build-id:</emphasis>
512 Human-readable information about the build configuration 512 Human-readable information about the build configuration
513 and metadata source revisions.</para></listitem> 513 and metadata source revisions.</para></listitem>
514 <listitem><para><emphasis>*.dot:</emphasis> 514 <listitem><para><emphasis>*.dot:</emphasis>
515 Dependency graphs for the image that are 515 Dependency graphs for the image that are
516 compatible with <filename>graphviz</filename>. 516 compatible with <filename>graphviz</filename>.
517 </para></listitem> 517 </para></listitem>
518 <listitem><para><emphasis>files-in-image.txt:</emphasis> 518 <listitem><para><emphasis>files-in-image.txt:</emphasis>
519 A list of files in the image with permissions, 519 A list of files in the image with permissions,
520 owner, group, size, and symlink information. 520 owner, group, size, and symlink information.
521 </para></listitem> 521 </para></listitem>
522 <listitem><para><emphasis>image-info.txt:</emphasis> 522 <listitem><para><emphasis>image-info.txt:</emphasis>
523 A text file containing name-value pairs with information 523 A text file containing name-value pairs with information
524 about the image. 524 about the image.
525 See the following listing example for more information. 525 See the following listing example for more information.
526 </para></listitem> 526 </para></listitem>
@@ -535,7 +535,7 @@
535 </itemizedlist> 535 </itemizedlist>
536 <note> 536 <note>
537 Installed package information is able to be gathered and 537 Installed package information is able to be gathered and
538 produced even if package management is disabled for the final 538 produced even if package management is disabled for the final
539 image. 539 image.
540 </note> 540 </note>
541 </para> 541 </para>
@@ -551,15 +551,15 @@
551 package-management ssh-server-dropbear package-management 551 package-management ssh-server-dropbear package-management
552 IMAGE_LINGUAS = en-us en-gb 552 IMAGE_LINGUAS = en-us en-gb
553 IMAGE_INSTALL = task-core-boot task-base-extended 553 IMAGE_INSTALL = task-core-boot task-base-extended
554 BAD_RECOMMENDATIONS = 554 BAD_RECOMMENDATIONS =
555 ROOTFS_POSTPROCESS_COMMAND = buildhistory_get_image_installed ; rootfs_update_timestamp ; 555 ROOTFS_POSTPROCESS_COMMAND = buildhistory_get_image_installed ; rootfs_update_timestamp ;
556 IMAGE_POSTPROCESS_COMMAND = buildhistory_get_imageinfo ; 556 IMAGE_POSTPROCESS_COMMAND = buildhistory_get_imageinfo ;
557 IMAGESIZE = 171816 557 IMAGESIZE = 171816
558 </literallayout> 558 </literallayout>
559 Other than <filename>IMAGESIZE</filename>, which is the 559 Other than <filename>IMAGESIZE</filename>, which is the
560 total size of the files in the image in Kbytes, the 560 total size of the files in the image in Kbytes, the
561 name-value pairs are variables that may have influenced the 561 name-value pairs are variables that may have influenced the
562 content of the image. 562 content of the image.
563 This information is often useful when you are trying to determine 563 This information is often useful when you are trying to determine
564 why a change in the package or file listings has occurred. 564 why a change in the package or file listings has occurred.
565 </para> 565 </para>
@@ -568,15 +568,15 @@
568 <section id='using-build-history-to-gather-image-information-only'> 568 <section id='using-build-history-to-gather-image-information-only'>
569 <title>Using Build History to Gather Image Information Only</title> 569 <title>Using Build History to Gather Image Information Only</title>
570 570
571 <para> 571 <para>
572 As you can see, build history produces image information, 572 As you can see, build history produces image information,
573 including dependency graphs, so you can see why something 573 including dependency graphs, so you can see why something
574 was pulled into the image. 574 was pulled into the image.
575 If you are just interested in this information and not 575 If you are just interested in this information and not
576 interested in collecting history or any package information, 576 interested in collecting history or any package information,
577 you can enable writing only image information without 577 you can enable writing only image information without
578 any history by adding the following 578 any history by adding the following
579 to your <filename>conf/local.conf</filename> file found in the 579 to your <filename>conf/local.conf</filename> file found in the
580 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>: 580 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>:
581 <literallayout class='monospaced'> 581 <literallayout class='monospaced'>
582 INHERIT += "buildhistory" 582 INHERIT += "buildhistory"
@@ -590,28 +590,28 @@
590 <title>Examining Build History Information</title> 590 <title>Examining Build History Information</title>
591 591
592 <para> 592 <para>
593 You can examine build history output from the command line or 593 You can examine build history output from the command line or
594 from a web interface. 594 from a web interface.
595 </para> 595 </para>
596 596
597 <para> 597 <para>
598 To see any changes that have occurred (assuming you have 598 To see any changes that have occurred (assuming you have
599 <filename>BUILDHISTORY_COMMIT = "1"</filename>), you can simply 599 <filename>BUILDHISTORY_COMMIT = "1"</filename>), you can simply
600 use any Git command that allows you to view the history of 600 use any Git command that allows you to view the history of
601 a repository. 601 a repository.
602 Here is one method: 602 Here is one method:
603 <literallayout class='monospaced'> 603 <literallayout class='monospaced'>
604 $ git log -p 604 $ git log -p
605 </literallayout> 605 </literallayout>
606 You need to realize, however, that this method does show 606 You need to realize, however, that this method does show
607 changes that are not significant (e.g. a package's size 607 changes that are not significant (e.g. a package's size
608 changing by a few bytes). 608 changing by a few bytes).
609 </para> 609 </para>
610 610
611 <para> 611 <para>
612 A command-line tool called <filename>buildhistory-diff</filename> 612 A command-line tool called <filename>buildhistory-diff</filename>
613 does exist though that queries the Git repository and prints just 613 does exist though that queries the Git repository and prints just
614 the differences that might be significant in human-readable form. 614 the differences that might be significant in human-readable form.
615 Here is an example: 615 Here is an example:
616 <literallayout class='monospaced'> 616 <literallayout class='monospaced'>
617 $ ~/poky/poky/scripts/buildhistory-diff . HEAD^ 617 $ ~/poky/poky/scripts/buildhistory-diff . HEAD^
@@ -632,7 +632,7 @@
632 </para> 632 </para>
633 633
634 <para> 634 <para>
635 To see changes to the build history using a web interface, follow 635 To see changes to the build history using a web interface, follow
636 the instruction in the <filename>README</filename> file here. 636 the instruction in the <filename>README</filename> file here.
637 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/buildhistory-web/'></ulink>. 637 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/buildhistory-web/'></ulink>.
638 </para> 638 </para>
@@ -646,6 +646,6 @@
646</section> 646</section>
647 647
648</chapter> 648</chapter>
649<!-- 649<!--
650vim: expandtab tw=80 ts=4 650vim: expandtab tw=80 ts=4
651--> 651-->