3.1.1. 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 tools that speed up creating layers. This section describes the steps you perform by hand to create layers so that you can better understand them. For information about the layer-creation tools, see the "Creating a New BSP Layer Using the bitbake-layers Script" section in the Yocto Project Board Support Package (BSP) Developer's Guide and the "Creating a General Layer Using the bitbake-layers Script" section further down in this manual.

Follow these general steps to create your layer without using tools:

  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. You could find a layer that is identical or close to what you need.

  2. Create a Directory: Create the directory for your layer. When you create the layer, be sure to create the directory in an area not associated with the Yocto Project Source Directory (e.g. the cloned poky repository).

    While not strictly required, prepend the name of the directory with the string "meta-". For example:

         meta-mylayer
         meta-GUI_xyz
         meta-mymachine
                            

    With rare exceptions, a layer's name follows this form:

         meta-root_name
                            

    Following this layer naming convention can save you trouble later when tools, components, or variables "assume" your layer name begins with "meta-". A notable example is in configuration files as shown in the following step where layer names without the "meta-" string are appended to several variables used in the configuration.

  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 in the Yocto Project Source Repositories demonstrates the required syntax. For your layer, you need to replace "yoctobsp" with a unique identifier for your layer (e.g. "machinexyz" for a layer named "meta-machinexyz"):

         # 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 = "4"
         LAYERSERIES_COMPAT_yoctobsp = "warrior"
                            

    Following is an explanation of the layer configuration file:

    • BBPATH: Adds the layer's root directory to BitBake's search path. 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.

    • BBFILES: Defines the location for all recipes in the layer.

    • BBFILE_COLLECTIONS: Establishes the current layer through a unique identifier that is used throughout the OpenEmbedded build system to refer to the layer. In this example, the identifier "yoctobsp" is the representation for the container layer named "meta-yocto-bsp".

    • BBFILE_PATTERN: Expands immediately during parsing to provide the directory of the layer.

    • BBFILE_PRIORITY: Establishes a priority to use for recipes in the layer when the OpenEmbedded build finds recipes of the same name in different layers.

    • LAYERVERSION: Establishes a version number for the layer. You can use this version number to specify this exact version of the layer as a dependency when using the LAYERDEPENDS variable.

    • LAYERSERIES_COMPAT: Lists the Yocto Project releases for which the current version is compatible. This variable is a good way to indicate if your particular layer is current.

  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

    For an explanation of layer hierarchy that is compliant with the Yocto Project, see the "Example Filesystem Layout" section in the Yocto Project Board Support Package (BSP) Developer's Guide.

  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.