yocto layers

4.1. Understanding and Creating Layers

The Yocto Project build system supports organizing metadata into multiple layers. Layers allow you to isolate different types of customizations from each other. You might find it tempting to keep everything in one layer when working on a single project. However, the more modular you organize your metadata, the easier it is to cope with future changes.

To illustrate how layers are used to keep things modular, consider machine customizations. These types of customizations typically reside in a BSP Layer. Furthermore, the machine customizations should be isolated from recipes and metadata that support a new GUI environment, for example. This situation gives you a couple a layers: one for the machine configurations, and one for the GUI environment. It is important to understand, however, that the BSP layer can still make machine-specific additions to recipes within the GUI environment layer without polluting the GUI layer itself with those machine-specific changes. You can accomplish this through a recipe that is a BitBake append (.bbappend) file, which is described later in this section.

4.1.1. Yocto Project Layers

The Yocto Project contains several layers right out of the box. You can easily identify a layer in the Yocto Project by the name of its folder. Folders that are layers begin with the stringmeta. For example, when you set up theYocto Project Files structure, you will see several layers: meta,meta-demoapps,meta-skeleton, andmeta-yocto. Each of these folders is a layer.

Furthermore, if you set up a local copy of the meta-intel Git repository and then explore that folder, you will discover many BSP layers within themeta-intel layer. For more information on BSP layers, see the "BSP Layers" section in the Yocto Project Board Support Package (BSP) Developer's Guide.

4.1.2. Creating Your Own Layer

It is very easy to create your own layer to use with the Yocto Project. Follow these general steps to create your layer:

1. Check Existing Layers: Before creating a new layer, you should be sure someone has not already created a layer containing the metadata you need. You can see theLayerIndex for a list of layers from the OpenEmbedded community that can be used in the Yocto Project.

2. Create a Directory: Create the directory for your layer. Traditionally, prepend the name of the folder with the stringmeta. For example:

        meta-mylayer
        meta-GUI_xyz
        meta-mymachine
                           

3. Create a Layer Configuration File: Inside your new layer folder, you need to create aconf/layer.conf file. It is easiest to take an existing layer configuration file and copy that to your layer'sconf directory and then modify the file as needed.

   The meta-yocto/conf/layer.conf file demonstrates the required syntax:

        # We have a conf and classes directory, add to BBPATH
        BBPATH := "${LAYERDIR}:${BBPATH}"
   
        # We have a packages directory, add to BBFILES
        BBFILES := "${BBFILES} ${LAYERDIR}/recipes-*/*/*.bb \
                    ${LAYERDIR}/recipes-*/*/*.bbappend"
   
        BBFILE_COLLECTIONS += "yocto"
        BBFILE_PATTERN_yocto := "^${LAYERDIR}/"
        BBFILE_PRIORITY_yocto = "5" 
                           

   In the previous example, the recipes for the layers are added to BBFILES. TheBBFILE_COLLECTIONS variable is then appended with the layer name. TheBBFILE_PATTERN variable is set to a regular expression and is used to match files fromBBFILES into a particular layer. In this case, immediate expansion ofLAYERDIR setsBBFILE_PATTERN to the layer's path. The BBFILE_PRIORITY variable then assigns a priority to the layer. Applying priorities is useful in situations where the same package might appear in multiple layers and allows you to choose what layer should take precedence.

   Note the use of the LAYERDIR variable with the immediate expansion operator. TheLAYERDIR variable expands to the directory of the current layer and requires the immediate expansion operator so that BitBake does not wait to expand the variable when it's parsing a different directory.

   Through the use of the BBPATH variable, BitBake locates.bbclass files, configuration files, and files that are included withinclude andrequire statements. For these cases, BitBake uses the first file with the matching name found inBBPATH. This is similar to the way thePATH variable is used for binaries. We recommend, therefore, that you use unique.bbclass and configuration file names in your custom layer.

4. Add Content: Depending on the type of layer, add the content. If the layer adds support for a machine, add the machine configuration in aconf/machine/ file within the layer. If the layer adds distro policy, add the distro configuration in aconf/distro/ file with the layer. If the layer introduces new recipes, put the recipes you need inrecipes-* subdirectories within the layer.

