yocto: adding a package

4.3. 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 of the Yocto Project Reference Manual.

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.

4.3.1. 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.

4.3.2. 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.

4.3.3. 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=995cfe51b0a3cf32f381c140bf72b21bf91cef1b \
	     	file://add-exclusion-to-mkfs-jffs2-git-2.patch"

     S = "${WORKDIR}/git/"

     PR = "r1"

     EXTRA_OEMAKE = "'CC=${CC}' 'RANLIB=${RANLIB}' 'AR=${AR}' \
        '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
     }

     PARALLEL_MAKE = ""

     BBCLASSEXTEND = "native"
                

If your sources are available as a tarball instead of a Git repository, you will need to provide the URL to the tarball as well as an md5 or sha256 sum of the download. Here is an example:

     SRC_URI="ftp://ftp.infradead.org/pub/mtd-utils/mtd-utils-1.4.9.tar.bz2"
     SRC_URI[md5sum]="82b8e714b90674896570968f70ca778b"
                

You can generate the md5 or sha256 sums by using the md5sum or sha256sum commands with the target file as the only argument. Here is an example:

     $ md5sum mtd-utils-1.4.9.tar.bz2 
     82b8e714b90674896570968f70ca778b mtd-utils-1.4.9.tar.bz2
                

4.3.4. 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.

4.3.5. 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.

Note

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})"
                

4.3.6. 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.