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 --- documentation/poky-ref-manual/extendpoky.xml | 1316 -------------------------- 1 file changed, 1316 deletions(-) delete mode 100644 documentation/poky-ref-manual/extendpoky.xml (limited to 'documentation/poky-ref-manual') diff --git a/documentation/poky-ref-manual/extendpoky.xml b/documentation/poky-ref-manual/extendpoky.xml deleted file mode 100644 index 4fef075360..0000000000 --- a/documentation/poky-ref-manual/extendpoky.xml +++ /dev/null @@ -1,1316 +0,0 @@ - - - - -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