yocto customizing images

4.2. Customizing Images

You can customize Yocto Project images to satisfy particular requirements. This section describes several methods and provides guidelines for each.

4.2.1. Customizing Images Using Custom .bb Files

One way to get additional software into an image is to create a custom image. The following example shows the form for the two lines you need:

     IMAGE_INSTALL = "task-core-x11-base package1 package2"

     inherit core-image
                

By creating a custom image, a developer has total control over the contents of the image. It is important to use the correct names of packages in the IMAGE_INSTALL variable. You must use the OpenEmbedded notation and not the Debian notation for the names (e.g. eglibc-dev instead of libc6-dev).

The other method for creating a custom image is to modify an existing image. For example, if a developer wants to add strace into the core-image-sato image, they can use the following recipe:

     require core-image-sato.bb

     IMAGE_INSTALL += "strace"
                

4.2.2. Customizing Images Using Custom Tasks

For complex custom images, the best approach is to create a custom task package that is used to build the image or images. A good example of a tasks package is meta/recipes-core/tasks/task-core-boot.bb The PACKAGES variable lists the task packages to build along with the complementary -dbg and -dev packages. For each package added, you can use RDEPENDS and RRECOMMENDS entries to provide a list of packages the parent task package should contain. Following is an example:

     DESCRIPTION = "My Custom Tasks"

     PACKAGES = "\
         task-custom-apps \
         task-custom-apps-dbg \
         task-custom-apps-dev \
         task-custom-tools \
         task-custom-tools-dbg \
         task-custom-tools-dev \
         "

     RDEPENDS_task-custom-apps = "\
         dropbear \
         portmap \
         psplash"

     RDEPENDS_task-custom-tools = "\
         oprofile \
         oprofileui-server \
         lttng-control \
         lttng-viewer"

     RRECOMMENDS_task-custom-tools = "\
         kernel-module-oprofile"
                

In the previous example, two task packages are created with their dependencies and their recommended package dependencies listed: task-custom-apps, and task-custom-tools. To build an image using these task packages, you need to add task-custom-apps and/or task-custom-tools to IMAGE_INSTALL. For other forms of image dependencies see the other areas of this section.

4.2.3. Customizing Images Using Custom IMAGE_FEATURES and EXTRA_IMAGE_FEATURES

Ultimately users might want to add extra image features to the set used by Yocto Project with the IMAGE_FEATURES variable. To create these features, the best reference is meta/classes/core-image.bbclass, which shows how the Yocto Project achieves this. In summary, the file looks at the contents of the IMAGE_FEATURES variable and then maps that into a set of tasks or packages. Based on this information the IMAGE_INSTALL variable is generated automatically. Users can add extra features by extending the class or creating a custom class for use with specialized image .bb files. You can also add more features by configuring the EXTRA_IMAGE_FEATURES variable in the local.conf file found in the Yocto Project files located in the build directory.

The Yocto Project ships with two SSH servers you can use in your images: Dropbear and OpenSSH. Dropbear is a minimal SSH server appropriate for resource-constrained environments, while OpenSSH is a well-known standard SSH server implementation. By default, the core-image-sato image is configured to use Dropbear. The core-image-basic and core-image-lsb images both include OpenSSH. To change these defaults, edit the IMAGE_FEATURES variable so that it sets the image you are working with to include ssh-server-dropbear or ssh-server-openssh.

4.2.4. Customizing Images Using local.conf

It is possible to customize image contents by using variables from your local configuration in your conf/local.conf file. Because it is limited to local use, this method generally only allows you to add packages and is not as flexible as creating your own customized image. When you add packages using local variables this way, you need to realize that these variable changes affect all images at the same time and might not be what you require.

The simplest way to add extra packages to all images is by using the IMAGE_INSTALL variable with the _append operator:

     IMAGE_INSTALL_append = " strace"
                

Use of the syntax is important. Specifically, the space between the quote and the package name, which is strace in this example. This space is required since the _append operator does not add the space.

Furthermore, you must use _append instead of the += operator if you want to avoid ordering issues. The reason for this is because doing so unconditionally appends to the variable and avoids ordering problems due to the variable being set in image recipes and .bbclass files with operators like ?=. Using _append ensures the operation takes affect.

As shown in its simplest use, IMAGE_INSTALL_append affects all images. It is possible to extend the syntax so that the variable applies to a specific image only. Here is an example:

     IMAGE_INSTALL_append_pn-core-image-minimal = " strace"
                

This example adds strace to core-image-minimal only.

You can add packages using a similar approach through the CORE_IMAGE_EXTRA_INSTALL variable. If you use this variable, only core-image-* images are affected.