Yocto Project Software Development Kit (SDK) Developer's Guide

Welcome to the Yocto Project Software Development Kit (SDK) Developer's Guide. This manual provides information that explains how to use both the standard Yocto Project SDK and an extensible SDK to develop applications and images using the Yocto Project. Additionally, the manual also provides information on how to use the popular Eclipse™ IDE as part of your application development workflow within the SDK environment.

Prior to the 2.0 Release of the Yocto Project, application development was primarily accomplished through the use of the Application Development Toolkit (ADT) and the availability of stand-alone cross-development toolchains and other tools. With the 2.1 Release of the Yocto Project, application development has transitioned to within a more traditional SDK and extensible SDK.

A standard SDK consists of the following:

You can use the standard SDK to independently develop and test code that is destined to run on some target machine.

An extensible SDK consists of everything that the standard SDK has plus tools that allow you to easily add new applications and libraries to an image, modify the source of an existing component, test changes on the target hardware, and easily integrate an application into the OpenEmbedded build system.

SDKs are 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 and populate_sdk_ext archives.

Another feature for the SDKs is that only one set of cross-compiler 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.

The SDK development environment consists of the following:

Fundamentally, the SDK fits into the development process as follows:

The SDK is installed on any machine and can be used to develop applications, images, and kernels. An SDK can even be used by a QA Engineer or Release Engineer. The fundamental concept is that the machine that has the SDK installed does not have to be associated with the machine that has the Yocto Project installed. A developer can independently compile and test an object on their machine and then, when the object is ready for integration into an image, they can simply make it available to the machine that has the Yocto Project. Once the object is available, the image can be rebuilt using the Yocto Project to produce the modified image.

You just need to follow these general steps:

The remainder of this manual describes how to use both the standard SDK and the extensible SDK. Information also exists in appendix form that describes how you can build, install, and modify an SDK.

The Standard SDK provides a cross-development toolchain and libraries tailored to the contents of a specific image. You would use the Standard SDK if you want a more traditional toolchain experience.

The installed Standard SDK consists of several files and directories. Basically, it contains an SDK environment setup script, some configuration files, and host and target root filesystems to support usage. You can see the directory structure in the "Installed Standard SDK Directory Structure" section.

The first thing you need to do is install the SDK on your host development machine by running the *.sh installation script.

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.1/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 the image for which the SDK was built.

         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.1, 2.1+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 and using the current 2.1 snapshot:

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

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

     $ chmod +x poky-glibc-x86_64-core-image-sato-i586-toolchain-2.1.sh
            

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. The example assumes the toolchain installer is located in ~/Downloads/.

     $ ./poky-glibc-x86_64-core-image-sato-i586-toolchain-2.1.sh
     Poky (Yocto Project Reference Distro) SDK installer version 2.0
     ===============================================================
     Enter target directory for SDK (default: /opt/poky/2.1):
     You are about to install the SDK to "/opt/poky/2.1". Proceed[Y/n]? Y
     Extracting SDK.......................................................................done
     Setting it up...done
     SDK has been successfully set up and is ready to be used.
     Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g.
      $ . /opt/poky/2.1/environment-setup-i586-poky-linux
        

Again, reference the "Installed Standard SDK Directory Structure" section for more details on the resulting directory structure of the installed SDK.

Once you have the SDK installed, you must run the SDK environment setup script before you can actually use it. This setup script resides in the directory you chose when you installed the SDK. For information on where this setup script can reside, see the "Obtaining the SDK" Appendix.

Before running the script, be sure it is the one 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 tuned target architecture. For example, the command to source a setup script for an IA-based target machine using i586 tuning and located in the default SDK installation directory is as follows:

     $ source /opt/poky/2.1/environment-setup-i586-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
        

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 are subject to general make rules.

To illustrate this, consider the following four cross-toolchain environment variables:

     CC=i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.1/sysroots/i586-poky-linux
     LD=i586-poky-linux-ld --sysroot=/opt/poky/2.1/sysroots/i586-poky-linux
     CFLAGS=-O2 -pipe -g -feliminate-unused-debug-types
     CXXFLAGS=-O2 -pipe -g -feliminate-unused-debug-types
        

Now, consider the following three cases:

