summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--documentation/poky-ref-manual/extendpoky.xml190
1 files changed, 95 insertions, 95 deletions
diff --git a/documentation/poky-ref-manual/extendpoky.xml b/documentation/poky-ref-manual/extendpoky.xml
index ad8918dcb8..03546e6d3f 100644
--- a/documentation/poky-ref-manual/extendpoky.xml
+++ b/documentation/poky-ref-manual/extendpoky.xml
@@ -5,13 +5,12 @@
5 5
6<title>Extending Poky</title> 6<title>Extending Poky</title>
7 <para> 7 <para>
8 This section provides information about how to extend the functionality 8 This chapter provides information about how to extend the functionality
9 already present in Poky. 9 already present in Poky.
10 The section also documents standard tasks such as adding new 10 The chapter also documents standard tasks such as adding new
11 software packages, extending or customizing images or porting Poky to 11 software packages, extending or customizing images or porting Poky to
12 new hardware (adding a new machine). 12 new hardware (adding a new machine).
13 Finally, the section contains advice about how 13 Finally, the chapter contains advice about how to make changes to Poky to achieve the best results.
14 to make changes to Poky to achieve the best results.
15 </para> 14 </para>
16 15
17 <section id='usingpoky-extend-addpkg'> 16 <section id='usingpoky-extend-addpkg'>
@@ -21,7 +20,7 @@
21 Writing a recipe means creating a <filename>.bb</filename> file that sets some 20 Writing a recipe means creating a <filename>.bb</filename> file that sets some
22 variables. 21 variables.
23 For information on variables that are useful for recipes and for information about recipe naming 22 For information on variables that are useful for recipes and for information about recipe naming
24 issues, see <link linkend='ref-varlocality-recipe-required'>Recipe Variables - Required</link> 23 issues, see the <link linkend='ref-varlocality-recipe-required'>Recipe Variables - Required</link>
25 appendix. 24 appendix.
26 </para> 25 </para>
27 <para> 26 <para>
@@ -29,7 +28,7 @@
29 whether someone else has written one already. 28 whether someone else has written one already.
30 OpenEmbedded is a good place to look as it has a wider scope and range of packages. 29 OpenEmbedded is a good place to look as it has a wider scope and range of packages.
31 Because Poky aims to be compatible with OpenEmbedded, most recipes should 30 Because Poky aims to be compatible with OpenEmbedded, most recipes should
32 just work in Poky. 31 simply work in Poky.
33 </para> 32 </para>
34 <para> 33 <para>
35 For new packages, the simplest way to add a recipe is to base it on a similar 34 For new packages, the simplest way to add a recipe is to base it on a similar
@@ -43,11 +42,11 @@
43 Building an application from a single file that is stored locally (e.g. under 42 Building an application from a single file that is stored locally (e.g. under
44 <filename>files/</filename>) requires a recipe that has the file listed in 43 <filename>files/</filename>) requires a recipe that has the file listed in
45 the <glossterm><link linkend='var-SRC_URI'>SRC_URI</link></glossterm> variable. 44 the <glossterm><link linkend='var-SRC_URI'>SRC_URI</link></glossterm> variable.
46 Additionally, you need to manually write the <function>do_compile</function> and 45 Additionally, you need to manually write the "do_compile" and
47 <function>do_install</function> tasks. 46 "do_install" tasks.
48 The <glossterm><link linkend='var-S'>S</link></glossterm> variable defines the 47 The <glossterm><link linkend='var-S'>S</link></glossterm> variable defines the
49 directory containing the source code, which is set to <glossterm><link linkend='var-WORKDIR'> 48 directory containing the source code, which is set to <glossterm><link linkend='var-WORKDIR'>
50 WORKDIR</link></glossterm> in this case - the directory BitBake uses for the build. 49 WORKDIR</link></glossterm> in this case - the directory Bitbake uses for the build.
51 </para> 50 </para>
52 <programlisting> 51 <programlisting>
53DESCRIPTION = "Simple helloworld application" 52DESCRIPTION = "Simple helloworld application"
@@ -82,13 +81,13 @@ do_install() {
82 Applications that use autotools such as <filename>autoconf</filename> and 81 Applications that use autotools such as <filename>autoconf</filename> and
83 <filename>automake</filename> require a recipe that has a source archive listed in 82 <filename>automake</filename> require a recipe that has a source archive listed in
84 <glossterm><link linkend='var-SRC_URI'>SRC_URI</link></glossterm> and 83 <glossterm><link linkend='var-SRC_URI'>SRC_URI</link></glossterm> and
85 <filename>also inherits autotools</filename>, which instructs BitBake to use the 84 <filename>also inherits autotools</filename>, which instructs Bitbake to use the
86 <filename>autotools.bbclass</filename> containing the definitions of all the steps 85 <filename>autotools.bbclass</filename> file, which contains the definitions of all the steps
87 needed to build an autotooled application. 86 needed to build an autotooled application.
88 The result of the build is automatically packaged. 87 The result of the build is automatically packaged.
89 And, if the application uses NLS for localization, packages with local information are 88 And, if the application uses NLS for localization, packages with local information are
90 generated (one package per language). 89 generated (one package per language).
91 Following is one example (<filename>hello_2.2.bb</filename>) 90 Following is one example: (<filename>hello_2.2.bb</filename>)
92 </para> 91 </para>
93 <programlisting> 92 <programlisting>
94DESCRIPTION = "GNU Helloworld application" 93DESCRIPTION = "GNU Helloworld application"
@@ -102,9 +101,9 @@ SRC_URI = "${GNU_MIRROR}/hello/hello-${PV}.tar.gz"
102inherit autotools gettext 101inherit autotools gettext
103 </programlisting> 102 </programlisting>
104 <para> 103 <para>
105 <glossterm><link linkend='var-LIC_FILES_CHKSUM'>LIC_FILES_CHKSUM</link> 104 The variable <glossterm><link linkend='var-LIC_FILES_CHKSUM'>LIC_FILES_CHKSUM</link>
106 </glossterm> is used to <link linkend='usingpoky-configuring-LIC_FILES_CHKSUM'> 105 </glossterm> is used to <link linkend='usingpoky-configuring-LIC_FILES_CHKSUM'>
107 track source license change</link>. 106 track source license changes</link>.
108 You can quickly create autotool-based recipes in a manner similar to the previous example. 107 You can quickly create autotool-based recipes in a manner similar to the previous example.
109 </para> 108 </para>
110 109
@@ -115,13 +114,13 @@ inherit autotools gettext
115 <para> 114 <para>
116 Applications that use GNU <filename>make</filename> also require a recipe that has 115 Applications that use GNU <filename>make</filename> also require a recipe that has
117 the source archive listed in <glossterm><link linkend='var-SRC_URI'>SRC_URI</link></glossterm>. 116 the source archive listed in <glossterm><link linkend='var-SRC_URI'>SRC_URI</link></glossterm>.
118 You do not need to add a <function>do_compile</function> step since by default BitBake 117 You do not need to add a <function>do_compile</function> step since by default Bitbake
119 starts the <filename>make</filename> command to compile the application. 118 starts the <filename>make</filename> command to compile the application.
120 If you need additional <filename>make</filename> options you should store them in the 119 If you need additional <filename>make</filename> options you should store them in the
121 <glossterm><link linkend='var-EXTRA_OEMAKE'>EXTRA_OEMAKE</link></glossterm> variable. 120 <glossterm><link linkend='var-EXTRA_OEMAKE'>EXTRA_OEMAKE</link></glossterm> variable.
122 Bitbake passes these options into the <filename>make</filename> GNU invocation. 121 Bitbake passes these options into the <filename>make</filename> GNU invocation.
123 Note that a <function>do_install</function> task is still required. 122 Note that a "do_install" task is still required.
124 Otherwise BitBake runs an empty <function>do_install</function> task by default. 123 Otherwise Bitbake runs an empty "do_install" task by default.
125 </para> 124 </para>
126 <para> 125 <para>
127 Some applications might require extra parameters to be passed to the compiler. 126 Some applications might require extra parameters to be passed to the compiler.
@@ -134,7 +133,7 @@ inherit autotools gettext
134CFLAGS_prepend = "-I ${S}/include " 133CFLAGS_prepend = "-I ${S}/include "
135 </programlisting> 134 </programlisting>
136 <para> 135 <para>
137 In the following example <filename>mtd-utils</filename> is a Makefile-based package: 136 In the following example <filename>mtd-utils</filename> is a makefile-based package:
138 </para> 137 </para>
139 <programlisting> 138 <programlisting>
140DESCRIPTION = "Tools for managing memory technology devices." 139DESCRIPTION = "Tools for managing memory technology devices."
@@ -171,7 +170,7 @@ do_install () {
171 </para> 170 </para>
172 <para> 171 <para>
173 Following is an example that uses the "libXpm" recipe (<filename>libxpm_3.5.7.bb</filename>). 172 Following is an example that uses the "libXpm" recipe (<filename>libxpm_3.5.7.bb</filename>).
174 By default, the "libXpm" recipe generates a single package containing the library, along 173 By default, the "libXpm" recipe generates a single package that contains the library along
175 with a few binaries. 174 with a few binaries.
176 You can modify the recipe to split the binaries into separate packages: 175 You can modify the recipe to split the binaries into separate packages:
177 </para> 176 </para>
@@ -198,8 +197,8 @@ FILES_sxpm = "${bindir}/sxpm"
198 package by default, we prepend the <glossterm><link linkend='var-PACKAGES'>PACKAGES</link> 197 package by default, we prepend the <glossterm><link linkend='var-PACKAGES'>PACKAGES</link>
199 </glossterm> variable so additional package names are added to the start of list. 198 </glossterm> variable so additional package names are added to the start of list.
200 This results in the extra <glossterm><link linkend='var-FILES'>FILES</link></glossterm>_* 199 This results in the extra <glossterm><link linkend='var-FILES'>FILES</link></glossterm>_*
201 variables then containing information defining which files and 200 variables then containing information that define which files and
202 directories go into which package. 201 directories go into which packages.
203 Files included by earlier packages are skipped by latter packages. 202 Files included by earlier packages are skipped by latter packages.
204 Thus, the main <glossterm><link linkend='var-PN'>PN</link></glossterm> package does not include 203 Thus, the main <glossterm><link linkend='var-PN'>PN</link></glossterm> package does not include
205 the above listed files. 204 the above listed files.
@@ -234,7 +233,7 @@ pkg_postinst_PACKAGENAME () {
234 Sometimes it is necessary for the execution of a post-installation 233 Sometimes it is necessary for the execution of a post-installation
235 script to be delayed until the first boot. 234 script to be delayed until the first boot.
236 For example, the script might need to be executed on the device itself. 235 For example, the script might need to be executed on the device itself.
237 To delay script execution until boot time, use the following structure for the 236 To delay script execution until boot time, use the following structure in the
238 post-installation script: 237 post-installation script:
239 </para> 238 </para>
240 <programlisting> 239 <programlisting>
@@ -259,8 +258,8 @@ fi
259 <section id='usingpoky-extend-customimage'> 258 <section id='usingpoky-extend-customimage'>
260 <title>Customizing Images</title> 259 <title>Customizing Images</title>
261 <para> 260 <para>
262 You can customize Poky images to satisfy particular requirements. 261 You can customize Poky images to satisfy particular requirements.
263 This section describes several methods and provides guidelines for each. 262 This section describes several methods and provides guidelines for each.
264 </para> 263 </para>
265 264
266 <section id='usingpoky-extend-customimage-custombb'> 265 <section id='usingpoky-extend-customimage-custombb'>
@@ -344,8 +343,8 @@ RRECOMMENDS_task-custom-tools = "\
344 <filename>task-custom-tools</filename>. 343 <filename>task-custom-tools</filename>.
345 To build an image using these task packages, you need to add 344 To build an image using these task packages, you need to add
346 "task-custom-apps" and/or "task-custom-tools" to <glossterm><link 345 "task-custom-apps" and/or "task-custom-tools" to <glossterm><link
347 linkend='var-IMAGE_INSTALL'>IMAGE_INSTALL</link></glossterm> or other forms 346 linkend='var-IMAGE_INSTALL'>IMAGE_INSTALL</link></glossterm>.
348 of image dependencies as described in other areas of this section. 347 For other forms of image dependencies see the other areas of this section.
349 </para> 348 </para>
350 </section> 349 </section>
351 350
@@ -359,7 +358,7 @@ RRECOMMENDS_task-custom-tools = "\
359 <filename>meta/classes/poky-image.bbclass</filename>, which shows how poky achieves this. 358 <filename>meta/classes/poky-image.bbclass</filename>, which shows how poky achieves this.
360 In summary, the file looks at the contents of the 359 In summary, the file looks at the contents of the
361 <glossterm><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></glossterm> 360 <glossterm><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></glossterm>
362 variable and then maps them into a set of tasks or packages. 361 variable and then maps that into a set of tasks or packages.
363 Based on this information the <glossterm><link linkend='var-IMAGE_INSTALL'> IMAGE_INSTALL</link> 362 Based on this information the <glossterm><link linkend='var-IMAGE_INSTALL'> IMAGE_INSTALL</link>
364 </glossterm> variable is generated automatically. 363 </glossterm> variable is generated automatically.
365 Users can add extra features by extending the class or creating a custom class for use 364 Users can add extra features by extending the class or creating a custom class for use
@@ -370,12 +369,12 @@ RRECOMMENDS_task-custom-tools = "\
370 <section id='usingpoky-extend-customimage-localconf'> 369 <section id='usingpoky-extend-customimage-localconf'>
371 <title>Customizing Images Using local.conf</title> 370 <title>Customizing Images Using local.conf</title>
372 <para> 371 <para>
373 It is possible to customize image contents by abusing variables used by distribution 372 It is possible to customize image contents by using variables used by distribution
374 maintainers in local.conf. 373 maintainers in the <filename>local.conf</filename>.
375 This method only allows the addition of packages and is not recommended. 374 This method only allows the addition of packages and is not recommended.
376 </para> 375 </para>
377 <para> 376 <para>
378 For example, to add the "strace" package into the image the you would add this to the 377 For example, to add the "strace" package into the image you would add this package to the
379 <filename>local.conf</filename> file: 378 <filename>local.conf</filename> file:
380 </para> 379 </para>
381 <programlisting> 380 <programlisting>
@@ -387,18 +386,18 @@ DISTRO_EXTRA_RDEPENDS += "strace"
387 distribution maintainers, adding packages using this method is not as simple as adding 386 distribution maintainers, adding packages using this method is not as simple as adding
388 them using a custom <filename>.bb</filename> file. 387 them using a custom <filename>.bb</filename> file.
389 Using the <filename>local.conf</filename> file method could result in some packages 388 Using the <filename>local.conf</filename> file method could result in some packages
390 requiring recreation. 389 needing to be recreated.
391 For example, if packages were previously created and the image was rebuilt then the packages 390 For example, if packages were previously created and the image was rebuilt then the packages
392 would need to be recreated. 391 would need to be recreated.
393 </para> 392 </para>
394 <para> 393 <para>
395 Cleaning task-* packages is required because they use the 394 Cleaning task-* packages are required because they use the
396 <glossterm><link linkend='var-DISTRO_EXTRA_RDEPENDS'> 395 <glossterm><link linkend='var-DISTRO_EXTRA_RDEPENDS'>
397 DISTRO_EXTRA_RDEPENDS</link></glossterm> variable. 396 DISTRO_EXTRA_RDEPENDS</link></glossterm> variable.
398 You do not have to build them by hand because Poky images depend on the packages they contain. 397 You do not have to build them by hand because Poky images depend on the packages they contain.
399 This means dependencies are automatically built when the image builds. 398 This means dependencies are automatically built when the image builds.
400 For this reason we don't use the "rebuild" task. 399 For this reason we don't use the "rebuild" task.
401 In this case the "rebuild" task does does not care about 400 In this case the "rebuild" task does not care about
402 dependencies - it only rebuilds the specified package. 401 dependencies - it only rebuilds the specified package.
403 </para> 402 </para>
404 <programlisting> 403 <programlisting>
@@ -416,24 +415,23 @@ $ bitbake poky-image-sato
416 This section provides information that gives you an idea of the changes you must make. 415 This section provides information that gives you an idea of the changes you must make.
417 The information covers adding machines similar to those Poky already supports. 416 The information covers adding machines similar to those Poky already supports.
418 Although well within the capabilities of Poky, adding a totally new architecture might require 417 Although well within the capabilities of Poky, adding a totally new architecture might require
419 changes to <filename>gcc/glibc</filename> and to the site information. 418 changes to <filename>gcc/glibc</filename> and to the site information, which is
420 Consequently, the information is beyond the scope of this manual. 419 beyond the scope of this manual.
421 </para> 420 </para>
422 421
423 <section id="platdev-newmachine-conffile"> 422 <section id="platdev-newmachine-conffile">
424 <title>Adding the Machine Configuration File</title> 423 <title>Adding the Machine Configuration File</title>
425 <para> 424 <para>
426 To add a machine configuration you need to add a <filename>.conf</filename> file 425 To add a machine configuration you need to add a <filename>.conf</filename> file
427 with details of the device being added to <filename>conf/machine/</filename>. 426 with details of the device being added to the <filename>conf/machine/</filename> file.
428 The name of the file determines the name Poky uses to reference the new machine. 427 The name of the file determines the name Poky uses to reference the new machine.
429 </para> 428 </para>
430 <para> 429 <para>
431 The most important variables to set in this file are <glossterm> 430 The most important variables to set in this file are <glossterm>
432 <link linkend='var-TARGET_ARCH'>TARGET_ARCH</link></glossterm> 431 <link linkend='var-TARGET_ARCH'>TARGET_ARCH</link></glossterm> (e.g. "arm"),
433 (e.g. "arm"), <glossterm><link linkend='var-PREFERRED_PROVIDER'> 432 <glossterm><link linkend='var-PREFERRED_PROVIDER'>PREFERRED_PROVIDER</link></glossterm>_virtual/kernel
434 PREFERRED_PROVIDER</link></glossterm>_virtual/kernel (see below) and 433 (see below) and <glossterm><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></glossterm>
435 <glossterm><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES 434 (e.g. "kernel26 apm screen wifi").
436 </link></glossterm> (e.g. "kernel26 apm screen wifi").
437 You might also need other variables like <glossterm><link linkend='var-SERIAL_CONSOLE'>SERIAL_CONSOLE 435 You might also need other variables like <glossterm><link linkend='var-SERIAL_CONSOLE'>SERIAL_CONSOLE
438 </link></glossterm> (e.g. "115200 ttyS0"), <glossterm> 436 </link></glossterm> (e.g. "115200 ttyS0"), <glossterm>
439 <link linkend='var-KERNEL_IMAGETYPE'>KERNEL_IMAGETYPE</link> 437 <link linkend='var-KERNEL_IMAGETYPE'>KERNEL_IMAGETYPE</link>
@@ -461,7 +459,7 @@ $ bitbake poky-image-sato
461 <link linkend='var-S'>S</link></glossterm> to point at the source code. 459 <link linkend='var-S'>S</link></glossterm> to point at the source code.
462 You need to create a "configure" task that configures the unpacked kernel with a defconfig. 460 You need to create a "configure" task that configures the unpacked kernel with a defconfig.
463 You can do this by using a <filename>make defconfig</filename> command or 461 You can do this by using a <filename>make defconfig</filename> command or
464 more commonly by copying in a suitable defconfig and and then running 462 more commonly by copying in a suitable <filename>defconfig</filename> file and and then running
465 <filename>make oldconfig</filename>. 463 <filename>make oldconfig</filename>.
466 By making use of "inherit kernel" and potentially some of the 464 By making use of "inherit kernel" and potentially some of the
467 <filename>linux-*.inc</filename> files, most other functionality is 465 <filename>linux-*.inc</filename> files, most other functionality is
@@ -486,12 +484,12 @@ COMPATIBLE_MACHINE = '(qemux86|qemumips)'
486 <title>Adding a Formfactor Configuration File</title> 484 <title>Adding a Formfactor Configuration File</title>
487 <para> 485 <para>
488 A formfactor configuration file provides information about the 486 A formfactor configuration file provides information about the
489 target hardware on which Poky is running, and that Poky cannot 487 target hardware on which Poky is running, and information that Poky cannot
490 obtain from other sources such as the kernel. 488 obtain from other sources such as the kernel.
491 Some examples of information contained in a formfactor configuration file include 489 Some examples of information contained in a formfactor configuration file include
492 framebuffer orientation, whether or not the system has a keyboard, 490 framebuffer orientation, whether or not the system has a keyboard,
493 the positioning of the keyboard in relation to the screen, and 491 the positioning of the keyboard in relation to the screen, and
494 screen resolution. 492 the screen resolution.
495 </para> 493 </para>
496 <para> 494 <para>
497 Reasonable defaults are used in most cases, but if customization is 495 Reasonable defaults are used in most cases, but if customization is
@@ -545,7 +543,7 @@ DISPLAY_SUBPIXEL_ORDER=vrgb
545 <para> 543 <para>
546 The Poky tree includes several additional layers such as meta-emenlow and meta-extras 544 The Poky tree includes several additional layers such as meta-emenlow and meta-extras
547 that demonstrate this functionality. 545 that demonstrate this functionality.
548 The meta-emenlow layer is an example layer that by default is enabled. 546 The meta-emenlow layer is an example layer that, by default, is enabled.
549 However, the meta-extras repository is not enabled by default. 547 However, the meta-extras repository is not enabled by default.
550 It is easy though to enable any layer. 548 It is easy though to enable any layer.
551 You simply add the layer's path to the 549 You simply add the layer's path to the
@@ -554,16 +552,16 @@ DISPLAY_SUBPIXEL_ORDER=vrgb
554 The following example shows how to enable meta-extras in the Poky build: 552 The following example shows how to enable meta-extras in the Poky build:
555 </para> 553 </para>
556 <para> 554 <para>
557 <literallayout class='monospaced'> 555 <programlisting>
558 LCONF_VERSION = "1" 556LCONF_VERSION = "1"
559 557
560 BBFILES ?= "" 558BBFILES ?= ""
561 BBLAYERS = " \ 559BBLAYERS = " \
562 /path/to/poky/meta \ 560 /path/to/poky/meta \
563 /path/to/poky/meta-emenlow \ 561 /path/to/poky/meta-emenlow \
564 /path/to/poky/meta-extras \ 562 /path/to/poky/meta-extras \
565 " 563 "
566 </literallayout> 564 </programlisting>
567 </para> 565 </para>
568 566
569 <para> 567 <para>
@@ -575,18 +573,18 @@ DISPLAY_SUBPIXEL_ORDER=vrgb
575 </para> 573 </para>
576 <para> 574 <para>
577 The <filename>meta-emenlow/conf/layer.conf</filename> file demonstrates the required syntax: 575 The <filename>meta-emenlow/conf/layer.conf</filename> file demonstrates the required syntax:
578 <literallayout class='monospaced'> 576 <programlisting>
579 # We have a conf and classes directory, add to BBPATH 577# We have a conf and classes directory, add to BBPATH
580 BBPATH := "${BBPATH}:${LAYERDIR}" 578BBPATH := "${BBPATH}:${LAYERDIR}"
581 579
582 # We have a recipes directory containing both .bb and .bbappend files, add to BBFILES 580# We have a recipes directory containing both .bb and .bbappend files, add to BBFILES
583 BBFILES := "${BBFILES} ${LAYERDIR}/recipes/*/*.bb \ 581BBFILES := "${BBFILES} ${LAYERDIR}/recipes/*/*.bb \
584 ${LAYERDIR}/recipes/*/*.bbappend" 582 ${LAYERDIR}/recipes/*/*.bbappend"
585 583
586 BBFILE_COLLECTIONS += "emenlow" 584BBFILE_COLLECTIONS += "emenlow"
587 BBFILE_PATTERN_emenlow := "^${LAYERDIR}/" 585BBFILE_PATTERN_emenlow := "^${LAYERDIR}/"
588 BBFILE_PRIORITY_emenlow = "6" 586BBFILE_PRIORITY_emenlow = "6"
589 </literallayout> 587 </programlisting>
590 </para> 588 </para>
591 <para> 589 <para>
592 In the previous example, the recipes for the layers are added to 590 In the previous example, the recipes for the layers are added to
@@ -598,7 +596,7 @@ DISPLAY_SUBPIXEL_ORDER=vrgb
598 a particular layer, in this case by using the base pathname. 596 a particular layer, in this case by using the base pathname.
599 The <glossterm><link linkend='var-BBFILE_PRIORITY'>BBFILE_PRIORITY</link></glossterm> variable 597 The <glossterm><link linkend='var-BBFILE_PRIORITY'>BBFILE_PRIORITY</link></glossterm> variable
600 then assigns different priorities to the files in different layers. 598 then assigns different priorities to the files in different layers.
601 This technique useful in situations where the same package might appear in multiple 599 Applying priorities is useful in situations where the same package might appear in multiple
602 layers and allows you to choose what layer should take precedence. 600 layers and allows you to choose what layer should take precedence.
603 </para> 601 </para>
604 <para> 602 <para>
@@ -637,11 +635,14 @@ DISPLAY_SUBPIXEL_ORDER=vrgb
637 revision control system. 635 revision control system.
638 Because some simple practices can significantly improve usability, policy for committing changes 636 Because some simple practices can significantly improve usability, policy for committing changes
639 is important. 637 is important.
638 It helps to use a consistent documentation style when committing changes.
639 We have found the following style works well.
640 </para>
641 <para>
640 Following are suggestions for committing changes to the Poky core: 642 Following are suggestions for committing changes to the Poky core:
641 </para> 643 </para>
644
642 <para> 645 <para>
643 It helps to use a consistent documentation style when committing changes.
644 We have found the following style works well.
645 <itemizedlist> 646 <itemizedlist>
646 <listitem><para>The first line of the commit summarizes the change and begins with the 647 <listitem><para>The first line of the commit summarizes the change and begins with the
647 name of the affected package or packages. 648 name of the affected package or packages.
@@ -680,10 +681,10 @@ DISPLAY_SUBPIXEL_ORDER=vrgb
680 <para> 681 <para>
681 If a committed change results in changing the package output 682 If a committed change results in changing the package output
682 then the value of the <glossterm><link linkend='var-PR'>PR</link> 683 then the value of the <glossterm><link linkend='var-PR'>PR</link>
683 </glossterm> variable needs to be increased ('bumped') as part of that commit. 684 </glossterm> variable needs to be increased (or 'bumped') as part of that commit.
684 This means that for new recipes you be sure to add the PR variable and set its initial value 685 This means that for new recipes you must be sure to add the PR variable and set its initial value
685 equal to "r0". 686 equal to "r0".
686 Not initially defining PR makes makes it easy to miss when you bump a package. 687 Not initially defining PR makes it easy to miss when you bump a package.
687 Note that you can only use integer values for the PR variable. 688 Note that you can only use integer values for the PR variable.
688 </para> 689 </para>
689 <para> 690 <para>
@@ -691,7 +692,7 @@ DISPLAY_SUBPIXEL_ORDER=vrgb
691 linkend='var-PV'>PV</link></glossterm>) and PR variables should be reset to "r0". 692 linkend='var-PV'>PV</link></glossterm>) and PR variables should be reset to "r0".
692 </para> 693 </para>
693 <para> 694 <para>
694 Usually a package version only increases. 695 Usually, version increases occur only to packages.
695 However, if for some reason PV changes but does not increase, you can increase the 696 However, if for some reason PV changes but does not increase, you can increase the
696 <glossterm><link linkend='var-PE'>PE</link></glossterm> variable (Package Epoch). 697 <glossterm><link linkend='var-PE'>PE</link></glossterm> variable (Package Epoch).
697 The PE variable defaults to '0'. 698 The PE variable defaults to '0'.
@@ -718,7 +719,7 @@ DISPLAY_SUBPIXEL_ORDER=vrgb
718 <section id="usingpoky-changes-collaborate"> 719 <section id="usingpoky-changes-collaborate">
719 <title>Using Poky in a Team Environment</title> 720 <title>Using Poky in a Team Environment</title>
720 <para> 721 <para>
721 It may not be immediately clear how you can use Poky in a team environment, 722 It might not be immediately clear how you can use Poky in a team environment,
722 or scale it for a large team of developers. 723 or scale it for a large team of developers.
723 The specifics of any situation determine the best solution. 724 The specifics of any situation determine the best solution.
724 Granted that Poky offers immense flexibility regarding this, practices do exist 725 Granted that Poky offers immense flexibility regarding this, practices do exist
@@ -728,7 +729,7 @@ DISPLAY_SUBPIXEL_ORDER=vrgb
728 The core component of any development effort with Poky is often an 729 The core component of any development effort with Poky is often an
729 automated build testing framework and an image generation process. 730 automated build testing framework and an image generation process.
730 You can use these core components to check that the metadata is buildable, 731 You can use these core components to check that the metadata is buildable,
731 highlight when commits break the builds, and provide up-to-date images that 732 highlight when commits break the build, and provide up-to-date images that
732 allow people to test the end result and use it as a base platform for further 733 allow people to test the end result and use it as a base platform for further
733 development. 734 development.
734 Experience shows that buildbot is a good fit for this role. 735 Experience shows that buildbot is a good fit for this role.
@@ -747,7 +748,7 @@ DISPLAY_SUBPIXEL_ORDER=vrgb
747 </para> 748 </para>
748 <para> 749 <para>
749 Full builds build and test everything from the ground up. 750 Full builds build and test everything from the ground up.
750 They usually happen at preset times like during the night when the machine 751 They usually happen at predetermined times like during the night when the machine
751 load is low. 752 load is low.
752 </para> 753 </para>
753 <para> 754 <para>
@@ -768,7 +769,7 @@ DISPLAY_SUBPIXEL_ORDER=vrgb
768 Of course circumstances will be different in each case. 769 Of course circumstances will be different in each case.
769 However, this situation reveals one of Poky's advantages - the system itself does not 770 However, this situation reveals one of Poky's advantages - the system itself does not
770 force any particular policy on users, unlike a lot of build systems. 771 force any particular policy on users, unlike a lot of build systems.
771 The system allows the best policy to be chosen for the given circumstances. 772 The system allows the best policies to be chosen for the given circumstances.
772 </para> 773 </para>
773 </section> 774 </section>
774 775
@@ -797,7 +798,7 @@ DISPLAY_SUBPIXEL_ORDER=vrgb
797 Although Poky is usually used to build software, you can use it to modify software. 798 Although Poky is usually used to build software, you can use it to modify software.
798 </para> 799 </para>
799 <para> 800 <para>
800 During building, source is available in the 801 During a build, source is available in the
801 <glossterm><link linkend='var-WORKDIR'>WORKDIR</link></glossterm> directory. 802 <glossterm><link linkend='var-WORKDIR'>WORKDIR</link></glossterm> directory.
802 The actual location depends on the type of package and the architecture of the target device. 803 The actual location depends on the type of package and the architecture of the target device.
803 For a standard recipe not related to 804 For a standard recipe not related to
@@ -811,7 +812,7 @@ DISPLAY_SUBPIXEL_ORDER=vrgb
811 <para> 812 <para>
812 Be sure the package recipe sets the 813 Be sure the package recipe sets the
813 <glossterm><link linkend='var-S'>S</link></glossterm> variable to something 814 <glossterm><link linkend='var-S'>S</link></glossterm> variable to something
814 other than standard <filename>WORKDIR/PN-PV/</filename> value. 815 other than the standard <filename>WORKDIR/PN-PV/</filename> value.
815 </para> 816 </para>
816 </tip> 817 </tip>
817 <para> 818 <para>
@@ -820,9 +821,9 @@ DISPLAY_SUBPIXEL_ORDER=vrgb
820 following example: 821 following example:
821 </para> 822 </para>
822 823
823 <programlisting> 824 <literallayout class='monospaced'>
824bitbake -c compile -f NAME_OF_PACKAGE 825 $ bitbake -c compile -f NAME_OF_PACKAGE
825 </programlisting> 826 </literallayout>
826 827
827 <para> 828 <para>
828 The "-f" or "--force" option forces re-execution of the specified task. 829 The "-f" or "--force" option forces re-execution of the specified task.
@@ -836,28 +837,28 @@ bitbake -c compile -f NAME_OF_PACKAGE
836 <title>Modifying Package Source Code with quilt</title> 837 <title>Modifying Package Source Code with quilt</title>
837 <para> 838 <para>
838 By default Poky uses <ulink url='http://savannah.nongnu.org/projects/quilt'>quilt</ulink> 839 By default Poky uses <ulink url='http://savannah.nongnu.org/projects/quilt'>quilt</ulink>
839 to manage patches in the <filename>do_patch</filename> task. 840 to manage patches in the "do_patch" task.
840 This is a powerful tool that you can use to track all modifications to package sources. 841 This is a powerful tool that you can use to track all modifications to package sources.
841 </para> 842 </para>
842 <para> 843 <para>
843 Before modifying source code, it is important to notify quilt so it can track the changes 844 Before modifying source code, it is important to notify quilt so it can track the changes
844 into the new patch file: 845 into the new patch file:
845 846
846 <programlisting> 847 <literallayout class='monospaced'>
847quilt new NAME-OF-PATCH.patch 848quilt new NAME-OF-PATCH.patch
848 </programlisting> 849 </literallayout>
849 850
850 After notifying quilt, add all modified files into that patch: 851 After notifying quilt, add all modified files into that patch:
851 <programlisting> 852 <literallayout class='monospaced'>
852quilt add file1 file2 file3 853quilt add file1 file2 file3
853 </programlisting> 854 </literallayout>
854 855
855 You can now start editing. 856 You can now start editing.
856 Once you are done editing, you need to use quilt to generate the final patch that 857 Once you are done editing, you need to use quilt to generate the final patch that
857 will contain all your modifications. 858 will contain all your modifications.
858 <programlisting> 859 <literallayout class='monospaced'>
859quilt refresh 860quilt refresh
860 </programlisting> 861 </literallayout>
861 862
862 You can find the resulting patch file in the 863 You can find the resulting patch file in the
863 <filename>patches/</filename> subdirectory of the source 864 <filename>patches/</filename> subdirectory of the source
@@ -869,8 +870,8 @@ quilt refresh
869SRC_URI += "file://NAME-OF-PATCH.patch" 870SRC_URI += "file://NAME-OF-PATCH.patch"
870 </programlisting> 871 </programlisting>
871 Finally, don't forget to 'bump' the 872 Finally, don't forget to 'bump' the
872 <glossterm><link linkend='var-PR'>PR</link></glossterm> value in the same recipe. 873 <glossterm><link linkend='var-PR'>PR</link></glossterm> value in the same recipe since
873 The resulting packages have changed. 874 the resulting packages have changed.
874 </para> 875 </para>
875 </section> 876 </section>
876 877
@@ -880,8 +881,7 @@ SRC_URI += "file://NAME-OF-PATCH.patch"
880 <title>Track License Change</title> 881 <title>Track License Change</title>
881 <para> 882 <para>
882 The license of an upstream project might change in the future. 883 The license of an upstream project might change in the future.
883 To address this situation, Poky uses the 884 Poky uses the <glossterm><link linkend='var-LIC_FILES_CHKSUM'>LIC_FILES_CHKSUM</link></glossterm> variable
884 <glossterm><link linkend='var-LIC_FILES_CHKSUM'>LIC_FILES_CHKSUM</link></glossterm> variable
885 to track license changes. 885 to track license changes.
886 </para> 886 </para>
887 887
@@ -940,7 +940,7 @@ LIC_FILES_CHKSUM = "file://../license.html;md5=5c94767cedb5d6987c902ac850ded2c6"
940 This mismatch triggers a build failure and notifies the developer. 940 This mismatch triggers a build failure and notifies the developer.
941 Notification allows the developer to review and address the license text changes. 941 Notification allows the developer to review and address the license text changes.
942 Also note that if a mis-match occurs during the build, the correct md5 942 Also note that if a mis-match occurs during the build, the correct md5
943 checksum is placed in the build log, which can be easily copied to a .bb file. 943 checksum is placed in the build log and can be easily copied to a .bb file.
944 </para> 944 </para>
945 <para> 945 <para>
946 There is no limit to how many files you can specify using the LIC_FILES_CHKSUM variable. 946 There is no limit to how many files you can specify using the LIC_FILES_CHKSUM variable.
@@ -950,7 +950,7 @@ LIC_FILES_CHKSUM = "file://../license.html;md5=5c94767cedb5d6987c902ac850ded2c6"
950 This practice allow you to just track the "COPYING" file as long as it is kept up to date. 950 This practice allow you to just track the "COPYING" file as long as it is kept up to date.
951 </para> 951 </para>
952 <tip> 952 <tip>
953 If you specify an empty or invalid "md5" parameter, bitback returns an md5 mis-match 953 If you specify an empty or invalid "md5" parameter, Bitbake returns an md5 mis-match
954 error and displays the correct "md5" parameter value during the build. The correct parameter 954 error and displays the correct "md5" parameter value during the build. The correct parameter
955 is also captured in the build log. 955 is also captured in the build log.
956 </tip> 956 </tip>
@@ -966,7 +966,7 @@ LIC_FILES_CHKSUM = "file://../license.html;md5=5c94767cedb5d6987c902ac850ded2c6"
966 <para> 966 <para>
967 Sometimes a package name you are using might exist under an alias or as a similarly named 967 Sometimes a package name you are using might exist under an alias or as a similarly named
968 package in a different distribution. 968 package in a different distribution.
969 Poky implements a distro_check task that automatically connects to major distributions 969 Poky implements a "distro_check" task that automatically connects to major distributions
970 and checks for these situations. 970 and checks for these situations.
971 If the package exists under a different name in a different distribution you get a 971 If the package exists under a different name in a different distribution you get a
972 distro_check mismatch. 972 distro_check mismatch.
@@ -986,7 +986,7 @@ DISTRO_PN_ALIAS_pn-PACKAGENAME = "distro1=package_name_alias1 \
986 </programlisting> 986 </programlisting>
987 </para> 987 </para>
988 <para> 988 <para>
989 If you have more than one distribution alias separate them with a space. 989 If you have more than one distribution alias, separate them with a space.
990 Note that Poky currently automatically checks the Fedora, OpenSuSE, Debian, Ubuntu, 990 Note that Poky currently automatically checks the Fedora, OpenSuSE, Debian, Ubuntu,
991 and Mandriva distributions for source package recipes without having to specify them 991 and Mandriva distributions for source package recipes without having to specify them
992 using the DISTRO_PN_ALIAS variable. 992 using the DISTRO_PN_ALIAS variable.