To create layers that are easier to maintain, you should consider the following:

• Avoid "overlaying" entire recipes from other layers in your configuration. In other words, don't copy an entire recipe into your layer and then modify it. Use.bbappend files to override the parts of the recipe you need to modify.

• Avoid duplicating include files. Use .bbappend files for each recipe that uses an include file. Or, if you are introducing a new recipe that requires the included file, use the path relative to the original layer directory to refer to the file. For example, use require recipes-core/somepackage/somefile.inc instead ofrequire somefile.inc. If you're finding you have to overlay the include file, it could indicate a deficiency in the include file in the layer to which it originally belongs. If this is the case, you need to address that deficiency instead of overlaying the include file. For example, consider how Qt 4 database support plugins are configured. The Yocto Project does not have MySQL or PostgreSQL, however OpenEmbedded's layermeta-oe does. Consequently,meta-oe uses .bbappend files to modify theQT_SQL_DRIVER_FLAGS variable to enable the appropriate plugins. This variable was added to theqt4.inc include file in The Yocto Project specifically to allow themeta-oe layer to be able to control which plugins are built.

We also recommend the following:

• Store custom layers in a Git repository that uses the meta-<layer_name> format.

• Clone the repository alongside other meta directories in the Yocto Project source files area.

Following these recommendations keeps your Yocto Project files area and its configuration entirely inside the Yocto Project's core base.

4.1.3. Enabling Your Layer

Before the Yocto Project build system can use your new layer, you need to enable it. To enable your layer, simply add your layer's path to theBBLAYERS variable in yourconf/bblayers.conf file, which is found in theYocto Project Build Directory. The following example shows how to enable a layer namedmeta-mylayer:

     LCONF_VERSION = "1"

     BBFILES ?= ""
     BBLAYERS = " \
       /path/to/poky/meta \
       /path/to/poky/meta-yocto \
       /path/to/poky/meta-mylayer \
       "
                

BitBake parses each conf/layer.conf file as specified in theBBLAYERS variable within theconf/bblayers.conf file. During the processing of eachconf/layer.conf file, BitBake adds the recipes, classes and configurations contained within the particular layer to the Yocto Project.

4.1.4. Using .bbappend Files

Recipes used to append metadata to other recipes are called BitBake append files. BitBake append files use the.bbappend file type suffix, while underlying recipes to which metadata is being appended use the.bb file type suffix.

A .bbappend file allows your layer to make additions or changes to the content of another layer's recipe without having to copy the other recipe into your layer. Your.bbappend file resides in your layer, while the underlying.bb recipe file to which you are appending metadata resides in a different layer.

Append files files must have the same name as the underlying recipe. For example, the append filesomeapp_1.2.bbappend must apply tosomeapp_1.2.bb. This means the original recipe and append file names are version number specific. If the underlying recipe is renamed to update to a newer version, the corresponding.bbappend file must be renamed as well. During the build process, BitBake displays an error on starting if it detects a.bbappend file that does not have an underlying recipe with a matching name.

Being able to append information to an existing recipe not only avoids duplication, but also automatically applies recipe changes in a different layer to your layer. If you were copying recipes, you would have to manually merge changes as they occur.

As an example, consider the main formfactor recipe and a corresponding formfactor append file both from theYocto Project Files. Here is the main formfactor recipe, which is named formfactor_0.0.bb and located in the meta layer atmeta/bsp-recipes/formfactor:

     DESCRIPTION = "Device formfactor information"
     SECTION = "base"
     LICENSE = "MIT"
     LIC_FILES_CHKSUM = "file://${COREBASE}/LICENSE;md5=3f40d7994397109285ec7b81fdeb3b58 \
                    file://${COREBASE}/meta/COPYING.MIT;md5=3da9cfbcb788c80a0384361b4de20420"
     PR = "r19"

     SRC_URI = "file://config file://machconfig"
     S = "${WORKDIR}"

     PACKAGE_ARCH = "${MACHINE_ARCH}"
     INHIBIT_DEFAULT_DEPS = "1"

     do_install() {
     	# Only install file if it has a contents
             install -d ${D}${sysconfdir}/formfactor/
             install -m 0644 ${S}/config ${D}${sysconfdir}/formfactor/
     	if [ -s "${S}/machconfig" ]; then
     	        install -m 0644 ${S}/machconfig ${D}${sysconfdir}/formfactor/
	     fi
     }
                

