Yocto Project Application Developer's Guide

To run the ADT Installer, you need to get the ADT Installer tarball, be sure you have the necessary host development packages that support the ADT Installer, and then run the ADT Installer Script.

For a list of the host packages needed to support ADT installation and use, see the "ADT Installer Extras" lists in the "Required Packages for the Host Development System" section of the Yocto Project Reference Manual.

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

     $ cd adt-installer
     $ ./adt_installer
                

If you want to simply install a cross-toolchain by hand, you can do so by running the toolchain installer. The installer includes the pre-built cross-toolchain, the runqemu script, and support files. If you use this method to install the cross-toolchain, you might still need to install the target sysroot by installing and extracting it separately. For information on how to install the sysroot, see the "Extracting the Root Filesystem" section.

Follow these steps:

A final way of making the cross-toolchain available is to use BitBake to generate the toolchain within an existing Build Directory. This method does not install the toolchain into the default /opt directory. As with the previous method, if you need to install the target sysroot, you must do that separately as well.

Follow these steps to generate the toolchain into the Build Directory:

To get the kernel and filesystem images, you either have to build them or download pre-built versions. For an example of how to build these images, see the "Buiding Images" section of the Yocto Project Quick Start. For an example of downloading pre-build versions, see the "Example Using Pre-Built Binaries and QEMU" section.

The Yocto Project ships basic kernel and filesystem images for several architectures (x86, x86-64, mips, powerpc, and arm) that you can use unaltered in the QEMU emulator. These kernel images reside in the release area - http://downloads.yoctoproject.org/releases/yocto/yocto-2.0.3/machines and are ideal for experimentation using Yocto Project. For information on the image types you can build using the OpenEmbedded build system, see the "Images" chapter in the Yocto Project Reference Manual.

If you are planning on developing against your image and you are not building or using one of the Yocto Project development images (e.g. core-image-*-dev), you must be sure to include the development packages as part of your image recipe.

If you plan on remotely deploying and debugging your application from within the Eclipse IDE, you must have an image that contains the Yocto Target Communication Framework (TCF) agent (tcf-agent). You can do this by including the eclipse-debug image feature.

To include the eclipse-debug image feature, modify your local.conf file in the Build Directory so that the EXTRA_IMAGE_FEATURES variable includes the "eclipse-debug" feature. After modifying the configuration file, you can rebuild the image. Once the image is rebuilt, the tcf-agent will be included in the image and is launched automatically after the boot.

If you install your toolchain by hand or build it using BitBake and you need a root filesystem, you need to extract it separately. If you use the ADT Installer to install the ADT, the root filesystem is automatically extracted and installed.

Here are some cases where you need to extract the root filesystem:

To extract the root filesystem, first source the cross-development environment setup script to establish necessary environment variables. If you built the toolchain in the Build Directory, you will find the toolchain environment script in the tmp directory. If you installed the toolchain by hand, the environment setup script is located in /opt/poky/2.0.3.

After sourcing the environment script, use the runqemu-extract-sdk command and provide the filesystem image.

Following is an example. The second command sets up the environment. In this case, the setup script is located in the /opt/poky/2.0.3 directory. The third command extracts the root filesystem from a previously built filesystem that is located in the ~/Downloads directory. Furthermore, this command extracts the root filesystem into the qemux86-sato directory:

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

You could now point to the target sysroot at qemux86-sato.

You can download a tarball installer, which includes the pre-built toolchain, the runqemu script, and support files from the appropriate directory under http://downloads.yoctoproject.org/releases/yocto/yocto-2.0.3/toolchain/. Toolchains are available for 32-bit and 64-bit x86 development systems from the i686 and x86_64 directories, respectively. The toolchains the Yocto Project provides are based off the core-image-sato image and contain libraries appropriate for developing against that image. Each type of development system supports five or more target architectures.

The names of the tarball installer scripts are such that a string representing the host system appears first in the filename and then is immediately followed by a string representing the target architecture.

     poky-glibc-host_system-image_type-arch-toolchain-release_version.sh

     Where:
         host_system is a string representing your development system:

                    i686 or x86_64.

         image_type is a string representing the image you wish to
                develop a Software Development Toolkit (SDK) for use against.
                The Yocto Project builds toolchain installers using the
                following BitBake command:

                    bitbake core-image-sato -c populate_sdk

         arch is a string representing the tuned target architecture:

                    i586, x86_64, powerpc, mips, armv7a or armv5te

         release_version is a string representing the release number of the
                Yocto Project:

                    2.0.3, 2.0.3+snapshot
            

