1.. SPDX-License-Identifier: CC-BY-SA-2.0-UK 2 3Customizing Images 4****************** 5 6You can customize images to satisfy particular requirements. This 7section describes several methods and provides guidelines for each. 8 9Customizing Images Using ``local.conf`` 10======================================= 11 12Probably the easiest way to customize an image is to add a package by 13way of the ``local.conf`` configuration file. Because it is limited to 14local use, this method generally only allows you to add packages and is 15not as flexible as creating your own customized image. When you add 16packages using local variables this way, you need to realize that these 17variable changes are in effect for every build and consequently affect 18all images, which might not be what you require. 19 20To add a package to your image using the local configuration file, use 21the :term:`IMAGE_INSTALL` variable with the ``:append`` operator:: 22 23 IMAGE_INSTALL:append = " strace" 24 25Use of the syntax is important; specifically, the leading space 26after the opening quote and before the package name, which is 27``strace`` in this example. This space is required since the ``:append`` 28operator does not add the space. 29 30Furthermore, you must use ``:append`` instead of the ``+=`` operator if 31you want to avoid ordering issues. The reason for this is because doing 32so unconditionally appends to the variable and avoids ordering problems 33due to the variable being set in image recipes and ``.bbclass`` files 34with operators like ``?=``. Using ``:append`` ensures the operation 35takes effect. 36 37As shown in its simplest use, ``IMAGE_INSTALL:append`` affects all 38images. It is possible to extend the syntax so that the variable applies 39to a specific image only. Here is an example:: 40 41 IMAGE_INSTALL:append:pn-core-image-minimal = " strace" 42 43This example adds ``strace`` to the ``core-image-minimal`` image only. 44 45You can add packages using a similar approach through the 46:term:`CORE_IMAGE_EXTRA_INSTALL` variable. If you use this variable, only 47``core-image-*`` images are affected. 48 49Customizing Images Using Custom ``IMAGE_FEATURES`` and ``EXTRA_IMAGE_FEATURES`` 50=============================================================================== 51 52Another method for customizing your image is to enable or disable 53high-level image features by using the 54:term:`IMAGE_FEATURES` and 55:term:`EXTRA_IMAGE_FEATURES` 56variables. Although the functions for both variables are nearly 57equivalent, best practices dictate using :term:`IMAGE_FEATURES` from within 58a recipe and using :term:`EXTRA_IMAGE_FEATURES` from within your 59``local.conf`` file, which is found in the :term:`Build Directory`. 60 61To understand how these features work, the best reference is 62:ref:`meta/classes-recipe/image.bbclass <ref-classes-image>`. 63This class lists out the available 64:term:`IMAGE_FEATURES` of which most map to package groups while some, such 65as ``read-only-rootfs``, resolve as general configuration settings. 66 67In summary, the file looks at the contents of the :term:`IMAGE_FEATURES` 68variable and then maps or configures the feature accordingly. Based on 69this information, the build system automatically adds the appropriate 70packages or configurations to the 71:term:`IMAGE_INSTALL` variable. 72Effectively, you are enabling extra features by extending the class or 73creating a custom class for use with specialized image ``.bb`` files. 74 75Use the :term:`EXTRA_IMAGE_FEATURES` variable from within your local 76configuration file. Using a separate area from which to enable features 77with this variable helps you avoid overwriting the features in the image 78recipe that are enabled with :term:`IMAGE_FEATURES`. The value of 79:term:`EXTRA_IMAGE_FEATURES` is added to :term:`IMAGE_FEATURES` within 80``meta/conf/bitbake.conf``. 81 82To illustrate how you can use these variables to modify your image, 83consider an example that selects the SSH server. The Yocto Project ships 84with two SSH servers you can use with your images: Dropbear and OpenSSH. 85Dropbear is a minimal SSH server appropriate for resource-constrained 86environments, while OpenSSH is a well-known standard SSH server 87implementation. By default, the ``core-image-sato`` image is configured 88to use Dropbear. The ``core-image-full-cmdline`` and ``core-image-lsb`` 89images both include OpenSSH. The ``core-image-minimal`` image does not 90contain an SSH server. 91 92You can customize your image and change these defaults. Edit the 93:term:`IMAGE_FEATURES` variable in your recipe or use the 94:term:`EXTRA_IMAGE_FEATURES` in your ``local.conf`` file so that it 95configures the image you are working with to include 96``ssh-server-dropbear`` or ``ssh-server-openssh``. 97 98.. note:: 99 100 See the ":ref:`ref-manual/features:image features`" section in the Yocto 101 Project Reference Manual for a complete list of image features that ship 102 with the Yocto Project. 103 104Customizing Images Using Custom .bb Files 105========================================= 106 107You can also customize an image by creating a custom recipe that defines 108additional software as part of the image. The following example shows 109the form for the two lines you need:: 110 111 IMAGE_INSTALL = "packagegroup-core-x11-base package1 package2" 112 inherit core-image 113 114Defining the software using a custom recipe gives you total control over 115the contents of the image. It is important to use the correct names of 116packages in the :term:`IMAGE_INSTALL` variable. You must use the 117OpenEmbedded notation and not the Debian notation for the names (e.g. 118``glibc-dev`` instead of ``libc6-dev``). 119 120The other method for creating a custom image is to base it on an 121existing image. For example, if you want to create an image based on 122``core-image-sato`` but add the additional package ``strace`` to the 123image, copy the ``meta/recipes-sato/images/core-image-sato.bb`` to a new 124``.bb`` and add the following line to the end of the copy:: 125 126 IMAGE_INSTALL += "strace" 127 128Customizing Images Using Custom Package Groups 129============================================== 130 131For complex custom images, the best approach for customizing an image is 132to create a custom package group recipe that is used to build the image 133or images. A good example of a package group recipe is 134``meta/recipes-core/packagegroups/packagegroup-base.bb``. 135 136If you examine that recipe, you see that the :term:`PACKAGES` variable lists 137the package group packages to produce. The ``inherit packagegroup`` 138statement sets appropriate default values and automatically adds 139``-dev``, ``-dbg``, and ``-ptest`` complementary packages for each 140package specified in the :term:`PACKAGES` statement. 141 142.. note:: 143 144 The ``inherit packagegroup`` line should be located near the top of the 145 recipe, certainly before the :term:`PACKAGES` statement. 146 147For each package you specify in :term:`PACKAGES`, you can use :term:`RDEPENDS` 148and :term:`RRECOMMENDS` entries to provide a list of packages the parent 149task package should contain. You can see examples of these further down 150in the ``packagegroup-base.bb`` recipe. 151 152Here is a short, fabricated example showing the same basic pieces for a 153hypothetical packagegroup defined in ``packagegroup-custom.bb``, where 154the variable :term:`PN` is the standard way to abbreviate the reference to 155the full packagegroup name ``packagegroup-custom``:: 156 157 DESCRIPTION = "My Custom Package Groups" 158 159 inherit packagegroup 160 161 PACKAGES = "\ 162 ${PN}-apps \ 163 ${PN}-tools \ 164 " 165 166 RDEPENDS:${PN}-apps = "\ 167 dropbear \ 168 portmap \ 169 psplash" 170 171 RDEPENDS:${PN}-tools = "\ 172 oprofile \ 173 oprofileui-server \ 174 lttng-tools" 175 176 RRECOMMENDS:${PN}-tools = "\ 177 kernel-module-oprofile" 178 179In the previous example, two package group packages are created with 180their dependencies and their recommended package dependencies listed: 181``packagegroup-custom-apps``, and ``packagegroup-custom-tools``. To 182build an image using these package group packages, you need to add 183``packagegroup-custom-apps`` and/or ``packagegroup-custom-tools`` to 184:term:`IMAGE_INSTALL`. For other forms of image dependencies see the other 185areas of this section. 186 187Customizing an Image Hostname 188============================= 189 190By default, the configured hostname (i.e. ``/etc/hostname``) in an image 191is the same as the machine name. For example, if 192:term:`MACHINE` equals "qemux86", the 193configured hostname written to ``/etc/hostname`` is "qemux86". 194 195You can customize this name by altering the value of the "hostname" 196variable in the ``base-files`` recipe using either an append file or a 197configuration file. Use the following in an append file:: 198 199 hostname = "myhostname" 200 201Use the following in a configuration file:: 202 203 hostname:pn-base-files = "myhostname" 204 205Changing the default value of the variable "hostname" can be useful in 206certain situations. For example, suppose you need to do extensive 207testing on an image and you would like to easily identify the image 208under test from existing images with typical default hostnames. In this 209situation, you could change the default hostname to "testme", which 210results in all the images using the name "testme". Once testing is 211complete and you do not need to rebuild the image for test any longer, 212you can easily reset the default hostname. 213 214Another point of interest is that if you unset the variable, the image 215will have no default hostname in the filesystem. Here is an example that 216unsets the variable in a configuration file:: 217 218 hostname:pn-base-files = "" 219 220Having no default hostname in the filesystem is suitable for 221environments that use dynamic hostnames such as virtual machines. 222 223