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 Yocto Project. 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, which establishes several key environment variables, 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.8.1. 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.8.1/environment-setup-x86_64-poky-linux
        

When you run the setup script, many environment variables are defined:

     SDKTARGETSYSROOT - The path to the sysroot used for cross-compilation
     PKG_CONFIG_PATH - The path to the target pkg-config files
     CONFIG_SITE - A GNU autoconf site file preconfigured for the target
     CC - The minimal command and arguments to run the C compiler
     CXX - The minimal command and arguments to run the C++ compiler
     CPP - The minimal command and arguments to run the C preprocessor
     AS - The minimal command and arguments to run the assembler
     LD - The minimal command and arguments to run the linker
     GDB - The minimal command and arguments to run the GNU Debugger
     STRIP - The minimal command and arguments to run 'strip', which strips symbols
     RANLIB - The minimal command and arguments to run 'ranlib'
     OBJCOPY - The minimal command and arguments to run 'objcopy'
     OBJDUMP - The minimal command and arguments to run 'objdump'
     AR - The minimal command and arguments to run 'ar'
     NM - The minimal command and arguments to run 'nm'
     TARGET_PREFIX - The toolchain binary prefix for the target tools
     CROSS_COMPILE - The toolchain binary prefix for the target tools
     CONFIGURE_FLAGS - The minimal arguments for GNU configure
     CFLAGS - Suggested C flags
     CXXFLAGS - Suggested C++ flags
     LDFLAGS - Suggested linker flags when you use CC to link
     CPPFLAGS - Suggested preprocessor flags
        

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.8.1/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 if you have a Build Directory.

To build the toolchain installer and populate the SDK image, use the following command:

     $ bitbake image -c populate_sdk
        

The command results in a toolchain installer that contains the sysroot that matches your target root filesystem.

Another powerful feature is that the toolchain is completely self-contained. The binaries are linked against their own copy of libc, which results in no dependencies on the target system. To achieve this, the pointer to the dynamic loader is configured at install time since that path cannot be dynamically altered. This is the reason for a wrapper around the populate_sdk archive.

Another feature is that only one set of cross-canadian toolchain binaries are produced per architecture. This feature takes advantage of the fact that the target hardware can be passed to gcc as a set of compiler options. Those options are set up by the environment script and contained in variables such as CC and LD. This reduces the space needed for the tools. Understand, however, that a sysroot is still needed for every target since those binaries are target-specific.

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 = " glibc-staticdev"
            

You might want to use an external toolchain as part of your development. If this is the case, the fundamental steps you need to accomplish are as follows:

A good example of an external toolchain used with the Yocto Project is Mentor Graphics® Sourcery G++ Toolchain. You can see information on how to use that particular layer in the README file at http://github.com/MentorEmbedded/meta-sourcery/. You can find further information by reading about the TCMODE variable in the Yocto Project Reference Manual's variable glossary.

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 conf/local.conf 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 cross-toolchain 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 Makefile-based projects, the cross-toolchain environment variables established by running the cross-toolchain environment setup script override any settings you might have in your Makefile. For example, if you had settings such as the following in your Makefile, the environment variables defined by the script would override them:

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

Consequently, you should not set variables like CC and LD in your Makefile. For the list of variables set up by the cross-toolchain environment setup script, see the "Setting Up the Cross-Development Environment" section.