Poky Reference Manual

Periodically, we make releases of Poky available at http://yoctoproject.org/downloads/poky/. These releases are more stable and more rigorously tested than the nightly development images.

We make nightly builds of Poky for testing purposes and to make the latest developments available. The output from these builds is available at http://autobuilder.yoctoproject.org/. The numbers used in the builds increase for each subsequent build and can be used to reference a specific build.

Automated builds are available for "standard" Poky and for Poky SDKs and toolchains. Additionally, testing versions such as poky-bleeding can be made available as 'experimental' builds. The toolchains can be used either as external standalone toolchains or can be combined with Poky as a pre-built toolchain to reduce build time. Using the external toolchains is simply a case of untarring the tarball into the root of your system (it only creates files in /opt/poky) and then enabling the option in local.conf.

Poky is available from our git repository located at git://git.yoctoproject.org/poky.git; a web interface to the repository can be accessed at http://git.yoctoproject.org/.

The 'master' is where the development work takes place and you should use this if you're interested in working with the latest cutting-edge developments. It is possible for the trunk to suffer temporary periods of instability while new features are developed. If these periods of instability are undesirable, we recommend using one of the release branches.

BitBake is the tool at the heart of Poky and is responsible for parsing the metadata, generating a list of tasks from it and then executing them. To see a list of the options BitBake supports look at 'bitbake --help'.

The most common usage for BitBake is bitbake <packagename>, where packagename is the name of the package you want to build (referred to as the 'target' in this manual). The target often equates to the first part of a .bb filename. So, to run the matchbox-desktop_1.2.3.bb file, you might type the following:

     $ bitbake matchbox-desktop
            

Several different versions of matchbox-desktop might exist. BitBake chooses the one selected by the distribution configuration. You can get more details about how BitBake chooses between different versions and providers in the 'Preferences and Providers' section.

BitBake also tries to execute any dependent tasks first. So for example, before building matchbox-desktop BitBake would build a cross compiler and glibc if they had not already been built.

The .bb files are usually referred to as 'recipes'. In general, a recipe contains information about a single piece of software such as from where to download the source patches (if any are needed), which special configuration options to apply, how to compile the source files, and how to package the compiled output.

The term 'package' can also be used to describe recipes. However, since the same word is used for the packaged output from Poky (i.e. .ipk or .deb files), this document avoids it.

Class files (.bbclass) contain information that is useful to share between metadata files. An example is the autotools class, which contains common settings for any application that autotools uses. The Reference: Classes appendix provides details about common classes and how to use them.

The configuration files (.conf) define various configuration variables that govern what Poky does. These files are split into several areas that define machine configuration options, distribution configuration options, compiler tuning options, general common configuration options and user configuration options (local.conf).

The log file for shell tasks is available in ${WORKDIR}/temp/log.do_taskname.pid. For example, the "compile" task of busybox 1.01 on the ARM spitz machine might be tmp/work/armv5te-poky-linux-gnueabi/busybox-1.01/temp/log.do_compile.1234. To see what BitBake runs to generate that log, look at the corresponding run.do_taskname.pid file located in the same directory.

Presently, the output from python tasks is sent directly to the console.

Any given package consists of a set of tasks. In most cases the series is: fetch, unpack, patch, configure, compile, install, package, package_write and build. The default task is "build" and any tasks on which it depends build first - hence, the standard BitBake behaviour. Some tasks exist, such as devshell, that are not part of the default build chain. If you wish to run a task that is not part of the default build chain you can use the "-c" option in BitBake as follows:

     $ bitbake matchbox-desktop -c devshell
            

If you wish to rerun a task use the force option "-f". For example, the following sequence forces recompilation after changing files in the working directory.

     $ bitbake matchbox-desktop
     [make some changes to the source code in the WORKDIR]
     $ bitbake matchbox-desktop -c compile -f
     $ bitbake matchbox-desktop
            

This sequence first builds matchbox-desktop and then recompiles it. The last command reruns all tasks, basically the packaging tasks, after the compile. BitBake recognizes that the "compile" task was rerun and therefore understands that the other tasks also need to be run again.