For example, the following toolchain installer is for a 64-bit development host system and a i586-tuned target architecture based off the SDK for core-image-sato:

     poky-glibc-x86_64-core-image-sato-i586-toolchain-2.0.3.sh
                

Toolchains are self-contained and by default are installed into /opt/poky. However, when you run the toolchain installer, you can choose an installation directory.

The following command shows how to run the installer given a toolchain tarball for a 64-bit x86 development host system and a 32-bit x86 target architecture. You must change the permissions on the toolchain installer script so that it is executable.

The example assumes the toolchain installer is located in ~/Downloads/.

     $ ~/Downloads/poky-glibc-x86_64-core-image-sato-i586-toolchain-2.0.3.sh
                

For more information on how to install tarballs, see the "Using a Cross-Toolchain Tarball" and "Using BitBake and the Build Directory" sections in the Yocto Project Application Developer's Guide.

You can download the pre-built Linux kernel suitable for running in the QEMU emulator from http://downloads.yoctoproject.org/releases/yocto/yocto-2.0.3/machines/qemu. Be sure to use the kernel that matches the architecture you want to simulate. Download areas exist for the five supported machine architectures: qemuarm, qemumips, qemuppc, qemux86, and qemux86-64.

Most kernel files have one of the following forms:

     *zImage-qemuarch.bin
     vmlinux-qemuarch.bin

     Where:
         arch is a string representing the target architecture:
                x86, x86-64, ppc, mips, or arm.
                

You can learn more about downloading a Yocto Project kernel in the "Yocto Project Kernel" bulleted item in the Yocto Project Development Manual.

You can also download the filesystem image suitable for your target architecture from http://downloads.yoctoproject.org/releases/yocto/yocto-2.0.3/machines/qemu. Again, be sure to use the filesystem that matches the architecture you want to simulate.

The filesystem image has two tarball forms: ext3 and tar. You must use the ext3 form when booting an image using the QEMU emulator. The tar form can be flattened out in your host development system and used for build purposes with the Yocto Project.

     core-image-profile-qemuarch.ext3
     core-image-profile-qemuarch.tar.bz2

     Where:
         profile is the filesystem image's profile:
                   lsb, lsb-dev, lsb-sdk, lsb-qt3, minimal, minimal-dev, sato,
                   sato-dev, or sato-sdk. For information on these types of image
                   profiles, see the "Images"
                   chapter in the Yocto Project Reference Manual.

         arch is a string representing the target architecture:
                x86, x86-64, ppc, mips, or arm.
                

Before you start the QEMU emulator, you need to set up the emulation environment. The following command form sets up the emulation environment.

     $ source /opt/poky/2.0.3/environment-setup-arch-poky-linux-if

     Where:
         arch is a string representing the target architecture:
                i586, x86_64, ppc603e, mips, or armv5te.

         if is a string representing an embedded application binary interface.
              Not all setup scripts include this string.
                

Finally, this command form invokes the QEMU emulator

     $ runqemu qemuarch kernel-image filesystem-image

     Where:
         qemuarch is a string representing the target architecture: qemux86, qemux86-64,
                    qemuppc, qemumips, or qemuarm.

         kernel-image is the architecture-specific kernel image.

         filesystem-image is the .ext3 filesystem image.

                

Continuing with the example, the following two commands setup the emulation environment and launch QEMU. This example assumes the root filesystem (.ext3 file) and the pre-built kernel image file both reside in your home directory. The kernel and filesystem are for a 32-bit target architecture.

     $ cd $HOME
     $ source /opt/poky/2.0.3/environment-setup-i586-poky-linux
     $ runqemu qemux86 bzImage-qemux86.bin \
     core-image-sato-qemux86.ext3
                

The environment in which QEMU launches varies depending on the filesystem image and on the target architecture. For example, if you source the environment for the ARM target architecture and then boot the minimal QEMU image, the emulator comes up in a new shell in command-line mode. However, if you boot the SDK image, QEMU comes up with a GUI.

Follow these steps to create a simple Autotools-based project:

For an Autotools-based project, you can use the cross-toolchain by just passing the appropriate host option to configure.sh. The host option you use is derived from the name of the environment setup script found in the directory in which you installed the cross-toolchain. For example, the host option for an ARM-based target that uses the GNU EABI is armv5te-poky-linux-gnueabi. You will notice that the name of the script is environment-setup-armv5te-poky-linux-gnueabi. Thus, the following command works to update your project and rebuild it using the appropriate cross-toolchain tools:

     $ ./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