From 3c6e1d7c623672f6424508fd0ebbe795265a0fe0 Mon Sep 17 00:00:00 2001 From: Kevin Tian Date: Thu, 9 Sep 2010 17:00:31 +0800 Subject: 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 Signed-off-by: Ke Yu --- handbook/extendpoky.xml | 253 ++++++++++++++++++++++++++++++++---------------- 1 file changed, 172 insertions(+), 81 deletions(-) diff --git a/handbook/extendpoky.xml b/handbook/extendpoky.xml index 61d354f39..61620053a 100644 --- a/handbook/extendpoky.xml +++ b/handbook/extendpoky.xml @@ -27,7 +27,7 @@ Before writing a recipe from scratch it is often useful to check - someone else hasn't written one already. OpenEmbedded is a good place + whether someone else has written one already. OpenEmbedded is a good place to look as it has a wider scope and hence a wider range of packages. Poky aims to be compatible with OpenEmbedded so most recipes should just work in Poky. @@ -43,8 +43,8 @@ Single .c File Package (Hello World!) - To build an application from a single file stored locally requires a - recipe which has the file listed in the SRC_URI variable. In addition the do_compile and do_install tasks need to be manually written. The @@ -56,7 +56,7 @@ DESCRIPTION = "Simple helloworld application" SECTION = "examples" LICENSE = "MIT" -LIC_FILES_CHKSUM = "file://COPYING;md5=ae764cfda68da96df20af9fbf9fe49bd" +PR = "r0" SRC_URI = "file://helloworld.c" @@ -73,8 +73,9 @@ do_install() { - As a result of the build process "helloworld" and "helloworld-dbg" - packages will be built. + As a result of the build process "helloworld", "helloworld-dbg" and "hellworld-dev" + packages will be built by default. You can + control package process yourself. @@ -93,20 +94,28 @@ do_install() { The result of the build will be automatically packaged and if the application uses NLS to localise then packages with locale information will be generated (one package per - language). + language). Below is one example (hello_2.2.bb) DESCRIPTION = "GNU Helloworld application" SECTION = "examples" -LICENSE = "GPLv2" -LIC_FILES_CHKSUM = "file://COPYING;md5=ae764cfda68da96df20af9fbf9fe49bd" +LICENSE = "GPLv2+" +LIC_FILES_CHKSUM = "file://COPYING;md5=751419260aa954499f7abaabaa882bbe" +PR = "r0" -SRC_URI = "${GNU_MIRROR}/hello/hello-${PV}.tar.bz2" +SRC_URI = "${GNU_MIRROR}/hello/hello-${PV}.tar.gz" -inherit autotools +inherit autotools gettext + + LIC_FILES_CHKSUM + is used to + track source license change. Autotool based recipe can be quickly + created this way like above example. + +
@@ -132,23 +141,38 @@ inherit autotools Some applications may require extra parameters to be passed to the compiler, for example an additional header path. This can be done buy adding to the CFLAGS variable, as in the example below. + linkend='var-CFLAGS'>CFLAGS variable, as in the example below: + + + +CFLAGS_prepend = "-I ${S}/include " + + + + mtd-utils is an example as Makefile-based: DESCRIPTION = "Tools for managing memory technology devices." SECTION = "base" -DEPENDS = "zlib" +DEPENDS = "zlib lzo e2fsprogs util-linux" HOMEPAGE = "http://www.linux-mtd.infradead.org/" LICENSE = "GPLv2" -LIC_FILES_CHKSUM = "file://COPYING;md5=ae764cfda68da96df20af9fbf9fe49bd" -SRC_URI = "ftp://ftp.infradead.org/pub/mtd-utils/mtd-utils-${PV}.tar.gz" +SRC_URI = "git://git.infradead.org/mtd-utils.git;protocol=git;tag=v${PV}" -CFLAGS_prepend = "-I ${S}/include " +S = "${WORKDIR}/git/" -do_install() { - oe_runmake install DESTDIR=${D} +EXTRA_OEMAKE = "'CC=${CC}' 'CFLAGS=${CFLAGS} -I${S}/include -DWITHOUT_XATTR' \ + 'BUILDDIR=${S}'" + +do_install () { + oe_runmake install DESTDIR=${D} SBINDIR=${sbindir} MANDIR=${mandir} \ + INCLUDEDIR=${includedir} + install -d ${D}${includedir}/mtd/ + for f in ${S}/include/mtd/*.h; do + install -m 0644 $f ${D}${includedir}/mtd/ + done } @@ -165,7 +189,7 @@ do_install() { - Below the "libXpm" recipe is used as an example. By + Below the "libXpm" recipe (libxpm_3.5.7.bb) is used as an example. By default the "libXpm" recipe generates one package which contains the library and also a few binaries. The recipe can be adapted to @@ -177,8 +201,9 @@ require xorg-lib-common.inc DESCRIPTION = "X11 Pixmap library" LICENSE = "X-BSD" -LIC_FILES_CHKSUM = "file://COPYING;md5=ae764cfda68da96df20af9fbf9fe49bd" -DEPENDS += "libxext" +DEPENDS += "libxext libsm libxt" +PR = "r3" +PE = "1" XORG_PN = "libXpm" @@ -194,9 +219,12 @@ FILES_sxpm = "${bindir}/sxpm" package as standard we prepend the PACKAGES variable so additional package names are added to the start of list. The - extra FILES_* + extra FILES_* variables then contain information to specify which files and - directories goes into which package. + directories goes into which package. Files included by earlier + package are skipped by latter packages, and thus main + PN will not include + above listed files
@@ -208,12 +236,15 @@ FILES_sxpm = "${bindir}/sxpm" a pkg_postinst_PACKAGENAME() function to the .bb file where PACKAGENAME is the name of the package to attach - the postinst script to. A post-installation function has the following structure: + the postinst script to. Normally PN can be used which expands + to PACKAGENAME automatically. A post-installation function has the + following structure: pkg_postinst_PACKAGENAME () { -#!/bin/sh -e -# Commands to carry out + #!/bin/sh -e + # Commands to carry out } @@ -234,12 +265,12 @@ pkg_postinst_PACKAGENAME () { pkg_postinst_PACKAGENAME () { -#!/bin/sh -e -if [ x"$D" = "x" ]; then -# Actions to carry out on the device go here -else -exit 1 -fi + #!/bin/sh -e + if [ x"$D" = "x" ]; then + # Actions to carry out on the device go here + else + exit 1 + fi } @@ -349,7 +380,7 @@ RRECOMMENDS_task-custom-tools = "\ - In this example, two tasks packages are created, task-custom-apps and + In this example, two task packages are created, task-custom-apps and task-custom-tools with the dependencies and recommended package dependencies listed. To build an image using these task packages, you would then add "task-custom-apps" and/or "task-custom-tools" to variable is for distribution maintainers this method does not make adding packages as simple as a custom .bb file. Using - this method, a few packages will need to be recreated - and the the image built. + this method, a few packages will need to be recreated if they have been + created before and then the image is rebuilt. -bitbake -cclean task-boot task-base task-poky +bitbake -c clean task-boot task-base task-poky bitbake poky-image-sato @@ -410,7 +442,7 @@ bitbake poky-image-sato DISTRO_EXTRA_RDEPENDS variable. There is no need to build them by hand as Poky images depend on the packages they contain so - dependencies will be built automatically. For this reason we don't use the + dependencies will be built automatically when building the image. For this reason we don't use the "rebuild" task in this case since "rebuild" does not care about dependencies - it only rebuilds the specified package. @@ -451,7 +483,8 @@ bitbake poky-image-sato (e.g. "zImage") and IMAGE_FSTYPES (e.g. "tar.gz jffs2") might also be needed. Full details on what these variables do and the meaning of - their contents is available through the links. + their contents is available through the links. There're lots of existing + machine .conf files which can be easily leveraged from meta/conf/machine/. @@ -461,10 +494,10 @@ bitbake poky-image-sato Poky needs to be able to build a kernel for the machine. You need to either create a new kernel recipe for this machine or extend an existing recipe. There are plenty of kernel examples in the - packages/linux directory which can be used as references. + meta/recipes-kernel/linux directory which can be used as references. - If creating a new recipe the "normal" recipe writing rules apply + If creating a new recipe the "normal" recipe writing rules apply for setting up a SRC_URI including any patches and setting S to point at the source @@ -481,8 +514,11 @@ bitbake poky-image-sato machine's defconfig files in a given kernel, possibly listing it in the SRC_URI and adding the machine to the expression in COMPATIBLE_MACHINE - . + : + +COMPATIBLE_MACHINE = '(qemux86|qemumips)' +
@@ -502,8 +538,21 @@ bitbake poky-image-sato under meta/packages/formfactor/files/MACHINENAME/ where MACHINENAME is the name for which this infomation applies. For information about the settings available and the defaults, please see - meta/packages/formfactor/files/config. + meta/packages/formfactor/files/config. Below is one + example for qemuarm: + +HAVE_TOUCHSCREEN=1 +HAVE_KEYBOARD=1 + +DISPLAY_CAN_ROTATE=0 +DISPLAY_ORIENTATION=0 +#DISPLAY_WIDTH_PIXELS=640 +#DISPLAY_HEIGHT_PIXELS=480 +#DISPLAY_BPP=16 +DISPLAY_DPI=150 +DISPLAY_SUBPIXEL_ORDER=vrgb +
@@ -536,11 +585,13 @@ bitbake poky-image-sato - The Poky tree includes two additional layers which demonstrate - this functionality, meta-moblin and meta-extras. - The meta-extras repostory is not enabled by default but enabling - it is as easy as adding the layers path to the BBLAYERS variable in - your bblayers.conf, this is how all layers are enabled in Poky builds: + The Poky tree includes several additional layers which demonstrate + this functionality, such as meta-moblin, meta-emenlow, meta-extras. + Default layers enabled are meta-moblin and meta-emenlow, which may + suffer from future changes. The meta-extras repostory is not enabled + by default but enabling any layer is as easy as adding the layers path + to the BBLAYERS variable in your bblayers.conf. this is how meta-extras + are enabled in Poky builds: LCONF_VERSION = "1" @@ -549,6 +600,7 @@ BBFILES ?= "" BBLAYERS = " \ /path/to/poky/meta \ /path/to/poky/meta-moblin \ + /path/to/poky/meta-emenlow \ /path/to/poky/meta-extras \ " @@ -563,23 +615,23 @@ BBLAYERS = " \ - The meta-extras layer.conf demonstrates the required syntax: + The meta-emenlow/conf/layer.conf demonstrates the required syntax: # We have a conf and classes directory, add to BBPATH -BBPATH := "${BBPATH}${LAYERDIR}" +BBPATH := "${BBPATH}:${LAYERDIR}" # We have a packages directory, add to BBFILES -BBFILES := "${BBFILES} ${LAYERDIR}/packages/*/*.bb" - -BBFILE_COLLECTIONS += "extras" -BBFILE_PATTERN_extras := "^${LAYERDIR}/" -BBFILE_PRIORITY_extras = "5" +BBFILES := "${BBFILES} ${LAYERDIR}/packages/*/*.bb \ + ${LAYERDIR}/packages/*/*.bbappend" -require conf/distro/include/poky-extras-src-revisions.inc +BBFILE_COLLECTIONS += "emenlow" +BBFILE_PATTERN_emenlow := "^${LAYERDIR}/" +BBFILE_PRIORITY_emenlow = "6" - As can be seen, the layers recipes are added to BBFILES. The + As can be seen, the layers recipes are added to + BBFILES. The BBFILE_COLLECTIONS variable is then appended to with the layer name. The BBFILE_PATTERN variable is immediately expanded with a regular expression used to match files from BBFILES into @@ -588,15 +640,17 @@ require conf/distro/include/poky-extras-src-revisions.inc priorities to the files in different layers. This is useful in situations where the same package might appear in multiple layers and allows you to choose which layer should 'win'. - Note the use of LAYERDIR with the immediate expansion operator. - LAYERDIR expands to the directory of the current layer and + Note the use of + LAYERDIR with the immediate expansion operator. + LAYERDIR + expands to the directory of the current layer and requires use of the immediate expansion operator so that Bitbake does not lazily expand the variable when it's parsing a different directory. - Extra bbclasses and configuration are added to the BBPATH + Emenlow bbclasses and configuration are added to the BBPATH environment variable. In this case, the first file with the matching name found in BBPATH is the one that is used, just like the PATH variable for binaries. It is therefore recommended @@ -630,9 +684,19 @@ require conf/distro/include/poky-extras-src-revisions.inc summarises the change and starts with the name of any package affected work well. Not all changes are to specific packages so the prefix could also be a machine name or class name instead. If a change needs a longer - description this should follow the summary. + description this should follow the summary: + + bitbake/data.py: Add emit_func() and generate_dependencies() functions + + These functions allow generation of dependency data between funcitons and + variables allowing moves to be made towards generating checksums and allowing + use of the dependency information in other parts of bitbake. + + Signed-off-by: Richard Purdie rpurdie@linux.intel.com + + Any commit should be self contained in that it should leave the metadata in a consistent state, buildable before and after the @@ -655,7 +719,7 @@ require conf/distro/include/poky-extras-src-revisions.inc it easy to miss incrementing it when updating the recipe. When upgrading the version of a package (PV), the PR variable should be removed. + linkend='var-PR'>PR variable should be reset to "r0". @@ -675,7 +739,7 @@ require conf/distro/include/poky-extras-src-revisions.inc the repository and don't have to remember to rebuild any sections. The second is to ensure that target users are able to upgrade their devices via their package manager such as with the - opkg update;opkg upgrade commands (or similar for + opkg upgrade commands (or similar for dpkg/apt or rpm based systems). The aim is to ensure Poky has upgradable packages in all cases. @@ -708,6 +772,8 @@ require conf/distro/include/poky-extras-src-revisions.inc are builds that build everything from the ground up and test everything. They usually happen at preset times such as at night when the machine load isn't high from the incremental builds. + poky autobuilder + is an example implementation with buildrot. @@ -783,11 +849,14 @@ src/gz beagleboard http://www.mysite.com/somedir/deploy/ipk/beagleboard -bitbake --cmd compile --force NAME_OF_PACKAGE +bitbake -c compile -f NAME_OF_PACKAGE - Other tasks may also be called this way. + "-f" or "--force" is used to force re-execution of the specified task. + Other tasks may also be called this way. But note that all the modifications + in WORKDIR + are gone once you executes "-c clean" for a pacakge.
@@ -840,10 +909,11 @@ SRC_URI += "file://NAME-OF-PATCH.patch"
- Configuring the LIC_FILES_CHKSUM variable + Track license change - The changes in the license text inside source code files is tracked - using the LIC_FILES_CHKSUM metadata variable. + The license of one upstream project may change in the future, and Poky provides + one mechanism to track such license change - + LIC_FILES_CHKSUM variable.
@@ -855,6 +925,26 @@ LIC_FILES_CHKSUM = "file://COPYING; md5=xxxx \ file://licfile2.txt; endline=50;md5=zzzz \ ..." + + + S is the default directory + for searching files listed in + LIC_FILES_CHKSUM. Relative path could be used too: + + + +LIC_FILES_CHKSUM = "file://src/ls.c;startline=5;endline=16;\ + md5=bb14ed3c4cda583abc85401304b5cd4e" +LIC_FILES_CHKSUM = "file://../license.html;md5=5c94767cedb5d6987c902ac850ded2c6" + + + + The first line locates a file in + S/src/ls.c, and the second line refers to a file in + WORKDIR, which is the parent + of S + +
@@ -873,12 +963,12 @@ to specify "beginline" and "endline" parameters. The "md5" parameter stores the md5 checksum of the license text. So if -the license text changes in any way from a file, then it's md5 sum will differ and will not +the license text changes in any way from a file, then its md5 sum will differ and will not match with the previously stored md5 checksum. This mismatch will trigger build failure, notifying developer about the license text md5 mismatch, and allowing the developer to review the license text changes. Also note that if md5 checksum is not matched while building, the correct md5 checksum is printed in the build -log. +log which can be easily copied to .bb file. There 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. 1. If you specify empty or invalid "md5" parameter; then while building the package, bitbake will give md5 not matched error, and also show the correct -"md5" parameter value in the build log +"md5" parameter value both on the screen and in the build log 2. If the whole file contains only license text, then there is no need to @@ -901,22 +991,23 @@ specify "beginline" and "endline" parameters.
- Configuring the DISTRO_PN_ALIAS variable + Handle package name alias -Sometimes the names of the same packages are different in different -linux distributions; and that can becomes an issue for the distro_check -task to check if the given recipe package exists in other linux distros. -This issue is avoided by defining per distro recipe name alias: -DISTRO_PN_ALIAS +Poky implements a distro_check task which automatically connects to major distributions +and checks whether they contains same package. Sometimes the same package has different +names in different distributions, which results in a mismatch from distro_check task +This can be solved by defining per distro recipe name alias - +DISTRO_PN_ALIAS
Specifying the DISTRO_PN_ALIAS variable -DISTRO_PN_ALIAS_pn = "distro1=package_name_alias1 distro2=package_name_alias2 \ - distro3=package_name_alias3 \ - ..." +DISTRO_PN_ALIAS_pn-PACKAGENAME = "distro1=package_name_alias1 \ + distro2=package_name_alias2 \ + distro3=package_name_alias3 \ + ..." Use space as the delimiter if there're multiple distro aliases -- cgit v1.2.3