You can view a list of tasks in a given package by running the "listtasks" task. For example:

     $ bitbake matchbox-desktop -c
            

The results are in the file ${WORKDIR}/temp/log.do_listtasks.

Sometimes it can be hard to see why BitBake wants to build some other packages before a given package you've specified. The bitbake -g targetname command creates the depends.dot and task-depends.dot files in the current directory. These files show the package and task dependencies and are useful for debugging problems. You can use the bitbake -g -u depexp targetname command to display the results in a more human-readable form.

You can see debug output from BitBake by using the "-D" option. The debug output gives more information about what BitBake is doing and the reason behind it. Each "-D" option you use increases the logging level. The most common usage is -DDD.

The output from bitbake -DDD -v targetname can reveal why BitBake chose a certain version of a package or why BitBake picked a certain provider. This command could also help you in a situation where you think BitBake did something unexpected.

If you really want to build a specific .bb file, you can use the command form bitbake -b somepath/somefile.bb. This command form does not check for dependencies so you should use it only when you know its dependencies already exist. You can also specify fragments of the filename and BitBake checks for a unique match.

The "-e" option dumps the resulting environment for either the configuration (no package specified) or for a specific package when specified with the "-b" option.

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"
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 Controlling Package Content.

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 autotooled 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.2.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. You can quickly create autotool-based recipes in a manner similar to the previous example.

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"

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
}
            

You can use the variables PACKAGES and FILES to split an application into multiple packages.

Following is an example that uses the "libXpm" recipe (libxpm_3.5.7.bb). By default, the "libXpm" 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"
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.

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 rootfs is made. 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 'image' directory when the rootfs is being made at build time but is unset when executed on the first boot.

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-poky-x11-base package1 package2"

inherit poky-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. "glibc-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 "poky-image-sato", they can use the following recipe:

require poky-image-sato.bb

IMAGE_INSTALL += "strace"
            

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.

Ultimately users might want to add extra image "features" as used by Poky with the IMAGE_FEATURES variable. To create these features, the best reference is meta/classes/poky-image.bbclass, which shows how poky 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.

Poky 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, poky-image-sato is configured to use Dropbear. The poky-image-basic and poky-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.

It is possible to customize image contents by using variables used by distribution maintainers in the local.conf. This method only allows the addition of packages and is not recommended.

For example, to add the "strace" package into the image you would add this package to the local.conf file:

DISTRO_EXTRA_RDEPENDS += "strace"
            

However, since the DISTRO_EXTRA_RDEPENDS variable is for distribution maintainers, adding packages using this method is not as simple as adding them using a custom .bb file. Using the local.conf file method could result in some packages needing to be recreated. For example, if packages were previously created and the image was rebuilt then the packages would need to be recreated.

Cleaning task-* packages are required because they use the DISTRO_EXTRA_RDEPENDS variable. You do not have to build them by hand because Poky images depend on the packages they contain. This means dependencies are automatically built when the image builds. For this reason we don't use the "rebuild" task. In this case the "rebuild" task does not care about dependencies - it only rebuilds the specified package.

$ bitbake -c clean task-boot task-base task-poky
$ bitbake poky-image-sato
            

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 Poky uses to reference the new machine.

The most important variables to set in this file are TARGET_ARCH (e.g. "arm"), PREFERRED_PROVIDER_virtual/kernel (see below) and MACHINE_FEATURES (e.g. "kernel26 apm screen wifi"). You might also need other variables like SERIAL_CONSOLE (e.g. "115200 ttyS0"), KERNEL_IMAGETYPE (e.g. "zImage") and 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/.

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. You can find several kernel examples in the meta/recipes-kernel/linux directory that can be used as references.

If you are creating a new recipe, the "normal" recipe-writing rules apply for setting up a SRC_URI. This means specifying any necessary patches and setting 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)'
            

A formfactor configuration file provides information about the target hardware on which Poky is running and information that Poky 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.

