Create a Custom Meta-Layer

Custom Meta Layers!

Note

The video linked here is a little out of date now but it is still a good introduction to creating custom meta layers. For release-specific commands, refer to the guide.

At some point during application development it will become advantageous to consolidate the changes you made to the stock BSP into a meta layer in order to have them applied automatically by the build system. This makes it easier to reproduce the production image in new build environments and also allows you to version control your changes to the BSP, since meta layers are themselves repositories. As PHYTEC comes out with new BSP releases over time to improve our products, having your changes all in one meta layer also makes it easier to upgrade to the latest BSP and kernel when your development allows.

Note

In order to follow this guide, you must have first built the BSP in its entirety and have your BSP environment initialized. Checkout the Build the BSP guide if you haven’t yet!

bitbake-layers Tool

The easiest way to introduce new meta layers to the build system is by leveraging the bitbake-layers tool from OpenEmbedded-Core:

Example Output

sh-container:~$ bitbake-layers -h
NOTE: Starting bitbake server...
usage: bitbake-layers [-d] [-q] [-F] [--color COLOR] [-h] <subcommand> ...

BitBake layers utility

optional arguments:
  -d, --debug           Enable debug output
  -q, --quiet           Print only errors
  -F, --force           Force add without recipe parse verification
  --color COLOR         Colorize output (where COLOR is auto, always, never)
  -h, --help            show this help message and exit

subcommands:
  <subcommand>
    show-layers         show current configured layers.
    show-overlayed      list overlayed recipes (where the same recipe exists in another layer)
    show-recipes        list available recipes, showing the layer they are provided by
    show-appends        list bbappend files and recipe files they apply to
    show-cross-depends  Show dependencies between recipes that cross layer boundaries.
    layerindex-fetch    Fetches a layer from a layer index along with its dependent layers, and adds them to conf/bblayers.conf.
    layerindex-show-depends
                        Find layer dependencies from layer index.
    add-layer           Add one or more layers to bblayers.conf.
    remove-layer        Remove one or more layers from bblayers.conf.
    flatten             flatten layer configuration into a separate output directory.
    create-layer        Create a basic layer

Use bitbake-layers <subcommand> --help to get help on a specific command

Check Existing Layers

Before creating a new layer, you should be sure someone in the Yocto community hasn’t already created a layer containing the metadata you need. You can see the Open Embedded Layer Index for a list of layers from the OpenEmbedded community that can be used with the Yocto Project.

Note

Not all community layers are going to be compatible with the phyFLEX-AM62Px, the AM62Px soc, or the BSP-Yocto-Ampliphy-AM62Px-PD26.2.0 (this may or may not have workarounds however).

If you are familiar with Yocto and have used the workflow for a previous project, perhaps you already have a meta layer setup. In either case, you should find the repo URL of the meta layer and clone it locally to your Host Machine:

sh-container:~$ cd $BUILDDIR/../sources
sh-container:~$ git clone <meta layer URL>

You’ll also want to ensure that the appropriate branch of the layer is checked out, if applicable.

Note

This guide we will work through an example by creating a meta-custom layer but the commands here should still serve as a reference for when working with existing meta layers you manually cloned to the local file system.

Create a Layer

Use the following command to create a new meta layer from scratch, named ‘meta-custom’:

sh-container:~$ cd $BUILDDIR
sh-container:~$ bitbake-layers create-layer $BUILDDIR/../sources/meta-custom

Note

It is not a requirement that a layer name begin with the prefix meta-, but it is a commonly accepted standard in the Yocto Project community.

The bitbake-layers create-layer command sets up an example meta layer and automatically populates it with configuration information and an example recipe.

Add Layers

Now that you have a meta layer (or perhaps you manually cloned an existing layer from the OpenEmbedded Layer Index), we can enable it in the build system:

sh-container:~$ bitbake-layers add-layer $BUILDDIR/../sources/meta-custom

You have officially added a custom meta layer to the BSP! Congratulations! At this point, the best resource for further customizing this meta layer according to the specific needs of your project is to work through The Yocto Project Development Tasks Manual and The Yocto Project Board Support Package Developer’s Guide. We know that its a lot of manuals!

Note

Remember, you can always ask questions in PHYTEC’s Support Portal! We want your projects to succeed!

Note

For any technical questions, feel free to reach out to PHYTEC’s Support Portal!