5.1.2. Creating Your Own Layer

It is very easy to create your own layers to use with the OpenEmbedded build system. The Yocto Project ships with scripts that speed up creating general layers and BSP layers. This section describes the steps you perform by hand to create a layer so that you can better understand them. For information about the layer-creation scripts, see the "Creating a New BSP Layer Using the yocto-bsp Script" section in the Yocto Project Board Support Package (BSP) Developer's Guide and the "Creating a General Layer Using the yocto-layer Script" section further down in this manual.

Follow these general steps to create your layer without the aid of a script:

  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 the OpenEmbedded Metadata Index 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. While not strictly required, prepend the name of the folder with the string meta-. For example:

         meta-mylayer
         meta-GUI_xyz
         meta-mymachine
                            

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

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

         # We have a conf and classes directory, add to BBPATH
         BBPATH .= ":${LAYERDIR}"
    
         # We have recipes-* directories, add to BBFILES
         BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \
                     ${LAYERDIR}/recipes-*/*/*.bbappend"
    
         BBFILE_COLLECTIONS += "yoctobsp"
         BBFILE_PATTERN_yoctobsp = "^${LAYERDIR}/"
         BBFILE_PRIORITY_yoctobsp = "5"
         LAYERVERSION_yoctobsp = "3"
                            

    Here is an explanation of the example:

    • The configuration and classes directory is appended to BBPATH.

      Note

      All non-distro layers, which include all BSP layers, are expected to append the layer directory to the BBPATH. On the other hand, distro layers, such as meta-poky, can choose to enforce their own precedence over BBPATH. For an example of that syntax, see the layer.conf file for the meta-poky layer.
    • The recipes for the layers are appended to BBFILES.

    • The BBFILE_COLLECTIONS variable is then appended with the layer name.

    • The BBFILE_PATTERN variable is set to a regular expression and is used to match files from BBFILES into a particular layer. In this case, LAYERDIR is used to make BBFILE_PATTERN match within the layer's path.

    • The BBFILE_PRIORITY variable then assigns a priority to the layer. Applying priorities is useful in situations where the same recipe might appear in multiple layers and allows you to choose the layer that takes precedence.

    • The LAYERVERSION variable optionally specifies the version of a layer as a single number.

    Note the use of the LAYERDIR variable, which expands to the directory of the current layer.

    Through the use of the BBPATH variable, BitBake locates class files (.bbclass), configuration files, and files that are included with include and require statements. For these cases, BitBake uses the first file that matches the name found in BBPATH. This is similar to the way the PATH variable is used for binaries. It is recommended, therefore, that you use unique class and configuration filenames 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 a conf/machine/ file within the layer. If the layer adds distro policy, add the distro configuration in a conf/distro/ file within the layer. If the layer introduces new recipes, put the recipes you need in recipes-* subdirectories within the layer.

    Note

    In order to be compliant with the Yocto Project, a layer must contain a README file.

  5. Optionally Test for Compatibility: If you want permission to use the Yocto Project Compatibility logo with your layer or application that uses your layer, perform the steps to apply for compatibility. See the "Making Sure Your Layer is Compatible With Yocto Project" section for more information.