If you are familiar with the popular Eclipse IDE, you can use an Eclipse Yocto Plug-in to allow you to develop, deploy, and test your application all from within Eclipse. This section describes general workflow using the SDK and Eclipse and how to configure and set up Eclipse.

2.6.1. Workflow Using Eclipse™¶

The following figure and supporting list summarize the application development general workflow that employs both the SDK Eclipse.

1. Prepare the host system for the Yocto Project: See "Supported Linux Distributions" and "Required Packages for the Host Development System" sections both in the Yocto Project Reference Manual for requirements. In particular, be sure your host system has the xterm package installed.

2. Secure the Yocto Project kernel target image: You must have a target kernel image that has been built using the OpenEmbedded build system.

   Depending on whether the Yocto Project has a pre-built image that matches your target architecture and where you are going to run the image while you develop your application (QEMU or real hardware), the area from which you get the image differs.

   • Download the image from machines if your target architecture is supported and you are going to develop and test your application on actual hardware.

   • Download the image from machines/qemu if your target architecture is supported and you are going to develop and test your application using the QEMU emulator.

   • Build your image if you cannot find a pre-built image that matches your target architecture. If your target architecture is similar to a supported architecture, you can modify the kernel image before you build it. See the "Patching the Kernel" section in the Yocto Project Development manual for an example.

   For information on pre-built kernel image naming schemes for images that can run on the QEMU emulator, see the Yocto Project Software Development Kit (SDK) Developer's Guide.

3. Install the SDK: The SDK provides a target-specific cross-development toolchain, the root filesystem, the QEMU emulator, and other tools that can help you develop your application. For information on how to install the SDK, see the "Installing the SDK" section.

4. Secure the target root filesystem and the Cross-development toolchain: You need to find and download the appropriate root filesystem and the cross-development toolchain.

   You can find the tarballs for the root filesystem in the same area used for the kernel image. Depending on the type of image you are running, the root filesystem you need differs. For example, if you are developing an application that runs on an image that supports Sato, you need to get a root filesystem that supports Sato.

   You can find the cross-development toolchains at toolchains. Be sure to get the correct toolchain for your development host and your target architecture. See the "Locating Pre-Built SDK Installers" section for information and the "Installing the SDK" section for installation information.

5. Create and build your application: At this point, you need to have source files for your application. Once you have the files, you can use the Eclipse IDE to import them and build the project. If you are not using Eclipse, you need to use the cross-development tools you have installed to create the image.

6. Deploy the image with the application: If you are using the Eclipse IDE, you can deploy your image to the hardware or to QEMU through the project's preferences. If you are not using the Eclipse IDE, then you need to deploy the application to the hardware using other methods. Or, if you are using QEMU, you need to use that tool and load your image in for testing. See the "Using the Quick EMUlator (QEMU)" chapter in the Yocto Project Development Manual for information on using QEMU.

7. Test and debug the application: Once your application is deployed, you need to test it. Within the Eclipse IDE, you can use the debugging environment along with the set of installed user-space tools to debug your application. Of course, the same user-space tools are available separately if you choose not to use the Eclipse IDE.

     $ cd ~
     $ tar -xzvf ~/Downloads/eclipse-cpp-luna-SR2-linux-gtk-x86_64.tar.gz
                    

     ssh -XY user_name@remote_host_ip
                    

     export DISPLAY=:10.0
                    

Getting set up to use the extensible SDK is identical to getting set up to use the standard SDK. You still need to locate and run the installer and then run the environment setup script. See the "Installing the SDK" and the "Running the SDK Environment Setup Script" sections for general information. The following items highlight the only differences between getting set up to use the extensible SDK as compared to the standard SDK:

After installing the SDK, you need to run the SDK environment setup script. Here is the output:

     $ source environment-setup-core2-64-poky-linux
     SDK environment now set up; additionally you may now run devtool to perform development tasks.
     Run devtool --help for further details.
        

Once you run the environment setup script, you have devtool available.

The cornerstone of the extensible SDK is a command-line tool called devtool. This tool provides a number of features that help you build, test and package software within the extensible SDK, and optionally integrate it into an image built by the OpenEmbedded build system.

The devtool command line is organized similarly to Git in that it has a number of sub-commands for each function. You can run devtool --help to see all the commands.

