summaryrefslogtreecommitdiffstats
path: root/handbook
diff options
context:
space:
mode:
authorKevin Tian <kevin.tian@intel.com>2010-09-09 09:00:31 (GMT)
committerRichard Purdie <rpurdie@linux.intel.com>2010-09-10 10:57:31 (GMT)
commit3c6e1d7c623672f6424508fd0ebbe795265a0fe0 (patch)
tree28a573430cf1982b6101be2eca74556fd569a323 /handbook
parent7ef86584027458b41d8600700ef77647a23b1b92 (diff)
downloadpoky-3c6e1d7c623672f6424508fd0ebbe795265a0fe0.tar.gz
handbook: review and correct CH3(extend poky) in handbook
Fix inaccurate descriptions. Update recipe examples to make sure they do build Add some examples for better guidance Signed-off-by: Kevin Tian <kevin.tian@intel.com> Signed-off-by: Ke Yu <ke.yu@intel.com>
Diffstat (limited to 'handbook')
-rw-r--r--handbook/extendpoky.xml253
1 files changed, 172 insertions, 81 deletions
diff --git a/handbook/extendpoky.xml b/handbook/extendpoky.xml
index 61d354f..6162005 100644
--- a/handbook/extendpoky.xml
+++ b/handbook/extendpoky.xml
@@ -27,7 +27,7 @@
27 27
28 <para> 28 <para>
29 Before writing a recipe from scratch it is often useful to check 29 Before writing a recipe from scratch it is often useful to check
30 someone else hasn't written one already. OpenEmbedded is a good place 30 whether someone else has written one already. OpenEmbedded is a good place
31 to look as it has a wider scope and hence a wider range of packages. 31 to look as it has a wider scope and hence a wider range of packages.
32 Poky aims to be compatible with OpenEmbedded so most recipes should 32 Poky aims to be compatible with OpenEmbedded so most recipes should
33 just work in Poky. 33 just work in Poky.
@@ -43,8 +43,8 @@
43 <title>Single .c File Package (Hello World!)</title> 43 <title>Single .c File Package (Hello World!)</title>
44 44
45 <para> 45 <para>
46 To build an application from a single file stored locally requires a 46 To build an application from a single file stored locally (e.g. under "files/")
47 recipe which has the file listed in the <glossterm><link 47 requires a recipe which has the file listed in the <glossterm><link
48 linkend='var-SRC_URI'>SRC_URI</link></glossterm> variable. In addition 48 linkend='var-SRC_URI'>SRC_URI</link></glossterm> variable. In addition
49 the <function>do_compile</function> and <function>do_install</function> 49 the <function>do_compile</function> and <function>do_install</function>
50 tasks need to be manually written. The <glossterm><link linkend='var-S'> 50 tasks need to be manually written. The <glossterm><link linkend='var-S'>
@@ -56,7 +56,7 @@
56DESCRIPTION = "Simple helloworld application" 56DESCRIPTION = "Simple helloworld application"
57SECTION = "examples" 57SECTION = "examples"
58LICENSE = "MIT" 58LICENSE = "MIT"
59LIC_FILES_CHKSUM = "file://COPYING;md5=ae764cfda68da96df20af9fbf9fe49bd" 59PR = "r0"
60 60
61SRC_URI = "file://helloworld.c" 61SRC_URI = "file://helloworld.c"
62 62
@@ -73,8 +73,9 @@ do_install() {
73 </programlisting> 73 </programlisting>
74 74
75 <para> 75 <para>
76 As a result of the build process "helloworld" and "helloworld-dbg" 76 As a result of the build process "helloworld", "helloworld-dbg" and "hellworld-dev"
77 packages will be built. 77 packages will be built by default. You can <link linkend='usingpoky-extend-addpkg-files'>
78 control package process</link> yourself.
78 </para> 79 </para>
79 </section> 80 </section>
80 81
@@ -93,20 +94,28 @@ do_install() {
93 The result of the build will be automatically packaged and if 94 The result of the build will be automatically packaged and if
94 the application uses NLS to localise then packages with 95 the application uses NLS to localise then packages with
95 locale information will be generated (one package per 96 locale information will be generated (one package per
96 language). 97 language). Below is one example (hello_2.2.bb)
97 </para> 98 </para>
98 99
99 <programlisting> 100 <programlisting>
100DESCRIPTION = "GNU Helloworld application" 101DESCRIPTION = "GNU Helloworld application"
101SECTION = "examples" 102SECTION = "examples"
102LICENSE = "GPLv2" 103LICENSE = "GPLv2+"
103LIC_FILES_CHKSUM = "file://COPYING;md5=ae764cfda68da96df20af9fbf9fe49bd" 104LIC_FILES_CHKSUM = "file://COPYING;md5=751419260aa954499f7abaabaa882bbe"
105PR = "r0"
104 106
105SRC_URI = "${GNU_MIRROR}/hello/hello-${PV}.tar.bz2" 107SRC_URI = "${GNU_MIRROR}/hello/hello-${PV}.tar.gz"
106 108
107inherit autotools 109inherit autotools gettext
108 </programlisting> 110 </programlisting>
109 111
112 <para>
113 <glossterm><link linkend='var-LIC_FILES_CHKSUM'>LIC_FILES_CHKSUM</link>
114 </glossterm> is used to <link linkend='usingpoky-configuring-LIC_FILES_CHKSUM'>
115 track source license change</link>. Autotool based recipe can be quickly
116 created this way like above example.
117 </para>
118
110 </section> 119 </section>
111 120
112 <section id='usingpoky-extend-addpkg-makefile'> 121 <section id='usingpoky-extend-addpkg-makefile'>
@@ -132,23 +141,38 @@ inherit autotools
132 Some applications may require extra parameters to be passed to 141 Some applications may require extra parameters to be passed to
133 the compiler, for example an additional header path. This can 142 the compiler, for example an additional header path. This can
134 be done buy adding to the <glossterm><link 143 be done buy adding to the <glossterm><link
135 linkend='var-CFLAGS'>CFLAGS</link></glossterm> variable, as in the example below. 144 linkend='var-CFLAGS'>CFLAGS</link></glossterm> variable, as in the example below:
145 </para>
146
147 <programlisting>
148CFLAGS_prepend = "-I ${S}/include "
149 </programlisting>
150
151 <para>
152 mtd-utils is an example as Makefile-based:
136 </para> 153 </para>
137 154
138 <programlisting> 155 <programlisting>
139DESCRIPTION = "Tools for managing memory technology devices." 156DESCRIPTION = "Tools for managing memory technology devices."
140SECTION = "base" 157SECTION = "base"
141DEPENDS = "zlib" 158DEPENDS = "zlib lzo e2fsprogs util-linux"
142HOMEPAGE = "http://www.linux-mtd.infradead.org/" 159HOMEPAGE = "http://www.linux-mtd.infradead.org/"
143LICENSE = "GPLv2" 160LICENSE = "GPLv2"
144LIC_FILES_CHKSUM = "file://COPYING;md5=ae764cfda68da96df20af9fbf9fe49bd"
145 161
146SRC_URI = "ftp://ftp.infradead.org/pub/mtd-utils/mtd-utils-${PV}.tar.gz" 162SRC_URI = "git://git.infradead.org/mtd-utils.git;protocol=git;tag=v${PV}"
147 163
148CFLAGS_prepend = "-I ${S}/include " 164S = "${WORKDIR}/git/"
149 165
150do_install() { 166EXTRA_OEMAKE = "'CC=${CC}' 'CFLAGS=${CFLAGS} -I${S}/include -DWITHOUT_XATTR' \
151 oe_runmake install DESTDIR=${D} 167 'BUILDDIR=${S}'"
168
169do_install () {
170 oe_runmake install DESTDIR=${D} SBINDIR=${sbindir} MANDIR=${mandir} \
171 INCLUDEDIR=${includedir}
172 install -d ${D}${includedir}/mtd/
173 for f in ${S}/include/mtd/*.h; do
174 install -m 0644 $f ${D}${includedir}/mtd/
175 done
152} 176}
153 </programlisting> 177 </programlisting>
154 178
@@ -165,7 +189,7 @@ do_install() {
165 </para> 189 </para>
166 190
167 <para> 191 <para>
168 Below the "libXpm" recipe is used as an example. By 192 Below the "libXpm" recipe (libxpm_3.5.7.bb) is used as an example. By
169 default the "libXpm" recipe generates one package 193 default the "libXpm" recipe generates one package
170 which contains the library 194 which contains the library
171 and also a few binaries. The recipe can be adapted to 195 and also a few binaries. The recipe can be adapted to
@@ -177,8 +201,9 @@ require xorg-lib-common.inc
177 201
178DESCRIPTION = "X11 Pixmap library" 202DESCRIPTION = "X11 Pixmap library"
179LICENSE = "X-BSD" 203LICENSE = "X-BSD"
180LIC_FILES_CHKSUM = "file://COPYING;md5=ae764cfda68da96df20af9fbf9fe49bd" 204DEPENDS += "libxext libsm libxt"
181DEPENDS += "libxext" 205PR = "r3"
206PE = "1"
182 207
183XORG_PN = "libXpm" 208XORG_PN = "libXpm"
184 209
@@ -194,9 +219,12 @@ FILES_sxpm = "${bindir}/sxpm"
194 package as standard we prepend the <glossterm><link 219 package as standard we prepend the <glossterm><link
195 linkend='var-PACKAGES'>PACKAGES</link></glossterm> variable so 220 linkend='var-PACKAGES'>PACKAGES</link></glossterm> variable so
196 additional package names are added to the start of list. The 221 additional package names are added to the start of list. The
197 extra <glossterm><link linkend='var-PN'>FILES</link></glossterm>_* 222 extra <glossterm><link linkend='var-FILES'>FILES</link></glossterm>_*
198 variables then contain information to specify which files and 223 variables then contain information to specify which files and
199 directories goes into which package. 224 directories goes into which package. Files included by earlier
225 package are skipped by latter packages, and thus main <glossterm>
226 <link linkend='var-PN'>PN</link></glossterm> will not include
227 above listed files
200 </para> 228 </para>
201 </section> 229 </section>
202 230
@@ -208,12 +236,15 @@ FILES_sxpm = "${bindir}/sxpm"
208 a <function>pkg_postinst_PACKAGENAME()</function> 236 a <function>pkg_postinst_PACKAGENAME()</function>
209 function to the .bb file 237 function to the .bb file
210 where PACKAGENAME is the name of the package to attach 238 where PACKAGENAME is the name of the package to attach
211 the postinst script to. A post-installation function has the following structure: 239 the postinst script to. Normally <glossterm><link
240 linkend='var-PN'>PN</link></glossterm> can be used which expands
241 to PACKAGENAME automatically. A post-installation function has the
242 following structure:
212 </para> 243 </para>
213 <programlisting> 244 <programlisting>
214pkg_postinst_PACKAGENAME () { 245pkg_postinst_PACKAGENAME () {
215#!/bin/sh -e 246 #!/bin/sh -e
216# Commands to carry out 247 # Commands to carry out
217} 248}
218 </programlisting> 249 </programlisting>
219 <para> 250 <para>
@@ -234,12 +265,12 @@ pkg_postinst_PACKAGENAME () {
234 265
235 <programlisting> 266 <programlisting>
236pkg_postinst_PACKAGENAME () { 267pkg_postinst_PACKAGENAME () {
237#!/bin/sh -e 268 #!/bin/sh -e
238if [ x"$D" = "x" ]; then 269 if [ x"$D" = "x" ]; then
239# Actions to carry out on the device go here 270 # Actions to carry out on the device go here
240else 271 else
241exit 1 272 exit 1
242fi 273 fi
243} 274}
244 </programlisting> 275 </programlisting>
245 276
@@ -349,7 +380,7 @@ RRECOMMENDS_task-custom-tools = "\
349 </para> 380 </para>
350 381
351 <para> 382 <para>
352 In this example, two tasks packages are created, task-custom-apps and 383 In this example, two task packages are created, task-custom-apps and
353 task-custom-tools with the dependencies and recommended package dependencies 384 task-custom-tools with the dependencies and recommended package dependencies
354 listed. To build an image using these task packages, you would then add 385 listed. To build an image using these task packages, you would then add
355 "task-custom-apps" and/or "task-custom-tools" to <glossterm><link 386 "task-custom-apps" and/or "task-custom-tools" to <glossterm><link
@@ -367,8 +398,9 @@ RRECOMMENDS_task-custom-tools = "\
367 variable. To create these, the best reference is <filename>meta/classes/poky-image.bbclass</filename> 398 variable. To create these, the best reference is <filename>meta/classes/poky-image.bbclass</filename>
368 which illustrates how poky achieves this. In summary, the file looks at the contents of the 399 which illustrates how poky achieves this. In summary, the file looks at the contents of the
369 <glossterm><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></glossterm> 400 <glossterm><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></glossterm>
370 variable and based on this generates the <glossterm><link linkend='var-IMAGE_INSTALL'> 401 variable and then map into a set of tasks or packages. Based on this then the
371 IMAGE_INSTALL</link></glossterm> variable automatically. Extra features can be added by 402 <glossterm><link linkend='var-IMAGE_INSTALL'> IMAGE_INSTALL</link></glossterm>
403 variable is generated automatically. Extra features can be added by
372 extending the class or creating a custom class for use with specialised image .bb files. 404 extending the class or creating a custom class for use with specialised image .bb files.
373 </para> 405 </para>
374 </section> 406 </section>
@@ -397,11 +429,11 @@ DISTRO_EXTRA_RDEPENDS += "strace"
397 DISTRO_EXTRA_RDEPENDS</link></glossterm> variable is for 429 DISTRO_EXTRA_RDEPENDS</link></glossterm> variable is for
398 distribution maintainers this method does not make 430 distribution maintainers this method does not make
399 adding packages as simple as a custom .bb file. Using 431 adding packages as simple as a custom .bb file. Using
400 this method, a few packages will need to be recreated 432 this method, a few packages will need to be recreated if they have been
401 and the the image built. 433 created before and then the image is rebuilt.
402 </para> 434 </para>
403 <programlisting> 435 <programlisting>
404bitbake -cclean task-boot task-base task-poky 436bitbake -c clean task-boot task-base task-poky
405bitbake poky-image-sato 437bitbake poky-image-sato
406 </programlisting> 438 </programlisting>
407 439
@@ -410,7 +442,7 @@ bitbake poky-image-sato
410 <glossterm><link linkend='var-DISTRO_EXTRA_RDEPENDS'> 442 <glossterm><link linkend='var-DISTRO_EXTRA_RDEPENDS'>
411 DISTRO_EXTRA_RDEPENDS</link></glossterm> variable. There is no need to 443 DISTRO_EXTRA_RDEPENDS</link></glossterm> variable. There is no need to
412 build them by hand as Poky images depend on the packages they contain so 444 build them by hand as Poky images depend on the packages they contain so
413 dependencies will be built automatically. For this reason we don't use the 445 dependencies will be built automatically when building the image. For this reason we don't use the
414 "rebuild" task in this case since "rebuild" does not care about 446 "rebuild" task in this case since "rebuild" does not care about
415 dependencies - it only rebuilds the specified package. 447 dependencies - it only rebuilds the specified package.
416 </para> 448 </para>
@@ -451,7 +483,8 @@ bitbake poky-image-sato
451 </glossterm> (e.g. "zImage") and <glossterm><link linkend='var-IMAGE_FSTYPES'> 483 </glossterm> (e.g. "zImage") and <glossterm><link linkend='var-IMAGE_FSTYPES'>
452 IMAGE_FSTYPES</link></glossterm> (e.g. "tar.gz jffs2") might also be 484 IMAGE_FSTYPES</link></glossterm> (e.g. "tar.gz jffs2") might also be
453 needed. Full details on what these variables do and the meaning of 485 needed. Full details on what these variables do and the meaning of
454 their contents is available through the links. 486 their contents is available through the links. There're lots of existing
487 machine .conf files which can be easily leveraged from meta/conf/machine/.
455 </para> 488 </para>
456 </section> 489 </section>
457 490
@@ -461,10 +494,10 @@ bitbake poky-image-sato
461 Poky needs to be able to build a kernel for the machine. You need 494 Poky needs to be able to build a kernel for the machine. You need
462 to either create a new kernel recipe for this machine or extend an 495 to either create a new kernel recipe for this machine or extend an
463 existing recipe. There are plenty of kernel examples in the 496 existing recipe. There are plenty of kernel examples in the
464 packages/linux directory which can be used as references. 497 meta/recipes-kernel/linux directory which can be used as references.
465 </para> 498 </para>
466 <para> 499 <para>
467 If creating a new recipe the "normal" recipe writing rules apply 500 If creating a new recipe the "normal" recipe writing rules apply
468 for setting up a <glossterm><link linkend='var-SRC_URI'>SRC_URI 501 for setting up a <glossterm><link linkend='var-SRC_URI'>SRC_URI
469 </link></glossterm> including any patches and setting <glossterm> 502 </link></glossterm> including any patches and setting <glossterm>
470 <link linkend='var-S'>S</link></glossterm> to point at the source 503 <link linkend='var-S'>S</link></glossterm> to point at the source
@@ -481,8 +514,11 @@ bitbake poky-image-sato
481 machine's defconfig files in a given kernel, possibly listing it in 514 machine's defconfig files in a given kernel, possibly listing it in
482 the SRC_URI and adding the machine to the expression in <glossterm> 515 the SRC_URI and adding the machine to the expression in <glossterm>
483 <link linkend='var-COMPATIBLE_MACHINE'>COMPATIBLE_MACHINE</link> 516 <link linkend='var-COMPATIBLE_MACHINE'>COMPATIBLE_MACHINE</link>
484 </glossterm>. 517 </glossterm>:
485 </para> 518 </para>
519 <programlisting>
520COMPATIBLE_MACHINE = '(qemux86|qemumips)'
521 </programlisting>
486 </section> 522 </section>
487 523
488 <section id="platdev-newmachine-formfactor"> 524 <section id="platdev-newmachine-formfactor">
@@ -502,8 +538,21 @@ bitbake poky-image-sato
502 under <filename>meta/packages/formfactor/files/MACHINENAME/</filename> 538 under <filename>meta/packages/formfactor/files/MACHINENAME/</filename>
503 where <literal>MACHINENAME</literal> is the name for which this infomation 539 where <literal>MACHINENAME</literal> is the name for which this infomation
504 applies. For information about the settings available and the defaults, please see 540 applies. For information about the settings available and the defaults, please see
505 <filename>meta/packages/formfactor/files/config</filename>. 541 <filename>meta/packages/formfactor/files/config</filename>. Below is one
542 example for qemuarm:
506 </para> 543 </para>
544 <programlisting>
545HAVE_TOUCHSCREEN=1
546HAVE_KEYBOARD=1
547
548DISPLAY_CAN_ROTATE=0
549DISPLAY_ORIENTATION=0
550#DISPLAY_WIDTH_PIXELS=640
551#DISPLAY_HEIGHT_PIXELS=480
552#DISPLAY_BPP=16
553DISPLAY_DPI=150
554DISPLAY_SUBPIXEL_ORDER=vrgb
555 </programlisting>
507 </section> 556 </section>
508</section> 557</section>
509 558
@@ -536,11 +585,13 @@ bitbake poky-image-sato
536 </para> 585 </para>
537 586
538 <para> 587 <para>
539 The Poky tree includes two additional layers which demonstrate 588 The Poky tree includes several additional layers which demonstrate
540 this functionality, meta-moblin and meta-extras. 589 this functionality, such as meta-moblin, meta-emenlow, meta-extras.
541 The meta-extras repostory is not enabled by default but enabling 590 Default layers enabled are meta-moblin and meta-emenlow, which may
542 it is as easy as adding the layers path to the BBLAYERS variable in 591 suffer from future changes. The meta-extras repostory is not enabled
543 your bblayers.conf, this is how all layers are enabled in Poky builds: 592 by default but enabling any layer is as easy as adding the layers path
593 to the BBLAYERS variable in your bblayers.conf. this is how meta-extras
594 are enabled in Poky builds:
544 </para> 595 </para>
545 <para> 596 <para>
546 <literallayout class='monospaced'>LCONF_VERSION = "1" 597 <literallayout class='monospaced'>LCONF_VERSION = "1"
@@ -549,6 +600,7 @@ BBFILES ?= ""
549BBLAYERS = " \ 600BBLAYERS = " \
550 /path/to/poky/meta \ 601 /path/to/poky/meta \
551 /path/to/poky/meta-moblin \ 602 /path/to/poky/meta-moblin \
603 /path/to/poky/meta-emenlow \
552 /path/to/poky/meta-extras \ 604 /path/to/poky/meta-extras \
553 " 605 "
554</literallayout> 606</literallayout>
@@ -563,23 +615,23 @@ BBLAYERS = " \
563 </para> 615 </para>
564 616
565 <para> 617 <para>
566 The meta-extras layer.conf demonstrates the required syntax: 618 The meta-emenlow/conf/layer.conf demonstrates the required syntax:
567 <literallayout class='monospaced'># We have a conf and classes directory, add to BBPATH 619 <literallayout class='monospaced'># We have a conf and classes directory, add to BBPATH
568BBPATH := "${BBPATH}${LAYERDIR}" 620BBPATH := "${BBPATH}:${LAYERDIR}"
569 621
570# We have a packages directory, add to BBFILES 622# We have a packages directory, add to BBFILES
571BBFILES := "${BBFILES} ${LAYERDIR}/packages/*/*.bb" 623BBFILES := "${BBFILES} ${LAYERDIR}/packages/*/*.bb \
572 624 ${LAYERDIR}/packages/*/*.bbappend"
573BBFILE_COLLECTIONS += "extras"
574BBFILE_PATTERN_extras := "^${LAYERDIR}/"
575BBFILE_PRIORITY_extras = "5"
576 625
577require conf/distro/include/poky-extras-src-revisions.inc 626BBFILE_COLLECTIONS += "emenlow"
627BBFILE_PATTERN_emenlow := "^${LAYERDIR}/"
628BBFILE_PRIORITY_emenlow = "6"
578 </literallayout> 629 </literallayout>
579 </para> 630 </para>
580 631
581 <para> 632 <para>
582 As can be seen, the layers recipes are added to BBFILES. The 633 As can be seen, the layers recipes are added to
634 <glossterm> <link linkend='var-BBFILES'>BBFILES</link></glossterm>. The
583 BBFILE_COLLECTIONS variable is then appended to with the 635 BBFILE_COLLECTIONS variable is then appended to with the
584 layer name. The BBFILE_PATTERN variable is immediately expanded 636 layer name. The BBFILE_PATTERN variable is immediately expanded
585 with a regular expression used to match files from BBFILES into 637 with a regular expression used to match files from BBFILES into
@@ -588,15 +640,17 @@ require conf/distro/include/poky-extras-src-revisions.inc
588 priorities to the files in different layers. This is useful 640 priorities to the files in different layers. This is useful
589 in situations where the same package might appear in multiple 641 in situations where the same package might appear in multiple
590 layers and allows you to choose which layer should 'win'. 642 layers and allows you to choose which layer should 'win'.
591 Note the use of LAYERDIR with the immediate expansion operator. 643 Note the use of <glossterm><link linkend='var-LAYERDIR'>
592 LAYERDIR expands to the directory of the current layer and 644 LAYERDIR</link></glossterm> with the immediate expansion operator.
645 <glossterm><link linkend='var-LAYERDIR'>LAYERDIR</link></glossterm>
646 expands to the directory of the current layer and
593 requires use of the immediate expansion operator so that Bitbake 647 requires use of the immediate expansion operator so that Bitbake
594 does not lazily expand the variable when it's parsing a 648 does not lazily expand the variable when it's parsing a
595 different directory. 649 different directory.
596 </para> 650 </para>
597 651
598 <para> 652 <para>
599 Extra bbclasses and configuration are added to the BBPATH 653 Emenlow bbclasses and configuration are added to the BBPATH
600 environment variable. In this case, the first file with the 654 environment variable. In this case, the first file with the
601 matching name found in BBPATH is the one that is used, just 655 matching name found in BBPATH is the one that is used, just
602 like the PATH variable for binaries. It is therefore recommended 656 like the PATH variable for binaries. It is therefore recommended
@@ -630,9 +684,19 @@ require conf/distro/include/poky-extras-src-revisions.inc
630 summarises the change and starts with the name of any package affected 684 summarises the change and starts with the name of any package affected
631 work well. Not all changes are to specific packages so the prefix could 685 work well. Not all changes are to specific packages so the prefix could
632 also be a machine name or class name instead. If a change needs a longer 686 also be a machine name or class name instead. If a change needs a longer
633 description this should follow the summary. 687 description this should follow the summary:
634 </para> 688 </para>
635 689
690 <literallayout class='monospaced'>
691 bitbake/data.py: Add emit_func() and generate_dependencies() functions
692
693 These functions allow generation of dependency data between funcitons and
694 variables allowing moves to be made towards generating checksums and allowing
695 use of the dependency information in other parts of bitbake.
696
697 Signed-off-by: Richard Purdie rpurdie@linux.intel.com
698 </literallayout>
699
636 <para> 700 <para>
637 Any commit should be self contained in that it should leave the 701 Any commit should be self contained in that it should leave the
638 metadata in a consistent state, buildable before and after the 702 metadata in a consistent state, buildable before and after the
@@ -655,7 +719,7 @@ require conf/distro/include/poky-extras-src-revisions.inc
655 it easy to miss incrementing it when updating the recipe. 719 it easy to miss incrementing it when updating the recipe.
656 When upgrading the version of a package (<glossterm><link 720 When upgrading the version of a package (<glossterm><link
657 linkend='var-PV'>PV</link></glossterm>), the <glossterm><link 721 linkend='var-PV'>PV</link></glossterm>), the <glossterm><link
658 linkend='var-PR'>PR</link></glossterm> variable should be removed. 722 linkend='var-PR'>PR</link></glossterm> variable should be reset to "r0".
659 </para> 723 </para>
660 724
661 <para> 725 <para>
@@ -675,7 +739,7 @@ require conf/distro/include/poky-extras-src-revisions.inc
675 the repository and don't have to remember to rebuild any sections. 739 the repository and don't have to remember to rebuild any sections.
676 The second is to ensure that target users are able to upgrade their 740 The second is to ensure that target users are able to upgrade their
677 devices via their package manager such as with the <command> 741 devices via their package manager such as with the <command>
678 opkg update;opkg upgrade</command> commands (or similar for 742 opkg upgrade</command> commands (or similar for
679 dpkg/apt or rpm based systems). The aim is to ensure Poky has 743 dpkg/apt or rpm based systems). The aim is to ensure Poky has
680 upgradable packages in all cases. 744 upgradable packages in all cases.
681 </para> 745 </para>
@@ -708,6 +772,8 @@ require conf/distro/include/poky-extras-src-revisions.inc
708 are builds that build everything from the ground up and test everything. 772 are builds that build everything from the ground up and test everything.
709 They usually happen at preset times such as at night when the machine 773 They usually happen at preset times such as at night when the machine
710 load isn't high from the incremental builds. 774 load isn't high from the incremental builds.
775 <ulink url='http://autobuilder.pokylinux.org:8010'>poky autobuilder</ulink>
776 is an example implementation with buildrot.
711 </para> 777 </para>
712 778
713 <para> 779 <para>
@@ -783,11 +849,14 @@ src/gz beagleboard http://www.mysite.com/somedir/deploy/ipk/beagleboard</literal
783 </para> 849 </para>
784 850
785 <programlisting> 851 <programlisting>
786bitbake --cmd compile --force NAME_OF_PACKAGE 852bitbake -c compile -f NAME_OF_PACKAGE
787 </programlisting> 853 </programlisting>
788 854
789 <para> 855 <para>
790 Other tasks may also be called this way. 856 "-f" or "--force" is used to force re-execution of the specified task.
857 Other tasks may also be called this way. But note that all the modifications
858 in <glossterm><link linkend='var-WORKDIR'>WORKDIR</link></glossterm>
859 are gone once you executes "-c clean" for a pacakge.
791 </para> 860 </para>
792 861
793 <section id='usingpoky-modifying-packages-quilt'> 862 <section id='usingpoky-modifying-packages-quilt'>
@@ -840,10 +909,11 @@ SRC_URI += "file://NAME-OF-PATCH.patch"
840 909
841 </section> 910 </section>
842 <section id='usingpoky-configuring-LIC_FILES_CHKSUM'> 911 <section id='usingpoky-configuring-LIC_FILES_CHKSUM'>
843 <title>Configuring the LIC_FILES_CHKSUM variable</title> 912 <title>Track license change</title>
844 <para> 913 <para>
845 The changes in the license text inside source code files is tracked 914 The license of one upstream project may change in the future, and Poky provides
846 using the LIC_FILES_CHKSUM metadata variable. 915 one mechanism to track such license change - <glossterm>
916 <link linkend='var-LIC_FILES_CHKSUM'>LIC_FILES_CHKSUM</link></glossterm> variable.
847 </para> 917 </para>
848 918
849 <section id='usingpoky-specifying-LIC_FILES_CHKSUM'> 919 <section id='usingpoky-specifying-LIC_FILES_CHKSUM'>
@@ -855,6 +925,26 @@ LIC_FILES_CHKSUM = "file://COPYING; md5=xxxx \
855 file://licfile2.txt; endline=50;md5=zzzz \ 925 file://licfile2.txt; endline=50;md5=zzzz \
856 ..." 926 ..."
857 </programlisting> 927 </programlisting>
928
929 <para>
930 <glossterm><link linkend='var-S'>S</link></glossterm> is the default directory
931 for searching files listed in <glossterm><link linkend='var-LIC_FILES_CHKSUM'>
932 LIC_FILES_CHKSUM</link></glossterm>. Relative path could be used too:
933 </para>
934
935 <programlisting>
936LIC_FILES_CHKSUM = "file://src/ls.c;startline=5;endline=16;\
937 md5=bb14ed3c4cda583abc85401304b5cd4e"
938LIC_FILES_CHKSUM = "file://../license.html;md5=5c94767cedb5d6987c902ac850ded2c6"
939 </programlisting>
940
941 <para>
942 The first line locates a file in <glossterm><link linkend='var-S'>
943 S</link></glossterm>/src/ls.c, and the second line refers to a file in
944 <glossterm><link linkend='var-WORKDIR'>WORKDIR</link></glossterm>, which is the parent
945 of <glossterm><link linkend='var-S'>S</link></glossterm>
946 </para>
947
858 </section> 948 </section>
859 949
860 <section id='usingpoky-LIC_FILES_CHKSUM-explanation-of-syntax'> 950 <section id='usingpoky-LIC_FILES_CHKSUM-explanation-of-syntax'>
@@ -873,12 +963,12 @@ to specify "beginline" and "endline" parameters.
873 </para> 963 </para>
874 <para> 964 <para>
875The "md5" parameter stores the md5 checksum of the license text. So if 965The "md5" parameter stores the md5 checksum of the license text. So if
876the license text changes in any way from a file, then it's md5 sum will differ and will not 966the license text changes in any way from a file, then its md5 sum will differ and will not
877match with the previously stored md5 checksum. This mismatch will trigger build 967match with the previously stored md5 checksum. This mismatch will trigger build
878failure, notifying developer about the license text md5 mismatch, and allowing 968failure, notifying developer about the license text md5 mismatch, and allowing
879the developer to review the license text changes. Also note that if md5 checksum 969the developer to review the license text changes. Also note that if md5 checksum
880is not matched while building, the correct md5 checksum is printed in the build 970is not matched while building, the correct md5 checksum is printed in the build
881log. 971log which can be easily copied to .bb file.
882 </para> 972 </para>
883 <para> 973 <para>
884There is no limit on how many files can be specified on this parameter. But generally every 974There is no limit on how many files can be specified on this parameter. But generally every
@@ -891,7 +981,7 @@ is valid then tracking only that file would be enough.
891 <para> 981 <para>
8921. If you specify empty or invalid "md5" parameter; then while building 9821. If you specify empty or invalid "md5" parameter; then while building
893the package, bitbake will give md5 not matched error, and also show the correct 983the package, bitbake will give md5 not matched error, and also show the correct
894"md5" parameter value in the build log 984"md5" parameter value both on the screen and in the build log
895 </para> 985 </para>
896 <para> 986 <para>
8972. If the whole file contains only license text, then there is no need to 9872. If the whole file contains only license text, then there is no need to
@@ -901,22 +991,23 @@ specify "beginline" and "endline" parameters.
901 </section> 991 </section>
902 </section> 992 </section>
903 <section id='usingpoky-configuring-DISTRO_PN_ALIAS'> 993 <section id='usingpoky-configuring-DISTRO_PN_ALIAS'>
904 <title>Configuring the DISTRO_PN_ALIAS variable</title> 994 <title>Handle package name alias</title>
905 <para> 995 <para>
906Sometimes the names of the same packages are different in different 996Poky implements a distro_check task which automatically connects to major distributions
907linux distributions; and that can becomes an issue for the distro_check 997and checks whether they contains same package. Sometimes the same package has different
908task to check if the given recipe package exists in other linux distros. 998names in different distributions, which results in a mismatch from distro_check task
909This issue is avoided by defining per distro recipe name alias: 999This can be solved by defining per distro recipe name alias -
910DISTRO_PN_ALIAS 1000<glossterm><link linkend='var-DISTRO_PN_ALIAS'>DISTRO_PN_ALIAS</link></glossterm>
911 </para> 1001 </para>
912 1002
913 <section id='usingpoky-specifying-DISTRO_PN_ALIAS'> 1003 <section id='usingpoky-specifying-DISTRO_PN_ALIAS'>
914 <title>Specifying the DISTRO_PN_ALIAS variable </title> 1004 <title>Specifying the DISTRO_PN_ALIAS variable </title>
915 1005
916 <programlisting> 1006 <programlisting>
917DISTRO_PN_ALIAS_pn = "distro1=package_name_alias1 distro2=package_name_alias2 \ 1007DISTRO_PN_ALIAS_pn-PACKAGENAME = "distro1=package_name_alias1 \
918 distro3=package_name_alias3 \ 1008 distro2=package_name_alias2 \
919 ..." 1009 distro3=package_name_alias3 \
1010 ..."
920 </programlisting> 1011 </programlisting>
921 <para> 1012 <para>
922Use space as the delimiter if there're multiple distro aliases 1013Use space as the delimiter if there're multiple distro aliases