From a8108a2f178df40e6acd286a84a63f6a9d5d30a9 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Fri, 3 Feb 2012 16:13:09 -0600 Subject: documentation: File swap I am moving the "extended.xml" file from the YP Reference Manual to the YP Development Manual. This will be the basis for a common tasks chapter that talks about common things developers do. (From yocto-docs rev: 874b3a399c69e5eabf5001a5df5a3064a6d1f0ec) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- .../dev-manual/dev-manual-common-tasks.xml | 1316 ++++++++++++++++++++ 1 file changed, 1316 insertions(+) create mode 100644 documentation/dev-manual/dev-manual-common-tasks.xml (limited to 'documentation/dev-manual') diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml new file mode 100644 index 0000000000..4fef075360 --- /dev/null +++ b/documentation/dev-manual/dev-manual-common-tasks.xml @@ -0,0 +1,1316 @@ + + + + +Common Tasks + + This chapter describes standard tasks such as adding new + software packages, extending or customizing images or porting the Yocto Project to + new hardware (adding a new machine). + The chapter also describes ways to modify package source code, combine multiple + versions of library files into a single image, and handle a package name alias. + Finally, the chapter contains advice about how to make changes to the + Yocto Project to achieve the best results. + + +
+ Adding a Package + + + To add a package into the Yocto Project you need to write a recipe for it. + Writing a recipe means creating a .bb file that sets some + variables. + For information on variables that are useful for recipes and for information about recipe naming + issues, see the + Required section for recipe variables. + + + + Before writing a recipe from scratch, it is often useful to check + whether someone else has written one already. + OpenEmbedded is a good place to look as it has a wider scope and range of packages. + Because the Yocto Project aims to be compatible with OpenEmbedded, most recipes + you find there should work in Yocto Project. + + + + For new packages, the simplest way to add a recipe is to base it on a similar + pre-existing recipe. + The sections that follow provide some examples that show how to add standard + types of packages. + + +
+ Single .c File Package (Hello World!) + + + Building an application from a single file that is stored locally (e.g. under + files/) requires a recipe that has the file listed in + the SRC_URI variable. + Additionally, you need to manually write the do_compile and + do_install tasks. + The S variable defines the + directory containing the source code, which is set to + WORKDIR in this case - the directory BitBake uses for the build. + + DESCRIPTION = "Simple helloworld application" + SECTION = "examples" + LICENSE = "MIT" + LIC_FILES_CHKSUM = "file://${COMMON_LICENSE_DIR}/MIT;md5=0835ade698e0bcf8506ecda2f7b4f302" + PR = "r0" + + SRC_URI = "file://helloworld.c" + + S = "${WORKDIR}" + + do_compile() { + ${CC} helloworld.c -o helloworld + } + + do_install() { + install -d ${D}${bindir} + install -m 0755 helloworld ${D}${bindir} + } + + + + + By default, the helloworld, helloworld-dbg, + and helloworld-dev packages are built. + For information on how to customize the packaging process, see the + "Splitting an Application + into Multiple Packages" section. + +
+ +
+ Autotooled Package + + Applications that use Autotools such as autoconf and + automake require a recipe that has a source archive listed in + SRC_URI and + also inherits Autotools, which instructs BitBake to use the + autotools.bbclass file, which contains the definitions of all the steps + needed to build an Autotool-based application. + The result of the build is automatically packaged. + And, if the application uses NLS for localization, packages with local information are + generated (one package per language). + Following is one example: (hello_2.3.bb) + + DESCRIPTION = "GNU Helloworld application" + SECTION = "examples" + LICENSE = "GPLv2+" + LIC_FILES_CHKSUM = "file://COPYING;md5=751419260aa954499f7abaabaa882bbe" + PR = "r0" + + SRC_URI = "${GNU_MIRROR}/hello/hello-${PV}.tar.gz" + + inherit autotools gettext + + + + + The variable LIC_FILES_CHKSUM + is used to track source license changes as described in the + Track License Change + section. + You can quickly create Autotool-based recipes in a manner similar to the previous example. + +
+ +
+ Makefile-Based Package + + + Applications that use GNU make also require a recipe that has + the source archive listed in SRC_URI. + You do not need to add a do_compile step since by default BitBake + starts the make command to compile the application. + If you need additional make options you should store them in the + EXTRA_OEMAKE variable. + BitBake passes these options into the make GNU invocation. + Note that a do_install task is still required. + Otherwise BitBake runs an empty do_install task by default. + + + + Some applications might require extra parameters to be passed to the compiler. + For example, the application might need an additional header path. + You can accomplish this by adding to the CFLAGS + variable. + The following example shows this: + + CFLAGS_prepend = "-I ${S}/include " + + + + + In the following example, mtd-utils is a makefile-based package: + + DESCRIPTION = "Tools for managing memory technology devices." + SECTION = "base" + DEPENDS = "zlib lzo e2fsprogs util-linux" + HOMEPAGE = "http://www.linux-mtd.infradead.org/" + LICENSE = "GPLv2" + LIC_FILES_CHKSUM = "file://COPYING;md5=0636e73ff0215e8d672dc4c32c317bb3 \ + file://include/common.h;beginline=1;endline=17;md5=ba05b07912a44ea2bf81ce409380049c" + + SRC_URI = "git://git.infradead.org/mtd-utils.git;protocol=git;tag=v${PV}" + + S = "${WORKDIR}/git/" + + 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 + } + + +
+ +
+ Splitting an Application into Multiple Packages + + + You can use the variables PACKAGES and + FILES to split an application into + multiple packages. + + + + Following is an example that uses the libXpm recipe. + By default, this recipe generates a single package that contains the library along + with a few binaries. + You can modify the recipe to split the binaries into separate packages: + + require xorg-lib-common.inc + + DESCRIPTION = "X11 Pixmap library" + LICENSE = "X-BSD" + LIC_FILES_CHKSUM = "file://COPYING;md5=3e07763d16963c3af12db271a31abaa5" + DEPENDS += "libxext libsm libxt" + PR = "r3" + PE = "1" + + XORG_PN = "libXpm" + + PACKAGES =+ "sxpm cxpm" + FILES_cxpm = "${bindir}/cxpm" + FILES_sxpm = "${bindir}/sxpm" + + + + + In the previous example, we want to ship the sxpm + and cxpm binaries in separate packages. + Since bindir would be packaged into the main + PN + package by default, we prepend the PACKAGES + variable so additional package names are added to the start of list. + This results in the extra FILES_* + variables then containing information that define which files and + directories go into which packages. + Files included by earlier packages are skipped by latter packages. + Thus, the main PN package + does not include the above listed files. + +
+ +
+ Including Static Library Files + + + If you are building a library and the library offers static linking, you can control + which static library files (*.a files) get included in the + built library. + + + + The PACKAGES and FILES_* variables in the + meta/conf/bitbake.conf configuration file define how files installed + by the do_install task are packaged. + By default, the PACKAGES variable contains + ${PN}-staticdev, which includes all static library files. + + Previously released versions of the Yocto Project defined the static library files + through ${PN}-dev. + + Following, is part of the BitBake configuration file. + You can see where the static library files are defined: + + PACKAGES = "${PN}-dbg ${PN} ${PN}-doc ${PN}-dev ${PN}-staticdev ${PN}-locale" + PACKAGES_DYNAMIC = "${PN}-locale-*" + FILES = "" + + FILES_${PN} = "${bindir}/* ${sbindir}/* ${libexecdir}/* ${libdir}/lib*${SOLIBS} \ + ${sysconfdir} ${sharedstatedir} ${localstatedir} \ + ${base_bindir}/* ${base_sbindir}/* \ + ${base_libdir}/*${SOLIBS} \ + ${datadir}/${BPN} ${libdir}/${BPN}/* \ + ${datadir}/pixmaps ${datadir}/applications \ + ${datadir}/idl ${datadir}/omf ${datadir}/sounds \ + ${libdir}/bonobo/servers" + + FILES_${PN}-doc = "${docdir} ${mandir} ${infodir} ${datadir}/gtk-doc \ + ${datadir}/gnome/help" + SECTION_${PN}-doc = "doc" + + FILES_${PN}-dev = "${includedir} ${libdir}/lib*${SOLIBSDEV} ${libdir}/*.la \ + ${libdir}/*.o ${libdir}/pkgconfig ${datadir}/pkgconfig \ + ${datadir}/aclocal ${base_libdir}/*.o" + SECTION_${PN}-dev = "devel" + ALLOW_EMPTY_${PN}-dev = "1" + RDEPENDS_${PN}-dev = "${PN} (= ${EXTENDPKGV})" + + FILES_${PN}-staticdev = "${libdir}/*.a ${base_libdir}/*.a" + SECTION_${PN}-staticdev = "devel" + RDEPENDS_${PN}-staticdev = "${PN}-dev (= ${EXTENDPKGV})" + + +
+ +
+ Post Install Scripts + + + To add a post-installation script to a package, add a pkg_postinst_PACKAGENAME() + function to the .bb file and use + PACKAGENAME as the name of the package you want to attach to the + postinst script. + Normally PN can be used, which + automatically expands to PACKAGENAME. + A post-installation function has the following structure: + + pkg_postinst_PACKAGENAME () { + #!/bin/sh -e + # Commands to carry out + } + + + + + The script defined in the post-installation function is called when the + root filesystem is created. + If the script succeeds, the package is marked as installed. + If the script fails, the package is marked as unpacked and the script is + executed when the image boots again. + + + + Sometimes it is necessary for the execution of a post-installation + script to be delayed until the first boot. + For example, the script might need to be executed on the device itself. + To delay script execution until boot time, use the following structure in the + post-installation script: + + pkg_postinst_PACKAGENAME () { + #!/bin/sh -e + if [ x"$D" = "x" ]; then + # Actions to carry out on the device go here + else + exit 1 + fi + } + + + + + The previous example delays execution until the image boots again because the + D variable points + to the directory containing the image when the root filesystem is created at build time but + is unset when executed on the first boot. + +
+
+ +
+ Customizing Images + + + You can customize Yocto Project images to satisfy particular requirements. + This section describes several methods and provides guidelines for each. + + +
+ Customizing Images Using Custom .bb Files + + + One way to get additional software into an image is to create a custom image. + The following example shows the form for the two lines you need: + + IMAGE_INSTALL = "task-core-x11-base package1 package2" + + inherit core-image + + + + + By creating a custom image, a developer has total control + over the contents of the image. + It is important to use the correct names of packages in the + IMAGE_INSTALL variable. + You must use the OpenEmbedded notation and not the Debian notation for the names + (e.g. eglibc-dev instead of libc6-dev). + + + + The other method for creating a custom image is to modify an existing image. + For example, if a developer wants to add strace into + the core-image-sato image, they can use the following recipe: + + require core-image-sato.bb + + IMAGE_INSTALL += "strace" + + +
+ +
+ Customizing Images Using Custom Tasks + + + For complex custom images, the best approach is to create a custom task package + that is used to build the image or images. + A good example of a tasks package is + meta/recipes-sato/tasks/task-poky.bb. + The PACKAGES + variable lists the task packages to build along with the complementary + -dbg and -dev packages. + For each package added, you can use + RDEPENDS + and RRECOMMENDS + entries to provide a list of packages the parent task package should contain. + Following is an example: + + DESCRIPTION = "My Custom Tasks" + + PACKAGES = "\ + task-custom-apps \ + task-custom-apps-dbg \ + task-custom-apps-dev \ + task-custom-tools \ + task-custom-tools-dbg \ + task-custom-tools-dev \ + " + + RDEPENDS_task-custom-apps = "\ + dropbear \ + portmap \ + psplash" + + RDEPENDS_task-custom-tools = "\ + oprofile \ + oprofileui-server \ + lttng-control \ + lttng-viewer" + + RRECOMMENDS_task-custom-tools = "\ + kernel-module-oprofile" + + + + + In the previous example, two task packages are created with their dependencies and their + recommended package dependencies listed: task-custom-apps, and + task-custom-tools. + To build an image using these task packages, you need to add + task-custom-apps and/or + task-custom-tools to + IMAGE_INSTALL. + For other forms of image dependencies see the other areas of this section. + +
+ +
+ Customizing Images Using Custom <filename>IMAGE_FEATURES</filename> and + <filename>EXTRA_IMAGE_FEATURES</filename> + + + Ultimately users might want to add extra image features to the set used by + Yocto Project with the + IMAGE_FEATURES + variable. + To create these features, the best reference is + meta/classes/core-image.bbclass, which shows how the + Yocto Project achieves this. + In summary, the file looks at the contents of the + IMAGE_FEATURES + variable and then maps that into a set of tasks or packages. + Based on this information the + IMAGE_INSTALL variable + is generated automatically. + Users can add extra features by extending the class or creating a custom class for use + with specialized image .bb files. + You can also add more features by configuring the + EXTRA_IMAGE_FEATURES + variable in the local.conf file found in the Yocto Project + files located in the build directory. + + + + The Yocto Project ships with two SSH servers you can use in your images: + Dropbear and OpenSSH. + Dropbear is a minimal SSH server appropriate for resource-constrained environments, + while OpenSSH is a well-known standard SSH server implementation. + By default, the core-image-sato image is configured to use Dropbear. + The core-image-basic and core-image-lsb + images both include OpenSSH. + To change these defaults, edit the IMAGE_FEATURES variable + so that it sets the image you are working with to include + ssh-server-dropbear or ssh-server-openssh. + +
+ +
+ Customizing Images Using <filename>local.conf</filename> + + + It is possible to customize image contents by using variables from your + local configuration in your conf/local.conf file. + Because it is limited to local use, this method generally only allows you to + add packages and is not as flexible as creating your own customized image. + When you add packages using local variables this way, you need to realize that + these variable changes affect all images at the same time and might not be + what you require. + + +
+ Adding Packages + + + The simplest way to add extra packages to all images is by using the + IMAGE_INSTALL + variable with the _append operator: + + IMAGE_INSTALL_append = " strace" + + Use of the syntax is important. + Specifically, the space between the quote and the package name, which is + strace in this example. + This space is required since the _append + operator does not add the space. + + + + Furthermore, you must use _append instead of the += + operator if you want to avoid ordering issues. + The reason for this is because doing so uncondtionally appends to the variable and + avoids ordering problems due to the variable being set in image recipes and + .bbclass files with operators like ?=. + Using _append ensures the operation takes affect. + + + + As shown in its simplest use, IMAGE_INSTALL_append affects + all images. + It is possible to extend the syntax so that the variable applies to a specific image only. + Here is an example: + + IMAGE_INSTALL_append_pn-core-image-minimal = " strace" + + This example adds strace to core-image-minimal + only. + + + + You can add packages using a similar approach through the + POKY_EXTRA_INSTALL + variable. + If you use this variable, only core-image-* images are affected. + +
+ +
+ Excluding Packages + + + It is possible to filter or mask out recipe and recipe append files such that + BitBake ignores them. + You can do this by providing an expression with the + BBMASK variable. + Here is an example: + + BBMASK = ".*/meta-mymachine/recipes-maybe/" + + Here, all .bb and .bbappend files + in the directory that matches the expression are ignored during the build + process. + +
+
+
+ +
+ Porting the Yocto Project to a New Machine + + + Adding a new machine to the Yocto Project is a straightforward process. + This section provides information that gives you an idea of the changes you must make. + The information covers adding machines similar to those the Yocto Project already supports. + Although well within the capabilities of the Yocto Project, adding a totally new architecture + might require + changes to gcc/eglibc and to the site information, which is + beyond the scope of this manual. + + + + For a complete example that shows how to add a new machine to the Yocto Project, + see the + + BSP Development Example in Appendix A of + + The Yocto Project Development Manual. + + +
+ Adding the Machine Configuration File + + + To add a machine configuration you need to add a .conf file + with details of the device being added to the conf/machine/ file. + The name of the file determines the name the Yocto Project uses to reference the new machine. + + + + The most important variables to set in this file are as follows: + + + TARGET_ARCH (e.g. "arm") + + PREFERRED_PROVIDER_virtual/kernel (see below) + + MACHINE_FEATURES (e.g. "kernel26 apm screen wifi") + + + + + You might also need these variables: + + + SERIAL_CONSOLE (e.g. "115200 ttyS0") + + KERNEL_IMAGETYPE (e.g. "zImage") + + IMAGE_FSTYPES (e.g. "tar.gz jffs2") + + + + + You can find full details on these variables in the reference section. + You can leverage many existing machine .conf files from + meta/conf/machine/. + +
+ +
+ Adding a Kernel for the Machine + + + The Yocto Project 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. + You can find several kernel examples in the + Yocto Project file's meta/recipes-kernel/linux + directory that you can use as references. + + + + If you are creating a new recipe, normal recipe-writing rules apply for setting + up a SRC_URI. + Thus, you need to specify any necessary patches and set + S to point at the source code. + You need to create a configure task that configures the + unpacked kernel with a defconfig. + You can do this by using a make defconfig command or, + more commonly, by copying in a suitable defconfig file and and then running + make oldconfig. + By making use of inherit kernel and potentially some of the + linux-*.inc files, most other functionality is + centralized and the the defaults of the class normally work well. + + + + If you are extending an existing kernel, it is usually a matter of adding a + suitable defconfig file. + The file needs to be added into a location similar to defconfig files + used for other machines in a given kernel. + A possible way to do this is by listing the file in the + SRC_URI and adding the machine to the expression in + COMPATIBLE_MACHINE: + + COMPATIBLE_MACHINE = '(qemux86|qemumips)' + + +
+ +
+ Adding a Formfactor Configuration File + + + A formfactor configuration file provides information about the + target hardware for which the Yocto Project is building and information that + the Yocto Project cannot obtain from other sources such as the kernel. + Some examples of information contained in a formfactor configuration file include + framebuffer orientation, whether or not the system has a keyboard, + the positioning of the keyboard in relation to the screen, and + the screen resolution. + + + + The Yocto Project uses reasonable defaults in most cases, but if customization is + necessary you need to create a machconfig file + in the Yocto Project file's meta/recipes-bsp/formfactor/files + directory. + This directory contains directories for specific machines such as + qemuarm and qemux86. + For information about the settings available and the defaults, see the + meta/recipes-bsp/formfactor/files/config file found in the + same area. + Following is an 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 + + +
+
+ +
+ Modifying Package Source Code + + Although the Yocto Project is usually used to build software, you can use it to modify software. + + + + During a build, source is available in the + WORKDIR directory. + The actual location depends on the type of package and the architecture of the target device. + For a standard recipe not related to + MACHINE, the location is + tmp/work/PACKAGE_ARCH-poky-TARGET_OS/PN-PV-PR/. + For target device-dependent packages, you should use the MACHINE + variable instead of + PACKAGE_ARCH + in the directory name. + + + + Be sure the package recipe sets the + S variable to something + other than the standard WORKDIR/PN-PV/ value. + + + + After building a package, you can modify the package source code without problems. + The easiest way to test your changes is by calling the + compile task as shown in the following example: + + $ bitbake -c compile -f NAME_OF_PACKAGE + + + + + The -f or --force + option forces re-execution of the specified task. + You can call other tasks this way as well. + But note that all the modifications in + WORKDIR + are gone once you execute -c clean for a package. + +
+ +
+ Modifying Package Source Code with Quilt + + + By default Poky uses Quilt + to manage patches in the do_patch task. + This is a powerful tool that you can use to track all modifications to package sources. + + + + Before modifying source code, it is important to notify Quilt so it can track the changes + into the new patch file: + + $ quilt new NAME-OF-PATCH.patch + + + + + After notifying Quilt, add all modified files into that patch: + + $ quilt add file1 file2 file3 + + + + + You can now start editing. + Once you are done editing, you need to use Quilt to generate the final patch that + will contain all your modifications. + + $ quilt refresh + + + + + You can find the resulting patch file in the + patches/ subdirectory of the source + (S) directory. + For future builds, you should copy the patch into the Yocto Project metadata and add it into the + SRC_URI of a recipe. + Here is an example: + + SRC_URI += "file://NAME-OF-PATCH.patch" + + + + + Finally, don't forget to 'bump' the + PR value in the same recipe since + the resulting packages have changed. + +
+ +
+ Combining Multiple Versions of Library Files into One Image + + + The build system offers the ability to build libraries with different + target optimizations or architecture formats and combine these together + into one system image. + You can link different binaries in the image + against the different libraries as needed for specific use cases. + This feature is called "Multilib." + + + + An example would be where you have most of a system compiled in 32-bit + mode using 32-bit libraries, but you have something large, like a database + engine, that needs to be a 64-bit application and use 64-bit libraries. + Multilib allows you to get the best of both 32-bit and 64-bit libraries. + + + + While the Multilib feature is most commonly used for 32 and 64-bit differences, + the approach the build system uses facilitates different target optimizations. + You could compile some binaries to use one set of libraries and other binaries + to use other different sets of libraries. + The libraries could differ in architecture, compiler options, or other + optimizations. + + + + This section overviews the Multilib process only. + For more details on how to implement Multilib, see the + Multilib wiki + page. + + +
+ Preparing to use Multilib + + + User-specific requirements drive the Multilib feature, + Consequently, there is no one "out-of-the-box" configuration that likely + exists to meet your needs. + + + + In order to enable Multilib, you first need to ensure your recipe is + extended to support multiple libraries. + Many standard recipes are already extended and support multiple libraries. + You can check in the meta/conf/multilib.conf + configuration file in the Yocto Project files directory to see how this is + done using the BBCLASSEXTEND variable. + Eventually, all recipes will be covered and this list will be unneeded. + + + + For the most part, the Multilib class extension works automatically to + extend the package name from ${PN} to + ${MLPREFIX}${PN}, where MLPREFIX + is the particular multilib (e.g. "lib32-" or "lib64-"). + Standard variables such as DEPENDS, + RDEPENDS, RPROVIDES, + RRECOMMENDS, PACKAGES, and + PACKAGES_DYNAMIC are automatically extended by the system. + If you are extending any manual code in the recipe, you can use the + ${MLPREFIX} variable to ensure those names are extended + correctly. + This automatic extension code resides in multilib.bbclass. + +
+ +
+ Using Multilib + + + After you have set up the recipes, you need to define the actual + combination of multiple libraries you want to build. + You accomplish this through your local.conf + configuration file in the Yocto Project build directory. + An example configuration would be as follows: + + MACHINE = "qemux86-64" + require conf/multilib.conf + MULTILIBS = "multilib:lib32" + DEFAULTTUNE_virtclass-multilib-lib32 = "x86" + MULTILIB_IMAGE_INSTALL = "lib32-connman" + + This example enables an + additional library named lib32 alongside the + normal target packages. + When combining these "lib32" alternatives, the example uses "x86" for tuning. + For information on this particular tuning, see + meta/conf/machine/include/ia32/arch-ia32.inc. + + + + The example then includes lib32-connman + in all the images, which illustrates one method of including a + multiple library dependency. + You can use a normal image build to include this dependency, + for example: + + $ bitbake core-image-sato + + You can also build Multilib packages specifically with a command like this: + + $ bitbake lib32-connman + + +
+ +
+ Additional Implementation Details + + + Different packaging systems have different levels of native Multilib + support. + For the RPM Package Management System, the following implementation details + exist: + + A unique architecture is defined for the Multilib packages, + along with creating a unique deploy folder under + tmp/deploy/rpm in the Yocto + Project build directory. + For example, consider lib32 in a + qemux86-64 image. + The possible architectures in the system are "all", "qemux86_64", + "lib32_qemux86_64", and "lib32_x86". + The ${MLPREFIX} variable is stripped from + ${PN} during RPM packaging. + The naming for a normal RPM package and a Multilib RPM package in a + qemux86-64 system resolves to something similar to + bash-4.1-r2.x86_64.rpm and + bash-4.1.r2.lib32_x86.rpm, respectively. + + When installing a Multilib image, the RPM backend first + installs the base image and then installs the Multilib libraries. + + The build system relies on RPM to resolve the identical files in the + two (or more) Multilib packages. + + + + + For the IPK Package Management System, the following implementation details exist: + + The ${MLPREFIX} is not stripped from + ${PN} during IPK packaging. + The naming for a normal RPM package and a Multilib IPK package in a + qemux86-64 system resolves to something like + bash_4.1-r2.x86_64.ipk and + lib32-bash_4.1-rw_x86.ipk, respectively. + + The IPK deploy folder is not modified with + ${MLPREFIX} because packages with and without + the Multilib feature can exist in the same folder due to the + ${PN} differences. + IPK defines a sanity check for Multilib installation + using certain rules for file comparison, overridden, etc. + + + +
+
+ +
+ Handling a Package Name Alias + + Sometimes a package name you are using might exist under an alias or as a similarly named + package in a different distribution. + The Yocto Project implements a distro_check + task that automatically connects to major distributions + and checks for these situations. + If the package exists under a different name in a different distribution, you get a + distro_check mismatch. + You can resolve this problem by defining a per-distro recipe name alias using the + DISTRO_PN_ALIAS variable. + + + + Following is an example that shows how you specify the DISTRO_PN_ALIAS + variable: + + DISTRO_PN_ALIAS_pn-PACKAGENAME = "distro1=package_name_alias1 \ + distro2=package_name_alias2 \ + distro3=package_name_alias3 \ + ..." + + + + + If you have more than one distribution alias, separate them with a space. + Note that the Yocto Project currently automatically checks the + Fedora, OpenSuSE, Debian, Ubuntu, + and Mandriva distributions for source package recipes without having to specify them + using the DISTRO_PN_ALIAS variable. + For example, the following command generates a report that lists the Linux distributions + that include the sources for each of the Yocto Project recipes. + + $ bitbake world -f -c distro_check + + The results are stored in the build/tmp/log/distro_check-${DATETIME}.results + file found in the Yocto Project files area. + +
+ +
+ Making and Maintaining Changes + + Because the Yocto Project is extremely configurable and flexible, + we recognize that developers will want + to extend, configure or optimize it for their specific uses. + To best keep pace with future Yocto Project changes, + we recommend you make controlled changes to the Yocto Project. + + + + The Yocto Project supports a "layers" concept. + If you use layers properly, you can ease future upgrades and allow segregation + between the Yocto Project core and a given developer's changes. + The following section provides more advice on managing changes to the Yocto Project. + + +
+ BitBake Layers + + Often, developers want to extend the Yocto Project either by adding packages + or by overriding files contained within the Yocto Project to add their own + functionality. + BitBake has a powerful mechanism called + "layers", which provides a way to handle this extension in a fully + supported and non-invasive fashion. + + + + The Yocto Project files include several additional layers such as + meta-rt and meta-yocto + that demonstrate this functionality. + The meta-rt layer is not enabled by default. + However, the meta-yocto layer is. + + + + To enable a layer, you simply add the layer's path to the + BBLAYERS variable in your + bblayers.conf file, which is found in the Yocto Project file's + build directory. + The following example shows how to enable the meta-rt: + + LCONF_VERSION = "1" + + BBFILES ?= "" + BBLAYERS = " \ + /path/to/poky/meta \ + /path/to/poky/meta-yocto \ + /path/to/poky/meta-rt \ + " + + + + + BitBake parses each conf/layer.conf file for each layer in + BBLAYERS + and adds the recipes, classes and configurations contained within the layer to + the Yocto Project. + To create your own layer, independent of the Yocto Project files, + simply create a directory with a conf/layer.conf file and + add the directory to your bblayers.conf file. + + + + The meta-yocto/conf/layer.conf file demonstrates the + required syntax: + + # We have a conf and classes directory, add to BBPATH + BBPATH := "${BBPATH}:${LAYERDIR}" + + # We have a packages directory, add to BBFILES + BBFILES := "${BBFILES} ${LAYERDIR}/recipes-*/*/*.bb \ + ${LAYERDIR}/recipes-*/*/*.bbappend" + + BBFILE_COLLECTIONS += "yocto" + BBFILE_PATTERN_yocto := "^${LAYERDIR}/" + BBFILE_PRIORITY_yocto = "5" + + + + + In the previous example, the recipes for the layers are added to + BBFILES. + The BBFILE_COLLECTIONS + variable is then appended with the layer name. + The BBFILE_PATTERN variable + immediately expands with a regular expression used to match files from + BBFILES into + a particular layer, in this case by using the base pathname. + The BBFILE_PRIORITY variable + then assigns different priorities to the files in different layers. + Applying priorities is useful in situations where the same package might appear in multiple + layers and allows you to choose what layer should take precedence. + + + + Note the use of the LAYERDIR + variable with the immediate expansion operator. + The LAYERDIR variable expands to the directory of the current layer and + requires the immediate expansion operator so that BitBake does not wait to expand the variable + when it's parsing a different directory. + + + + BitBake can locate where other .bbclass and configuration files + are applied through the BBPATH environment variable. + For these cases, BitBake uses the first file with the matching name found in + BBPATH. + This is similar to the way the PATH variable is used for binaries. + We recommend, therefore, that you use unique .bbclass + and configuration file names in your custom layer. + + + + We also recommend the following: + + Store custom layers in a Git repository that uses the + meta-prvt-XXXX format. + Clone the repository alongside other meta + directories in the Yocto Project source files area. + + Following these recommendations keeps your Yocto Project files area and + its configuration entirely inside the Yocto Project's core base. + +
+ +
+ Committing Changes + + + Modifications to the Yocto Project are often managed under some kind of source + revision control system. + Because some simple practices can significantly improve usability, policy for committing changes + is important. + It helps to use a consistent documentation style when committing changes. + The Yocto Project development team has found the following practices work well: + + The first line of the commit summarizes the change and begins with the + name of the affected package or packages. + However, not all changes apply to specific packages. + Consequently, the prefix could also be a machine name or class name. + The second part of the commit (if needed) is a longer more detailed + description of the changes. + Placing a blank line between the first and second parts helps with + readability. + + + + + Following is an example commit: + + bitbake/data.py: Add emit_func() and generate_dependencies() functions + + These functions allow generation of dependency data between functions 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 richard.purdie@linuxfoundation.org + + + + + All commits should be self-contained such that they leave the + metadata in a consistent state that builds both before and after the + commit is made. + Besides being a good practice to follow, it helps ensure autobuilder test results + are valid. + +
+ +
+ Package Revision Incrementing + + + If a committed change results in changing the package output, + then the value of the + PR variable needs to be increased + (or "bumped") as part of that commit. + This means that for new recipes you must be sure to add the PR + variable and set its initial value equal to "r0". + Failing to define PR makes it easy to miss when you bump a package. + Note that you can only use integer values following the "r" in the + PR variable. + + + + If you are sharing a common .inc file with multiple recipes, + you can also use the + INC_PR variable to ensure that + the recipes sharing the .inc file are rebuilt when the + .inc file itself is changed. + The .inc file must set INC_PR + (initially to "r0"), and all recipes referring to it should set PR + to "$(INC_PR).0" initially, incrementing the last number when the recipe is changed. + If the .inc file is changed then its + INC_PR should be incremented. + + + + When upgrading the version of a package, assuming the + PV changes, + the PR variable should be reset to "r0" + (or "$(INC_PR).0" if you are using INC_PR). + + + + Usually, version increases occur only to packages. + However, if for some reason PV changes but does not + increase, you can increase the + PE variable (Package Epoch). + The PE variable defaults to "0". + + + + Version numbering strives to follow the + + Debian Version Field Policy Guidelines. + These guidelines define how versions are compared and what "increasing" a version means. + + + + There are two reasons for following the previously mentioned guidelines. + First, to ensure that when a developer updates and rebuilds, they get all the changes to + the repository and do not have to remember to rebuild any sections. + Second, to ensure that target users are able to upgrade their + devices using package manager commands such as opkg upgrade + (or similar commands for dpkg/apt or rpm-based systems). + + + + The goal is to ensure the Yocto Project has packages that can be upgraded in all cases. + +
+ +
+ Using The Yocto Project in a Team Environment + + + It might not be immediately clear how you can use the Yocto Project in a team environment, + or scale it for a large team of developers. + The specifics of any situation determine the best solution. + Granted that the Yocto Project offers immense flexibility regarding this, practices do exist + that experience has shown work well. + + + + The core component of any development effort with the Yocto Project is often an + automated build and testing framework along with an image generation process. + You can use these core components to check that the metadata can be built, + highlight when commits break the build, and provide up-to-date images that + allow developers to test the end result and use it as a base platform for further + development. + Experience shows that buildbot is a good fit for this role. + What works well is to configure buildbot to make two types of builds: + incremental and full (from scratch). + See the buildbot for the + Yocto Project for an example implementation that uses buildbot. + + + + You can tie incremental builds to a commit hook that triggers the build + each time a commit is made to the metadata. + This practice results in useful acid tests that determine whether a given commit + breaks the build in some serious way. + Associating a build to a commit can catch a lot of simple errors. + Furthermore, the tests are fast so developers can get quick feedback on changes. + + + + Full builds build and test everything from the ground up. + These types of builds usually happen at predetermined times like during the + night when the machine load is low. + + + + Most teams have many pieces of software undergoing active development at any given time. + You can derive large benefits by putting these pieces under the control of a source + control system that is compatible with the Yocto Project (i.e. Git or Subversion (SVN). + You can then set the autobuilder to pull the latest revisions of the packages + and test the latest commits by the builds. + This practice quickly highlights issues. + The Yocto Project easily supports testing configurations that use both a + stable known good revision and a floating revision. + The Yocto Project can also take just the changes from specific source control branches. + This capability allows you to track and test specific changes. + + + + Perhaps the hardest part of setting this up is defining the software project or + the Yocto Project metadata policies that surround the different source control systems. + Of course circumstances will be different in each case. + However, this situation reveals one of the Yocto Project's advantages - + the system itself does not + force any particular policy on users, unlike a lot of build systems. + The system allows the best policies to be chosen for the given circumstances. + +
+ +
+ Updating Existing Images + + + Often, rather than re-flashing a new image, you might wish to install updated + packages into an existing running system. + You can do this by first sharing the tmp/deploy/ipk/ directory + through a web server and then by changing /etc/opkg/base-feeds.conf + to point at the shared server. + Following is an example: + + $ src/gz all http://www.mysite.com/somedir/deploy/ipk/all + $ src/gz armv7a http://www.mysite.com/somedir/deploy/ipk/armv7a + $ src/gz beagleboard http://www.mysite.com/somedir/deploy/ipk/beagleboard + + +
+
+ + + + -- cgit v1.2.3-54-g00ecf