Reasonable defaults are used in most cases, but if customization is necessary you need to create a machconfig file under meta/packages/formfactor/files/MACHINENAME/, where MACHINENAME is the name for which this information applies. For information about the settings available and the defaults, see meta/recipes-bsp/formfactor/files/config. 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
            

Often, people want to extend Poky either by adding packages or by overriding files contained within Poky 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 Poky tree includes several additional layers such as meta-emenlow and meta-extras that demonstrate this functionality. The meta-emenlow layer is an example layer that, by default, is enabled. However, the meta-extras repository is not enabled by default. It is easy though to enable any layer. You simply add the layer's path to the BBLAYERS variable in your bblayers.conf file. The following example shows how to enable meta-extras in the Poky build:

LCONF_VERSION = "1"

BBFILES ?= ""
BBLAYERS = " \
  /path/to/poky/meta \
  /path/to/poky/meta-emenlow \
  /path/to/poky/meta-extras \
  "
               

BitBake parses each conf/layer.conf file for each layer in BBLAYERS and adds the recipes, classes and configuration contained within the layer to Poky. To create your own layer, independent of the main Poky repository, simply create a directory with a conf/layer.conf file and add the directory to your bblayers.conf file.

The meta-emenlow/conf/layer.conf file demonstrates the required syntax:

# We have a conf and classes directory, add to BBPATH
BBPATH := "${BBPATH}:${LAYERDIR}"

# We have a recipes directory containing both .bb and .bbappend files, add to BBFILES
BBFILES := "${BBFILES} ${LAYERDIR}/recipes/*/*.bb \
             ${LAYERDIR}/recipes/*/*.bbappend"

BBFILE_COLLECTIONS += "emenlow"
BBFILE_PATTERN_emenlow := "^${LAYERDIR}/"
BBFILE_PRIORITY_emenlow = "6"
               

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:

Following these recommendations keeps your Poky tree and its configuration entirely inside POKYBASE.

Modifications to Poky 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. We have found the following style works well.

Following are suggestions for committing changes to the Poky core:

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 policy to follow, this helps ensure the autobuilder test results are valid.

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 these guidelines. First, to ensure that when a developer updates and rebuilds, they get all the changes to the repository and don't 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 Poky has upgradeable packages in all cases.

It might not be immediately clear how you can use Poky in a team environment, or scale it for a large team of developers. The specifics of any situation determine the best solution. Granted that Poky offers immense flexibility regarding this, practices do exist that experience has shown work well.