Here is the append file, which is named formfactor_0.0.bbappend and is from the Crown Bay BSP Layer namedmeta-intel/meta-crownbay:

     FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
 
     PRINC = "1"
                

This example adds or overrides files in SRC_URI within a .bbappend by extending the path BitBake uses to search for files. The most reliable way to do this is by prepending theFILESEXTRAPATHS variable. For example, if you have your files in a directory that is named the same as your package (PN), you can add this directory by adding the following to your .bbappend file:

     FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
                

Using the immediate expansion assignment operator := is important because of the reference toTHISDIR. The trailing colon character is important as it ensures that items in the list remain colon-separated.

Note

BitBake automatically defines the THISDIR variable. You should never set this variable yourself. Using _prepend ensures your path will be searched prior to other paths in the final list.

For another example on how to use a .bbappend file, see the "Changingrecipes-kernel" section.

4.1.5. Prioritizing Your Layer

Each layer is assigned a priority value. Priority values control which layer takes precedence if there are recipe files with the same name in multiple layers. For these cases, the recipe file from the layer with a higher priority number taking precedence. Priority values also affect the order in which multiple.bbappend files for the same recipe are applied. You can either specify the priority manually, or allow the build system to calculate it based on the layer's dependencies.

To specify the layer's priority manually, use the BBFILE_PRIORITY variable. For example:

     BBFILE_PRIORITY := "1"
                

Note

It is possible for a recipe with a lower version number PV in a layer that has a higher priority to take precedence.

Also, the layer priority does not currently affect the precedence order of .conf or .bbclass files. Future versions of BitBake might address this.

4.1.6. Managing Layers

You can use the BitBake layer management tool to provide a view into the structure of recipes across a multi-layer project. Being able to generate output that reports on configured layers with their paths and priorities and on.bbappend files and their applicable recipes can help to reveal potential problems.

Use the following form when running the layer management tool.

     $ bitbake-layers <command> [arguments]
                

The following list describes the available commands:

• help: Displays general help or help on a specified command.

• show-layers: Show the current configured layers.

• show-recipes: Lists available recipes and the layers that provide them.

• show-overlayed: Lists overlayed recipes. A recipe is overlayed when a recipe with the same name exists in another layer that has a higher layer priority.

• show-appends: Lists.bbappend files and the recipe files to which they apply.

• flatten: Flattens the layer configuration into a separate output directory. Flattening your layer configuration builds a "flattened" directory that contains the contents of all layers, with any overlayed recipes removed and any .bbappend files appended to the corresponding recipes. You might have to perform some manual cleanup of the flattened layer as follows:

  • Non-recipe files (such as patches) are overwritten. The flatten command shows a warning for these files.

  • Anything beyond the normal layer setup has been added to the layer.conf file. Only the lowest priority layer's layer.conf is used.

  • Overridden and appended items from .bbappend files need to be cleaned up. The contents of each.bbappend end up in the flattened recipe. However, if there are appended or changed variable values, you need to tidy these up yourself. Consider the following example. Here, thebitbake-layers command adds the line#### bbappended ... so that you know where the following lines originate:

         ...
         DESCRIPTION = "A useful utility"
         ...
         EXTRA_OECONF = "--enable-something"
         ...
    
         #### bbappended from meta-anotherlayer ####
    
         DESCRIPTION = "Customized utility"
         EXTRA_OECONF += "--enable-somethingelse"
                                    

    Ideally, you would tidy up these utilities as follows:

         ...
         DESCRIPTION = "Customized utility"
         ...
         EXTRA_OECONF = "--enable-something --enable-somethingelse"
         ...