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, consider an 83example that selects the SSH server. The Yocto Project ships with two SSH 84servers you can use with your images: Dropbear and OpenSSH. Dropbear is a 85minimal SSH server appropriate for resource-constrained environments, while 86OpenSSH is a well-known standard SSH server implementation. By default, the 87``core-image-sato`` image is configured to use Dropbear. The 88``core-image-full-cmdline`` image includes OpenSSH. The ``core-image-minimal`` 89image does not contain an SSH server. 90 91You can customize your image and change these defaults. Edit the 92:term:`IMAGE_FEATURES` variable in your recipe or use the 93:term:`EXTRA_IMAGE_FEATURES` in your ``local.conf`` file so that it 94configures the image you are working with to include 95``ssh-server-dropbear`` or ``ssh-server-openssh``. 96 97.. note:: 98 99 See the ":ref:`ref-manual/features:image features`" section in the Yocto 100 Project Reference Manual for a complete list of image features that ship 101 with the Yocto Project. 102 103Customizing Images Using Custom .bb Files 104========================================= 105 106You can also customize an image by creating a custom recipe that defines 107additional software as part of the image. The following example shows 108the form for the two lines you need:: 109 110 IMAGE_INSTALL = "packagegroup-core-x11-base package1 package2" 111 inherit core-image 112 113Defining the software using a custom recipe gives you total control over 114the contents of the image. It is important to use the correct names of 115packages in the :term:`IMAGE_INSTALL` variable. You must use the 116OpenEmbedded notation and not the Debian notation for the names (e.g. 117``glibc-dev`` instead of ``libc6-dev``). 118 119The other method for creating a custom image is to base it on an 120existing image. For example, if you want to create an image based on 121``core-image-sato`` but add the additional package ``strace`` to the 122image, copy the ``meta/recipes-sato/images/core-image-sato.bb`` to a new 123``.bb`` and add the following line to the end of the copy:: 124 125 IMAGE_INSTALL += "strace" 126 127Customizing Images Using Custom Package Groups 128============================================== 129 130For complex custom images, the best approach for customizing an image is 131to create a custom package group recipe that is used to build the image 132or images. A good example of a package group recipe is 133``meta/recipes-core/packagegroups/packagegroup-base.bb``. 134 135If you examine that recipe, you see that the :term:`PACKAGES` variable lists 136the package group packages to produce. The ``inherit packagegroup`` 137statement sets appropriate default values and automatically adds 138``-dev``, ``-dbg``, and ``-ptest`` complementary packages for each 139package specified in the :term:`PACKAGES` statement. 140 141.. note:: 142 143 The ``inherit packagegroup`` line should be located near the top of the 144 recipe, certainly before the :term:`PACKAGES` statement. 145 146For each package you specify in :term:`PACKAGES`, you can use :term:`RDEPENDS` 147and :term:`RRECOMMENDS` entries to provide a list of packages the parent 148task package should contain. You can see examples of these further down 149in the ``packagegroup-base.bb`` recipe. 150 151Here is a short, fabricated example showing the same basic pieces for a 152hypothetical packagegroup defined in ``packagegroup-custom.bb``, where 153the variable :term:`PN` is the standard way to abbreviate the reference to 154the full packagegroup name ``packagegroup-custom``:: 155 156 DESCRIPTION = "My Custom Package Groups" 157 158 inherit packagegroup 159 160 PACKAGES = "\ 161 ${PN}-apps \ 162 ${PN}-tools \ 163 " 164 165 RDEPENDS:${PN}-apps = "\ 166 dropbear \ 167 portmap \ 168 psplash" 169 170 RDEPENDS:${PN}-tools = "\ 171 oprofile \ 172 oprofileui-server \ 173 lttng-tools" 174 175 RRECOMMENDS:${PN}-tools = "\ 176 kernel-module-oprofile" 177 178In the previous example, two package group packages are created with 179their dependencies and their recommended package dependencies listed: 180``packagegroup-custom-apps``, and ``packagegroup-custom-tools``. To 181build an image using these package group packages, you need to add 182``packagegroup-custom-apps`` and/or ``packagegroup-custom-tools`` to 183:term:`IMAGE_INSTALL`. For other forms of image dependencies see the other 184areas of this section. 185 186Customizing an Image Hostname 187============================= 188 189By default, the configured hostname (i.e. ``/etc/hostname``) in an image 190is the same as the machine name. For example, if 191:term:`MACHINE` equals "qemux86", the 192configured hostname written to ``/etc/hostname`` is "qemux86". 193 194You can customize this name by altering the value of the "hostname" 195variable in the ``base-files`` recipe using either an append file or a 196configuration file. Use the following in an append file:: 197 198 hostname = "myhostname" 199 200Use the following in a configuration file:: 201 202 hostname:pn-base-files = "myhostname" 203 204Changing the default value of the variable "hostname" can be useful in 205certain situations. For example, suppose you need to do extensive 206testing on an image and you would like to easily identify the image 207under test from existing images with typical default hostnames. In this 208situation, you could change the default hostname to "testme", which 209results in all the images using the name "testme". Once testing is 210complete and you do not need to rebuild the image for test any longer, 211you can easily reset the default hostname. 212 213Another point of interest is that if you unset the variable, the image 214will have no default hostname in the filesystem. Here is an example that 215unsets the variable in a configuration file:: 216 217 hostname:pn-base-files = "" 218 219Having no default hostname in the filesystem is suitable for 220environments that use dynamic hostnames such as virtual machines. 221 222