Yocto Project Application Developer's Guide

The Cross-Development Toolchain consists of a cross-compiler, cross-linker, and cross-debugger that are used to develop user-space applications for targeted hardware. This toolchain is created either by running the ADT Installer script, a toolchain installer script, or through a Build Directory that is based on your Metadata configuration or extension for your targeted device. The cross-toolchain works with a matching target sysroot.

The matching target sysroot contains needed headers and libraries for generating binaries that run on the target architecture. The sysroot is based on the target root filesystem image that is built by the OpenEmbedded build system and uses the same Metadata configuration used to build the cross-toolchain.

The Eclipse IDE is a popular development environment and it fully supports development using the Yocto Project. When you install and configure the Eclipse Yocto Project Plug-in into the Eclipse IDE, you maximize your Yocto Project experience. Installing and configuring the Plug-in results in an environment that has extensions specifically designed to let you more easily develop software. These extensions allow for cross-compilation, deployment, and execution of your output into a QEMU emulation session. You can also perform cross-debugging and profiling. The environment also supports a suite of tools that allows you to perform remote profiling, tracing, collection of power data, collection of latency data, and collection of performance data.

For information about the application development workflow that uses the Eclipse IDE and for a detailed example of how to install and configure the Eclipse Yocto Project Plug-in, see the "Working Within Eclipse" section of the Yocto Project Development Manual.

The QEMU emulator allows you to simulate your hardware while running your application or image. QEMU is made available a number of ways:

User-space tools are included as part of the distribution. You will find these tools helpful during development. The tools include LatencyTOP, PowerTOP, OProfile, Perf, SystemTap, and Lttng-ust. These tools are common development tools for the Linux platform.

The following list describes installation methods that set up varying degrees of tool availability on your system. Regardless of the installation method you choose, you must source the cross-toolchain environment setup script before you use a toolchain. See the "Setting Up the Cross-Development Environment" section for more information.

     $ cd ~
     $ cp poky/build/tmp/deploy/sdk/adt_installer.tar.bz2 $HOME
     $ tar -xjf adt_installer.tar.bz2
                

     $ cd adt-installer
     $ ./adt_installer
                

Before you can develop using the cross-toolchain, you need to set up the cross-development environment by sourcing the toolchain's environment setup script. If you used the ADT Installer or hand-installed cross-toolchain, then you can find this script in the directory you chose for installation. For this release, the default installation directory is /opt/poky/1.6.2. If you installed the toolchain in the Build Directory, you can find the environment setup script for the toolchain in the Build Directory's tmp directory.

Be sure to run the environment setup script that matches the architecture for which you are developing. Environment setup scripts begin with the string "environment-setup" and include as part of their name the architecture. For example, the toolchain environment setup script for a 64-bit IA-based architecture installed in the default installation directory would be the following:

     /opt/poky/1.6.2/environment-setup-x86_64-poky-linux
        

You will need to have a kernel and filesystem image to boot using your hardware or the QEMU emulator. Furthermore, if you plan on booting your image using NFS or you want to use the root filesystem as the target sysroot, you need to extract the root filesystem.

     $ cd ~
     $ source /opt/poky/1.6.2/environment-setup-i586-poky-linux
     $ runqemu-extract-sdk \
        ~/Downloads/core-image-sato-sdk-qemux86-2011091411831.rootfs.tar.bz2 \
        $HOME/qemux86-sato
            

As an alternative to locating and downloading a toolchain installer, you can build the toolchain installer one of two ways if you have a Build Directory:

Remember, before using any BitBake command, you must source the build environment setup script (i.e. oe-init-build-env or oe-init-build-env-memres) located in the Source Directory and you must make sure your conf/local.conf variables are correct. In particular, you need to be sure the MACHINE variable matches the architecture for which you are building and that the SDKMACHINE variable is correctly set if you are building a toolchain designed to run on an architecture that differs from your current development host machine (i.e. the build machine).

When the bitbake command completes, the toolchain installer will be in tmp/deploy/sdk in the Build Directory.

     IMAGE_INSTALL_append = " eglibc-staticdev"
            

The OpenEmbedded build system supports the generation of sysroot files using three different Package Management Systems (PMS):

Whichever PMS you are using, you need to be sure that the PACKAGE_CLASSES variable in the conf/local.conf file is set to reflect that system. The first value you choose for the variable specifies the package file format for the root filesystem at sysroot. Additional values specify additional formats for convenience or testing. See the configuration file for details.

As an example, consider a scenario where you are using OPKG and you want to add the libglade package to the target sysroot.

First, you should generate the IPK file for the libglade package and add it into a working opkg repository. Use these commands:

     $ bitbake libglade
     $ bitbake package-index
        

Next, source the environment setup script found in the Source Directory. Follow that by setting up the installation destination to point to your sysroot as <sysroot_dir>. Finally, have an OPKG configuration file <conf_file> that corresponds to the opkg repository you have just created. The following command forms should now work:

     $ opkg-cl –f <conf_file> -o <sysroot_dir> update
     $ opkg-cl –f <cconf_file> -o <sysroot_dir> \
        --force-overwrite install libglade
     $ opkg-cl –f <cconf_file> -o <sysroot_dir> \
        --force-overwrite install libglade-dbg
     $ opkg-cl –f <conf_file> -o <sysroot_dir> \
        --force-overwrite install libglade-dev
        

Once you have a suitable cross-toolchain installed, it is very easy to develop a project outside of the OpenEmbedded build system. This section presents a simple "Helloworld" example that shows how to set up, compile, and run the project.

     $ ./configure --host=armv5te-poky-linux-gnueabi \
        --with-libtool-sysroot=<sysroot-dir>
            

     $ libtoolize --automake
     $ aclocal -I ${OECORE_NATIVE_SYSROOT}/usr/share/aclocal \
        [-I <dir_containing_your_project-specific_m4_macros>]
     $ autoconf
     $ autoheader
     $ automake -a
                

For a Makefile-based project, you use the cross-toolchain by making sure the tools are used. You can do this as follows:

     CC=arm-poky-linux-gnueabi-gcc
     LD=arm-poky-linux-gnueabi-ld
     CFLAGS=”${CFLAGS} --sysroot=<sysroot-dir>”
     CXXFLAGS=”${CXXFLAGS} --sysroot=<sysroot-dir>”