Two devtool subcommands that provide entry-points into development are:

As with the OpenEmbedded build system, "recipes" represent software packages within devtool. When you use devtool add, a recipe is automatically created. When you use devtool modify, the specified existing recipe is used in order to determine where to get the source code and how to patch it. In both cases, an environment is set up so that when you build the recipe a source tree that is under your control is used in order to allow you to make changes to the source as desired. By default, both new recipes and the source go into a "workspace" directory under the SDK.

The remainder of this section presents the devtool add and devtool modify workflows.

The devtool add command automatically creates a recipe based on the source tree with which you provide it. Currently, the command has support for the following:

Apart from binary packages, the determination of how a source tree should be treated is automatic based on the files present within that source tree. For example, if a CMakeLists.txt file is found, then the source tree is assumed to be using CMake and is treated accordingly.

The remainder of this section covers specifics regarding how parts of the recipe are generated.

     $ devtool reset -n recipename
            

     RDEPENDS_${PN} += "dependency1 dependency2 ..."
            

     $ devtool add "npm://registry.npmjs.org;name=forever;version=0.15.1"
            

When building a recipe with devtool build the typical build progression is as follows:

For recipes in the workspace, fetching and unpacking is disabled as the source tree has already been prepared and is persistent. Each of these build steps is defined as a function, usually with a "do_" prefix. These functions are typically shell scripts but can instead be written in Python.

If you look at the contents of a recipe, you will see that the recipe does not include complete instructions for building the software. Instead, common functionality is encapsulated in classes inherited with the inherit directive, leaving the recipe to describe just the things that are specific to the software to be built. A base class exists that is implicitly inherited by all recipes and provides the functionality that most typical recipes need.

The remainder of this section presents information useful when working with recipes.

If you use the devtool deploy-target command to write a recipe's build output to the target, and you are working on an existing component of the system, then you might find yourself in a situation where you need to restore the original files that existed prior to running the devtool deploy-target command. Because the devtool deploy-target command backs up any files it overwrites, you can use the devtool undeploy-target to restore those files and remove any other files the recipe deployed. Consider the following example:

     $ devtool undeploy-target lighttpd root@192.168.7.2
        

If you have deployed multiple applications, you can remove them all at once thus restoring the target device back to its original state:

     $ devtool undeploy-target -a root@192.168.7.2
        

Information about files deployed to the target as well as any backed up files are stored on the target itself. This storage of course requires some additional space on the target machine.

The extensible SDK typically only comes with a small number of tools and libraries out of the box. If you have a minimal SDK, then it starts mostly empty and is populated on-demand. However, sometimes you will need to explicitly install extra items into the SDK. If you need these extra items, you can first search for the items using the devtool search command. For example, suppose you need to link to libGL but you are not sure which recipe provides it. You can use the following command to find out:

     $ devtool search libGL
     mesa                  A free implementation of the OpenGL API
        

Once you know the recipe (i.e. mesa in this example), you can install it:

     $ devtool sdk-install mesa
        

By default, the devtool sdk-install assumes the item is available in pre-built form from your SDK provider. If the item is not available and it is acceptable to build the item from source, you can add the "-s" option as follows:

     $ devtool sdk-install -s mesa
        

It is important to remember that building the item from source takes significantly longer than installing the pre-built artifact. Also, if no recipe exists for the item you want to add to the SDK, you must instead add it using the devtool add command.

If you are working with an extensible SDK that gets occasionally updated (e.g. typically when that SDK has been provided to you by another party), then you will need to manually pull down those updates to your installed SDK.

To update your installed SDK, run the following:

     $ devtool sdk-update
         

The previous command assumes your SDK provider has set the default update URL for you. If that URL has not been set, you need to specify it yourself as follows:

     $ devtool sdk-update path_to_update_directory
         

You might need to produce an SDK that contains your own custom libraries for sending to a third party (e.g., if you are a vendor with customers needing to build their own software for the target platform). If that is the case, then you can produce a derivative SDK based on the currently installed SDK fairly easily. Use these steps:

The above procedure takes the recipes added to the workspace and constructs a new SDK installer containing those recipes and the resulting binary artifacts. The recipes go into their own separate layer in the constructed derivative SDK, leaving the workspace clean and ready for users to add their own recipes.