The core component of any development effort with Poky is often an automated build testing framework and 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 people 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 poky autobuilder 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. They 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 Poky (i.e. git or 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. Poky easily supports testing configurations that use both a stable known good revision and a floating revision. Poky 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 Poky metadata policies that surround the different source control systems. Of course circumstances will be different in each case. However, this situation reveals one of Poky'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.

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
            

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

The LIC_FILES_CHKSUM variable contains checksums of the license text in the recipe source code. Poky uses this to track changes in the license text of the source code files. Following is an example of LIC_FILES_CHKSUM:

LIC_FILES_CHKSUM = "file://COPYING; md5=xxxx \
                    file://licfile1.txt; beginline=5; endline=29;md5=yyyy \
                    file://licfile2.txt; endline=50;md5=zzzz \
                    ..."
            

Poky uses the S variable as the default directory used when searching files listed in LIC_FILES_CHKSUM. The previous example employs the default directory.

You can also use relative paths as shown in the following example:

LIC_FILES_CHKSUM = "file://src/ls.c;beginline=5;endline=16;\
                                    md5=bb14ed3c4cda583abc85401304b5cd4e"
LIC_FILES_CHKSUM = "file://../license.html;md5=5c94767cedb5d6987c902ac850ded2c6"
            

In this example the first line locates a file in S/src/ls.c. The second line refers to a file in WORKDIR, which is the parent of S.

As mentioned in the previous section the LIC_FILES_CHKSUM variable lists all the important files that contain the license text for the source code. Using this variable you can specify the line on which the license text starts and ends by supplying "beginline" and "endline" parameters. If you do not use the "beginline" parameter then it is assumed that the text begins on the first line of the file. Similarly, if you do not use the "endline" parameter it is assumed that the license text ends as the last line of the file.

The "md5" parameter stores the md5 checksum of the license text. If the license text changes in any way as compared to this parameter then a mis-match occurs. This mismatch triggers a build failure and notifies the developer. Notification allows the developer to review and address the license text changes. Also note that if a mis-match occurs during the build, the correct md5 checksum is placed in the build log and can be easily copied to a .bb file.

There is no limit to how many files you can specify using the LIC_FILES_CHKSUM variable. Generally, however, every project requires a few specifications for license tracking. Many projects have a "COPYING" file that stores the license information for all the source code files. This practice allow you to just track the "COPYING" file as long as it is kept up to date.

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 Poky 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 Poky recipes.

     $ bitbake world -f -c distro_check
             

The results are stored in the build/tmp/log/distro_check-${DATETIME}.results file.

meta-<bsp_name>/<bsp_license_file>
            

These optional files satisfy licensing requirements for the BSP. The type or types of files here can vary depending on the licensing requirements. For example, in the crownbay BSP all licensing requirements are handled with the COPYING.MIT file.

Licensing files can be MIT, BSD, GPLv*, and so forth. These files are recommended for the BSP but are optional and totally up to the BSP developer.

meta-<bsp_name>/README
            

This file provides information on how to boot the live images that are optionally included in the /binary directory. The README file also provides special information needed for building the image.

Technically speaking a README is optional but it is highly recommended that every BSP has one.

meta-<bsp_name>/binary/<bootable_images>
            

This optional area contains useful pre-built kernels and user-space filesystem images appropriate to the target system. This directory contains the Application Development Toolkit (ADT) and minimal live images when the BSP is has been "tar-balled" and placed on the Yocto Project website. You can use these kernels and images to get a system running and quickly get started on development tasks.

The exact types of binaries present are highly hardware-dependent. However, a README file should be present in the BSP file structure that explains how to use the kernels and images with the target hardware. If pre-built binaries are present, source code to meet licensing requirements must also be provided in some form.

meta-<bsp_name>/conf/layer.conf 
            

This file identifies the structure as a Poky layer, identifies the contents of the layer, and contains information about how Poky should use it. Generally, a standard boilerplate file such as the following works. In the following example you would replace "bsp" and "_bsp" with the actual name of the BSP (i.e. <bsp_name> from the example template).

# We have a conf directory, add to BBPATH
BBPATH := "${BBPATH}:${LAYERDIR}"

# We have a recipes directory containing .bb and .bbappend files, add to BBFILES
BBFILES := "${BBFILES} ${LAYERDIR}/recipes/*/*.bb \ ${LAYERDIR}/recipes/*/*.bbappend"

BBFILE_COLLECTIONS += "bsp"
BBFILE_PATTERN_bsp := "^${LAYERDIR}/"
BBFILE_PRIORITY_bsp = "5"
                

This file simply makes BitBake aware of the recipes and configuration directories. This file must exist so that Poky can recognize the BSP.

meta-<bsp_name>/conf/machine/*.conf
            

The machine files bind together all the information contained elsewhere in the BSP into a format that Poky can understand. If the BSP supports multiple machines, multiple machine configuration files can be present. These filenames correspond to the values to which users have set the MACHINE variable.

These files define things such as the kernel package to use (PREFERRED_PROVIDER of virtual/kernel), the hardware drivers to include in different types of images, any special software components that are needed, any bootloader information, and also any special image format requirements.

At least one machine file is required for a BSP layer. However, you can supply more than one file.

This directory could also contain shared hardware "tuning" definitions that are commonly used to pass specific optimization flags to the compiler. An example is tune-atom.inc:

BASE_PACKAGE_ARCH = "core2"
TARGET_CC_ARCH = "-m32 -march=core2 -msse3 -mtune=generic -mfpmath=sse"
                

This example defines a new package architecture called "core2" and uses the specified optimization flags, which are carefully chosen to give best performance on atom processors.

The tune file would be included by the machine definition and can be contained in the BSP or referenced from one of the standard core set of files included with Poky itself.

Both the base package architecture file and the tune file are optional for a Poky BSP layer.

meta-<bsp_name>/recipes-bsp/*
            

This optional directory contains miscellaneous recipe files for the BSP. Most notably would be the formfactor files. For example, in the crownbay BSP there is a machconfig file and a formfactor_0.0.bbappend file:

meta-crownbay/recipes-bsp/formfactor/formfactor/crownbay/machconfig
meta-crownbay/recipes-bsp/formfactor/formfactor_0.0.bbappend
                

meta-<bsp_name>/recipes-graphics/*            
            

This optional directory contains recipes for the BSP if it has special requirements for graphics support. All files that are needed for the BSP to support a display are kept here. For example, in the crownbay BSP several display support files exist:

meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-config/crownbay/xcorg.conf
meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-config_0.1.bbappend
meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-emgd-bin/.gitignore
meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-emgd-bin_1.7.99.2.bb
meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-emgd/crosscompile.patch
meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-emgd/fix_open_max_preprocessor_error.patch
meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-emgd/macro_tweak.patch
meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-emgd/nodolt.patch
meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-emgd_1.7.99.2.bb
                

meta-<bsp_name>/recipes-kernel/linux/linux-yocto_git.bbappend
            

This file appends your specific changes to the kernel you are using.

For your BSP you typically want to use an existing Poky kernel found in the Poky repository at meta/recipes-kernel/kernel. You can append your specific changes to the kernel recipe by using an append file, which is located in the meta-<bsp_name>/recipes-kernel/linux directory.

Suppose you use a BSP that uses the linux-yocto_git.bb kernel, which is the preferred kernel to use for developing a new BSP using the Yocto Project. In other words, you have selected the kernel in your <bsp_name>.conf file by adding the following statement:

PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto"
                

You would use the linux-yocto_git.bbappend file to append specific BSP settings to the kernel, thus configuring the kernel for your particular BSP.

Now take a look at the existing "crownbay" BSP. The append file used is:

meta-crownbay/recipes-kernel/linux/linux-yocto_git.bbappend
                

The file contains the following:

FILESEXTRAPATHS := "${THISDIR}/${PN}"
COMPATIBLE_MACHINE_crownbay = "crownbay"
KMACHINE_crownbay = "yocto/standard/crownbay"
                

This append file adds "crownbay" as a compatible machine, and additionally sets a Yocto Kernel-specific variable that identifies the name of the BSP branch to use in the GIT repository to find configuration information.

One thing missing in this particular BSP, which you will typically need when developing a BSP, is the kernel configuration (.config) for your BSP. When developing a BSP, you probably have a kernel configuration file or a set of kernel configuration files that, when taken together, define the kernel configuration for your BSP. You can accomplish this definition by putting the configurations in a file or a set of files inside a directory located at the same level as your append file and having the same name as the kernel. With all these conditions met simply reference those files in a SRC_URI statement in the append file.

For example, suppose you had a set of configuration options in a file called defconfig. If you put that file inside a directory named /linux-yocto and then added a SRC_URI statement such as the following to the append file, those configuration options will be picked up and applied when the kernel is built.

SRC_URI += "file://defconfig"
                

As mentioned earlier, you can group related configurations into multiple files and name them all in the SRC_URI statement as well. For example, you could group separate configurations specifically for Ethernet and graphics into their own files and add those by using a SRC_URI statement like the following in your append file:

SRC_URI += "file://defconfig \
            file://eth.cfg \
            file://gfx.cfg"
                

The FILESEXTRAPATHS variable is in boilerplate form here in order to make it easy to do that. It basically allows those configuration files to be found by the build process.

The meta-toolchain and meta-toolchain-sdk targets build tarballs that contain toolchains and libraries suitable for application development outside of Poky. For information on these targets see the Reference: Images appendix.

These tarballs unpack into the /opt/poky directory and contain a setup script (e.g. /opt/poky/environment-setup-i586-poky-linux), from which you can source to initialize a suitable environment. Sourcing these files adds the compiler, QEMU scripts, QEMU binary, a special version of pkgconfig and other useful utilities to the PATH variable. Variables to assist pkgconfig and autotools are also defined so that, for example, configure can find pre-generated test results for tests that need target hardware on which to run.

Using the toolchain with autotool-enabled packages is straightforward - just pass the appropriate host option to configure. Following is an example:

     $ ./configure --host=arm-poky-linux-gnueabi
            

For other projects it is usually a case of ensuring the cross tools are used:

     CC=arm-poky-linux-gnueabi-gcc and LD=arm-poky-linux-gnueabi-ld
            

The current release of the Yocto Project supports the Eclipse IDE plug-in to make developing software easier for the application developer. The plug-in provides capability extensions to the graphical IDE to allow for cross compilation, deployment and execution of the output in a QEMU emulation session. Support of the Eclipse plug-in also allows for cross debugging and profiling. Additionally, the Eclipse plug-in provides a suite of tools that allows the developer to perform remote profiling, tracing, collection of power data, collection of latency data and collection of performance data.

To use the Eclipse plug-in you need the Eclipse Framework (Helios 3.6.1) along with other plug-ins installed into the Eclipse IDE. Once you have your environment setup you need to configure the Eclipse plug-in. For information on how to install and configure the Eclipse plug-in, see the "Working Within Eclipse" chapter in the "Application Development Toolkit (ADT) User's Guide."

Running Poky QEMU images is covered in the Yocto Project Quick Start in the "A Quick Test Run" section.

Poky's QEMU images contain a complete native toolchain. This means you can develop applications within QEMU similar to the way you would in a normal system. Using qemux86 on an x86 machine is fast since the guest and host architectures match. On the other hand, using qemuarm can be slower but gives faithful emulation of ARM-specific issues. To speed things up, these images support using "distcc" to call a cross-compiler outside the emulated system. If "runqemu" was used to start QEMU, and "distccd" is present on the host system, any Bitbake cross-compiling toolchain available from the build system is automatically used from within QEMU simply by calling "distcc". You can accomplish this by defining the cross-compiler variable (e.g. export CC="distcc"). Alternatively, if a suitable SDK/toolchain is present in /opt/poky it is also automatically be used.

There are several options for connecting into the emulated system. QEMU provides a framebuffer interface that has standard consoles available. There is also a serial connection available that has a console to the system running on it and uses standard IP networking. The images have a dropbear ssh server running with the root password disabled to allow standard ssh and scp commands to work. The images also contain an NFS server that exports the guest's root filesystem, which allows it to be made available to the host.

Working directly in Poky is a fast and effective development technique. The idea is that you can directly edit files in WORKDIR or the source directory S and then force specific tasks to rerun in order to test the changes. An example session working on the matchbox-desktop package might look like this:

     $ bitbake matchbox-desktop
     $ sh
     $ cd tmp/work/armv5te-poky-linux-gnueabi/matchbox-desktop-2.0+svnr1708-r0/
     $ cd matchbox-desktop-2
     $ vi src/main.c
     $ exit
     $ bitbake matchbox-desktop -c compile -f
     $ bitbake matchbox-desktop
            

This example builds the package, changes into the work directory for the package, changes a file, then recompiles the package. Instead of using "sh" as it is in the example, you can also use two different terminals. However, the risk of using two terminals is that a command like "unpack" could destroy the changes you've made to the work directory. Consequently, you need to work carefully.

It is useful when making changes directly to the work directory files to do so using "quilt" as detailed in the modifying packages with quilt section. You can copy the resulting patches into the recipe directory and use them directly in the SRC_URI.

For a review of the skills used in this section see the Bitbake and Running Specific Tasks Sections.

When debugging certain commands or even when just editing packages, the 'devshell' can be a useful tool. Use a command like the following to start this tool.

     $ bitbake matchbox-desktop -c devshell
            

This command opens a terminal with a shell prompt within the Poky environment. Consequently, the following occurs:

Within this environment, you can run "configure" or "compile" commands as if they were being run by Poky itself. The working directory also automatically changes to the (S) directory. When you are finished, you just exit the shell or close the terminal window.

The default shell used by "devshell" is the gnome-terminal. You can use other forms of terminal can by setting the TERMCMD and TERMCMDRUN variables in local.conf. For examples of the other options available, see meta/conf/bitbake.conf.

An external shell is launched rather than opening directly into the original terminal window. This allows easier interaction with Bitbake's multiple threads as well as for a future client/server split. Note that "devshell" will still work over X11 forwarding or similar situations.

It is worth remembering that inside "devshell" you need to use the full compiler name such as arm-poky-linux-gnueabi-gcc instead of just gcc. The same applies to other applications such as gcc, bintuils, libtool and so forth. Poky will have setup environmental variables such as CC to assist applications, such as make, find the correct tools.

If you're working on a recipe that pulls from an external SCM it is possible to have Poky notice new changes added to the SCM and then build the latest version using them. This only works for SCMs from which it is possible to get a sensible revision number for changes. Currently it works for svn, git and bzr repositories.

To enable this behavior simply add SRCREV_pn- PN = "${AUTOREV}" to local.conf, where PN is the name of the package for which you want to enable automatic source revision updating.

First, make sure GDBSERVER is installed on the target. If not, install the package gdbserver, which needs the libthread-db1 package.

As an example, to launch GDBSERVER on the target and make it ready to "debug" a program located at /path/to/inferior, connect to the target and launch:

     $ gdbserver localhost:2345 /path/to/inferior
            

GDBSERVER should now be listening on port 2345 for debugging commands coming from a remote GDB process that is running on the host computer. Communication between GDBSERVER and the host GDB are done using TCP. To use other communication protocols please refer to the GDBSERVER documentation.

Running GDB on the host computer takes a number of stages. This section describes those stages.

 
/usr/local/poky/eabi-glibc/arm/bin/arm-poky-linux-gnueabi-gdb
                

     $ bitbake gdb-cross
                

tmp/sysroots/<host-arch>/usr/bin/<target-abi>-gdb 
                

     $ <target-abi>-gdb rootfs/usr/bin/foo
                

     $ set solib-absolute-prefix /path/to/tmp/rootfs
                

     $ target remote remote-target-ip-address:2345
                

     (gdb) break main
     (gdb) continue
                

Using OProfile you can perform all the profiling work on the target device. A simple OProfile session might look like the following:

# opcontrol --reset
# opcontrol --start --separate=lib --no-vmlinux -c 5
[do whatever is being profiled]
# opcontrol --stop
$ opreport -cl
            

In this example, the reset command clears any previously profiled data. The next command starts OProfile. The options used when starting the profiler separate dynamic library data within applications, disable kernel profiling, and enable callgraphing up to five levels deep.

After you perform your profiling tasks, the next command stops the profiler. After that you can view results with the "opreport" command with options to see the separate library symbols and callgraph information.

Callgraphing logs information about time spent in functions and about a function's calling function (parent) and called functions (children). The higher the callgraphing depth, the more accurate the results. However, higher depths also increase the logging overhead. Consequently, you should take care when setting the callgraphing depth.

For more information on using OProfile, see the OProfile online documentation at http://oprofile.sourceforge.net/docs/.

A graphical user interface for OProfile is also available. You can download and build it from the Yocto Project at http://git.yoctoproject.org/cgit.cgi/oprofileui/. If the "tools-profile" image feature is selected, all necessary binaries are installed onto the target device for OProfileUI interaction.

Even though Poky usually includes all needed patches on the target device, you might find you need other OProfile patches for recent OProfileUI features. If so, see the OProfileUI README for the most recent information.

     # opcontrol --reset
     # opcontrol --start --separate=lib --no-vmlinux -c 5
     [do whatever is being profiled]
     # opcontrol --stop
     # oparchive -o my_archive