Layers FAQ

General layer questions

What is a layer?

In OpenEmbedded, a layer is just a collection of recipes and/or configuration that can be used on top of OE-Core. Typically each layer is organised around a specific theme, e.g. adding recipes for building web browser software.

Where do I find existing layers?

See layers.openembedded.org.

How do I make use of a layer?

Clone / extract it somewhere (typically next to or within your OE-Core base directory, but the exact location is not critical) and then add the full path to it to the value of BBLAYERS in your conf/bblayers.conf in your build directory. Note that some layers depend on other layers; it is recommended that you consult the README file within the layer if one is included. Additionally, note that some layer repositories contain multiple layers - in this case there will be subdirectories in the repository corresponding to each layer.

How do I create a new layer?

See Creating a new Layer.

Is there any other documentation on layers?

Yes - the Yocto Project provides a set of manuals that cover layers in some detail.

• For general information see "Understanding and Creating Layers" in the Yocto Project Development Manual.
• For creating a layer for supporting a machine, see the Yocto Project BSP Developer's Guide.

How do I include an inc file from another layer?

You need to specify the path from the base of the other layer to where the inc file is located; e.g:

require recipes-graphics/xorg-driver/xorg-driver-input.inc

I've bbappended a recipe in my layer to replace a file with my own version but it's not being picked up - why not?

Assuming your bbappend is extending FILESEXTRAPATHS (which it must do), the probable cause is that the directory you have added to FILESEXTRAPATHS and the directory in which you have placed the file aren't the same. For example, if you have the following in your bbappend:

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

then your file must be placed in a directory named ${PN} - i.e. if your recipe file is called "magicrecipe_1.0.bb" then the directory would need to be named "magicrecipe". If you prefer, you can adjust the directory name added to FILESEXTRAPATHS as shown above to something else.

I've added a layer to my bblayers.conf and now the system is building an older version of some recipe - why?

The added layer likely contains an older version of the recipe and has a higher layer priority than the layer that contains the existing newer recipe. You can use PREFERRED_VERSION_recipename in your distro or local configuration to override the default selection and select the newer recipe.

Can I overlay/append an inc file from another layer in my layer?

There is no mechanism for this, no - inc files aren't handled in the same manner as .bb and .bbappend files. The possible solutions if you find you need to do this:

• bbappend each recipe that includes the inc file (and you can use % as a wildcard, for example meta-yocto/recipes-core/busybox/busybox_%.bbappend)
• Get an appropriate fix into the inc file itself - which may be adding a variable so that you can select the behaviour you want externally

I've just created a new layer and would like to publish it for the community. What should I do?

There are a few important steps you should take in order to publish a layer for the community:

1. Existing layers: Ideally, ensure your layer does not overlap with other layers. If there must be an overlap and it is not practical to resolve it with the maintainer of the existing layer(s), document what the overlap is and why it is there.
2. Maintainer: If you are publishing the layer as a repository, ensure there is a commitment from at least one person to be the maintainer for the layer. The maintainer's role is to accept, review and (if satisfactory) merge patches from the community.
3. README: Ensure the layer has a README text file in the root which describes briefly what the layer is for, how to use it (if there are any special instructions), the other layers it depends upon, who it is maintained by, and most importantly where and how people should submit patches for it.
4. Publish: Publish the layer in a place where it can be easily accessed. git.yoctoproject.org and openembedded.org can provide hosting, otherwise it is common to host layers on sites such as github.
5. Index: Submit the layer to the OpenEmbedded layer index.
6. Announcement: Send an announcement to both of the following mailing lists telling people about the new layer:
   • yocto@yoctoproject.org (list info)
   • openembedded-devel@lists.openembedded.org (list info)

Layer index

Questions relating to the layer index at layers.openembedded.org.

How do I submit a new layer to the index?

Click on "Submit layer" at the right of the top bar of the page, fill in the fields and then click on Submit.

How can I edit the entry for my layer?

If you're already listed as one of the maintainers for the layer, you can create an account using the same email address as the maintainer entry, and once you log in you'll automatically be able to edit the entry (using the "Edit layer" button in the top right hand corner of the layer details page for the layer).

Alternatively if you're not able to do this, please send an email to paul.eggleton@microsoft.com with your request.

How do I choose the appropriate "layer type" for my layer?

• Base: this is really only for oe-core and meta-oe, i.e. the base metadata for the build system.
• Machine (BSP): if your layer primarily exists to add support for additional machine(s), use this type.
• Software: if your layer primarily provides recipes for building additional software, use this type.
• Distribution: if your layer primarily provides policy configuration for a distribution (conf/distro/*), which may include customised/additional recipes for the distribution, then choose this type.
• Miscellaneous: if your layer doesn't fall into any other category you can choose this type; however there shouldn't be too many miscellaneous layers and it may be an indication that the purpose isn't well defined or that you should consider splitting the layer.

I can't find a recipe I'm looking for. What can I do?

Assuming you have searched the layer index and haven't found anything, there are a few different avenues you can explore:

• You may be able to find an older version of the recipe in the OE-Classic git repository which you can bring up-to-date by following Migrating metadata to OE-Core. These recipes can also be found in the OE-Classic section in the layer index.
• Try devtool add - this will attempt to automatically create a recipe for a given source tree and set up an environment where you can patch the source easily (which you often need to do when you're writing a recipe). See Use devtool add to Integrate New Code in the Yocto Project Development Manual.
• Create your own recipe - it's usually not too difficult. See Writing a New Recipe in the Yocto Project Development Manual for some instructions and examples. You may also find it useful to start by copying another recipe.
• Ask the community on the mailing list if anyone has/is planning on writing the recipe.

How often is the recipe/machine information updated in the index?

Currently, the update script runs once every three hours, fetching the latest version of every repository and updating the index for any changes.

A recipe in my layer has blank values for some fields even though they are specified in the recipe, why is this?

This is usually because the recipe failed to parse correctly when the layer index tried to process it. Note that the layer index update script will not set MACHINE or DISTRO to special values depending on the layer being parsed, so if parts of your layer fail to parse when these are set to other values then this will be a problem - ideally layers should still parse correctly no matter what the value of MACHINE or DISTRO is. Another cause of parse failures can be missing layer dependencies - ensure that all of the appropriate dependencies are listed against the layer in the index.

How do I report an issue with the layer index?

On the yocto mailing list, or if you have a concise description of a bug, please file it in the Yocto Project bugzilla.

I'd like to contribute improvements to the layer index code/design, how can I do that?

The code can be found on git.yoctoproject.org. It uses the Django web framework and split into two parts - the web-based frontend that you interact with, and an update script that runs periodically to gather information about all of the layers in the database. There's further information in the README file on how to contribute.