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 Yocto Project extensible and standard SDKs to develop applications and images. 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.

All SDKs consist of the following:

Additionally an extensible SDK has 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.

You can use an SDK to independently develop and test code that is destined to run on some target machine. 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 for any given 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:

In summary, the extensible and standard SDK share many features. However, the extensible SDK has powerful development tools to help you more quickly develop applications. Following is a table that summarizes the primary differences between the standard and extensible SDK types when considering which to build:

     * Extensible SDK will contain the toolchain and debugger if SDK_EXT_TYPE is "full" or SDK_INCLUDE_TOOLCHAIN is "1", which is the default.

     ** Sysroot is managed through use of devtool.  Thus, it is less likely that you will corrupt your SDK sysroot when you try to add additional libraries.

     *** Runtime package management can be added to the standard SDK but it is not supported by default.

     **** You must build and make the shared state available to extensible SDK users for "packages" you want to enable users to install.
        

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 extensible SDK provides a cross-development toolchain and libraries tailored to the contents of a specific image. You would use the Extensible SDK if you want a toolchain experience supplemented with the powerful set of devtool commands tailored for the Yocto Project environment.

The installed extensible SDK consists of several files and directories. Basically, it contains an SDK environment setup script, some configuration files, an internal build system, and the devtool functionality.

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, the internal build system, devtool, and support files from the appropriate directory under http://downloads.yoctoproject.org/releases/yocto/yocto-2.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. An extensible SDK has the string "-ext" as part of the name.

     poky-glibc-host_system-image_type-arch-toolchain-ext-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.3, 2.3+snapshot
            

For example, the following SDK 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.3 snapshot:

     poky-glibc-x86_64-core-image-sato-i586-toolchain-ext-2.3.sh
            

The SDK and toolchains are self-contained and by default are installed into the poky_sdk folder in your home directory. You can choose to install the extensible SDK in any location when you run the installer. However, the location you choose needs to be writable for whichever users need to use the SDK, since files will need to be written under that directory during the normal course of operation.

The following command shows how to run the installer given a toolchain tarball for a 64-bit x86 development host system and a 64-bit x86 target architecture. The example assumes the SDK installer is located in ~/Downloads/.

     $ ./poky-glibc-x86_64-core-image-minimal-core2-64-toolchain-ext-2.3.sh
     Poky (Yocto Project Reference Distro) Extensible SDK installer version 2.3
     ===================================================================================
     Enter target directory for SDK (default: ~/poky_sdk):
     You are about to install the SDK to "/home/scottrif/poky_sdk". Proceed[Y/n]? Y
     Extracting SDK......................................................................done
     Setting it up...
     Extracting buildtools...
     Preparing build system...
     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.
      $ . /home/scottrif/poky_sdk/environment-setup-core2-64-poky-linux
            

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, which is either the default poky_sdk directory or the directory you chose during installation.

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. As an example, the following commands set the working directory to where the SDK was installed and then source the environment setup script. In this example, the setup script is for an IA-based target machine using i586 tuning:

     $ cd /home/scottrif/poky_sdk
     $ 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.
            

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
            

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.

Three 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, devtool modify, and devtool upgrade 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"
                

     $ devtool add https://github.com/diversario/node-ssdp
                

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.

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 as compared to the extensible SDK, which provides an internal build system and the devtool functionality.

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.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 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.3, 2.3+snapshot
            

For example, the following SDK 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.3 snapshot:

     poky-glibc-x86_64-core-image-sato-i586-toolchain-2.3.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.3.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 SDK installer is located in ~/Downloads/.

     $ ./poky-glibc-x86_64-core-image-sato-i586-toolchain-2.3.sh
     Poky (Yocto Project Reference Distro) SDK installer version 2.3
     ===============================================================
     Enter target directory for SDK (default: /opt/poky/2.3):
     You are about to install the SDK to "/opt/poky/2.3". 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.3/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.3/environment-setup-i586-poky-linux
            

When you run the setup script, the same environment variables are defined as are when you run the setup script for an extensible SDK. See the "Running the Extensible SDK Environment Setup Script" section for more information.

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_TARGET_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.3/sysroots/i586-poky-linux
     LD=i586-poky-linux-ld --sysroot=/opt/poky/2.3/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.

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

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.

   Note

   As an alternative to downloading an SDK, you can build the SDK installer. For information on building the installer, see the "Building an SDK Installer" section. Another helpful resource for building an installer is the Cookbook guide to Making an Eclipse Debug Capable Image wiki page.

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: Using the Eclipse IDE, you can deploy your image to the hardware or to QEMU through the project's preferences. You can also use Eclipse to load and test your image under QEMU. 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 supported performance enhancing Linux Tools.

     $ ssh -XY user_name@remote_host_ip
                        

     $ ssh -XY root@192.168.7.2
                        

     export DISPLAY=:10.0