diff options
Diffstat (limited to 'documentation/dev-manual/customizing-images.rst')
-rw-r--r-- | documentation/dev-manual/customizing-images.rst | 223 |
1 files changed, 223 insertions, 0 deletions
diff --git a/documentation/dev-manual/customizing-images.rst b/documentation/dev-manual/customizing-images.rst new file mode 100644 index 0000000000..5b18958ade --- /dev/null +++ b/documentation/dev-manual/customizing-images.rst @@ -0,0 +1,223 @@ +.. SPDX-License-Identifier: CC-BY-SA-2.0-UK + +Customizing Images +****************** + +You can customize images to satisfy particular requirements. This +section describes several methods and provides guidelines for each. + +Customizing Images Using ``local.conf`` +======================================= + +Probably the easiest way to customize an image is to add a package by +way of the ``local.conf`` configuration 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 are in effect for every build and consequently affect +all images, which might not be what you require. + +To add a package to your image using the local configuration file, use +the :term:`IMAGE_INSTALL` variable with the ``:append`` operator:: + + IMAGE_INSTALL:append = " strace" + +Use of the syntax is important; specifically, the leading space +after the opening quote and before 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 effect. + +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 the ``core-image-minimal`` image only. + +You can add packages using a similar approach through the +:term:`CORE_IMAGE_EXTRA_INSTALL` variable. If you use this variable, only +``core-image-*`` images are affected. + +Customizing Images Using Custom ``IMAGE_FEATURES`` and ``EXTRA_IMAGE_FEATURES`` +=============================================================================== + +Another method for customizing your image is to enable or disable +high-level image features by using the +:term:`IMAGE_FEATURES` and +:term:`EXTRA_IMAGE_FEATURES` +variables. Although the functions for both variables are nearly +equivalent, best practices dictate using :term:`IMAGE_FEATURES` from within +a recipe and using :term:`EXTRA_IMAGE_FEATURES` from within your +``local.conf`` file, which is found in the :term:`Build Directory`. + +To understand how these features work, the best reference is +:ref:`meta/classes-recipe/image.bbclass <ref-classes-image>`. +This class lists out the available +:term:`IMAGE_FEATURES` of which most map to package groups while some, such +as ``debug-tweaks`` and ``read-only-rootfs``, resolve as general +configuration settings. + +In summary, the file looks at the contents of the :term:`IMAGE_FEATURES` +variable and then maps or configures the feature accordingly. Based on +this information, the build system automatically adds the appropriate +packages or configurations to the +:term:`IMAGE_INSTALL` variable. +Effectively, you are enabling extra features by extending the class or +creating a custom class for use with specialized image ``.bb`` files. + +Use the :term:`EXTRA_IMAGE_FEATURES` variable from within your local +configuration file. Using a separate area from which to enable features +with this variable helps you avoid overwriting the features in the image +recipe that are enabled with :term:`IMAGE_FEATURES`. The value of +:term:`EXTRA_IMAGE_FEATURES` is added to :term:`IMAGE_FEATURES` within +``meta/conf/bitbake.conf``. + +To illustrate how you can use these variables to modify your image, +consider an example that selects the SSH server. The Yocto Project ships +with two SSH servers you can use with 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-full-cmdline`` and ``core-image-lsb`` +images both include OpenSSH. The ``core-image-minimal`` image does not +contain an SSH server. + +You can customize your image and change these defaults. Edit the +:term:`IMAGE_FEATURES` variable in your recipe or use the +:term:`EXTRA_IMAGE_FEATURES` in your ``local.conf`` file so that it +configures the image you are working with to include +``ssh-server-dropbear`` or ``ssh-server-openssh``. + +.. note:: + + See the ":ref:`ref-manual/features:image features`" section in the Yocto + Project Reference Manual for a complete list of image features that ship + with the Yocto Project. + +Customizing Images Using Custom .bb Files +========================================= + +You can also customize an image by creating a custom recipe that defines +additional software as part of the image. The following example shows +the form for the two lines you need:: + + IMAGE_INSTALL = "packagegroup-core-x11-base package1 package2" + inherit core-image + +Defining the software using a custom recipe gives you total control over +the contents of the image. It is important to use the correct names of +packages in the :term:`IMAGE_INSTALL` variable. You must use the +OpenEmbedded notation and not the Debian notation for the names (e.g. +``glibc-dev`` instead of ``libc6-dev``). + +The other method for creating a custom image is to base it on an +existing image. For example, if you want to create an image based on +``core-image-sato`` but add the additional package ``strace`` to the +image, copy the ``meta/recipes-sato/images/core-image-sato.bb`` to a new +``.bb`` and add the following line to the end of the copy:: + + IMAGE_INSTALL += "strace" + +Customizing Images Using Custom Package Groups +============================================== + +For complex custom images, the best approach for customizing an image is +to create a custom package group recipe that is used to build the image +or images. A good example of a package group recipe is +``meta/recipes-core/packagegroups/packagegroup-base.bb``. + +If you examine that recipe, you see that the :term:`PACKAGES` variable lists +the package group packages to produce. The ``inherit packagegroup`` +statement sets appropriate default values and automatically adds +``-dev``, ``-dbg``, and ``-ptest`` complementary packages for each +package specified in the :term:`PACKAGES` statement. + +.. note:: + + The ``inherit packagegroup`` line should be located near the top of the + recipe, certainly before the :term:`PACKAGES` statement. + +For each package you specify in :term:`PACKAGES`, you can use :term:`RDEPENDS` +and :term:`RRECOMMENDS` entries to provide a list of packages the parent +task package should contain. You can see examples of these further down +in the ``packagegroup-base.bb`` recipe. + +Here is a short, fabricated example showing the same basic pieces for a +hypothetical packagegroup defined in ``packagegroup-custom.bb``, where +the variable :term:`PN` is the standard way to abbreviate the reference to +the full packagegroup name ``packagegroup-custom``:: + + DESCRIPTION = "My Custom Package Groups" + + inherit packagegroup + + PACKAGES = "\ + ${PN}-apps \ + ${PN}-tools \ + " + + RDEPENDS:${PN}-apps = "\ + dropbear \ + portmap \ + psplash" + + RDEPENDS:${PN}-tools = "\ + oprofile \ + oprofileui-server \ + lttng-tools" + + RRECOMMENDS:${PN}-tools = "\ + kernel-module-oprofile" + +In the previous example, two package group packages are created with +their dependencies and their recommended package dependencies listed: +``packagegroup-custom-apps``, and ``packagegroup-custom-tools``. To +build an image using these package group packages, you need to add +``packagegroup-custom-apps`` and/or ``packagegroup-custom-tools`` to +:term:`IMAGE_INSTALL`. For other forms of image dependencies see the other +areas of this section. + +Customizing an Image Hostname +============================= + +By default, the configured hostname (i.e. ``/etc/hostname``) in an image +is the same as the machine name. For example, if +:term:`MACHINE` equals "qemux86", the +configured hostname written to ``/etc/hostname`` is "qemux86". + +You can customize this name by altering the value of the "hostname" +variable in the ``base-files`` recipe using either an append file or a +configuration file. Use the following in an append file:: + + hostname = "myhostname" + +Use the following in a configuration file:: + + hostname:pn-base-files = "myhostname" + +Changing the default value of the variable "hostname" can be useful in +certain situations. For example, suppose you need to do extensive +testing on an image and you would like to easily identify the image +under test from existing images with typical default hostnames. In this +situation, you could change the default hostname to "testme", which +results in all the images using the name "testme". Once testing is +complete and you do not need to rebuild the image for test any longer, +you can easily reset the default hostname. + +Another point of interest is that if you unset the variable, the image +will have no default hostname in the filesystem. Here is an example that +unsets the variable in a configuration file:: + + hostname:pn-base-files = "" + +Having no default hostname in the filesystem is suitable for +environments that use dynamic hostnames such as virtual machines. + |