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 the poky distribution of The Yocto Project:

Example Output

phytec@ubuntu2004:~/BSP-Yocto-Ampliphy-AM64x-PD23.2.0/build$ 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 phyCORE-AM64x, the AM64x soc, or the BSP-Yocto-Ampliphy-AM64x-PD23.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:

Host (Ubuntu)

cd $BUILDDIR/../sources
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’:

Host (Ubuntu)

cd $BUILDDIR
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:

Host (Ubuntu)

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!

Extend a Recipe

As an exercise, we will extend the default kernel recipe and add the heartbeat LED modification we did in the Modify The BSP guide so that it can be automatically applied when the BSP is built. In order to follow this section of the guide you will need that patch file we generated so you can either create it yourself or download it in the steps below.

First, lets navigate into the meta-custom layer we created above:

Host (Ubuntu)

cd $BUILDDIR/../sources/meta-custom

Note

A handy command to view the structure of a directory is tree, install it with the following command:

Host (Ubuntu)

sudo apt-get install tree

Once tree is installed, use it to view the directory recursively!

Example Output

phytec@ubuntu2004:~/BSP-Yocto-Ampliphy-AM64x-PD23.2.0/sources/meta-custom$ tree
.
├── conf
│   └── layer.conf
├── COPYING.MIT
├── README
└── recipes-example
    └── example
        └── example_0.1.bb

3 directories, 4 files

Linux Kernel recipes by convention should reside in recipes-kernel/linux so we need to change some directories to conform to this convention:

Host (Ubuntu)

mv recipes-example/ recipes-kernel
mv recipes-kernel/example/ recipes-kernel/linux

We also need to change the example recipe to a recipe extension, so that it is applied on-top of an existing recipe. Since we know that the active kernel recipe in BSP-Yocto-Ampliphy-AM64x-PD23.2.0 is linux-ti_6.1.33-phy3.bb, we can extend it by changing the example recipe like so:

Host (Ubuntu)

mv recipes-kernel/linux/example_0.1.bb recipes-kernel/linux/linux-ti_%.bbappend

Now the build system will know that this recipe needs to be applied to the corresponding .bb file of the same name (the ‘%’ symbol acts as a version wildcard).

Open the .bbappend file using your favorite text editor:

Host (Ubuntu)

vim recipes-kernel/linux/linux-ti_%.bbappend

Modify the contents of the .bbappend file to reflect the following:

recipes-kernel/linux/|kernel-package|_%.bbappend

require conf/machine/phyboard-electra-am64xx-2.conf

COMPATIBLE_MACHINE = "phyboard-electra-am64xx-2"

FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}-customPatches:"

SRC_URI += " file://heartbeatD30.patch"

In the .bbappend file, we are instructing to the build system that this recipe extension is compatible with our target MACHINE configuration, the phyCORE-AM64x development kit, and it adds to some key variables the build system uses when processing a package. FILESEXTRAPATHS is the search path the build system uses when looking for files and patches as it processes recipes and append files. SRC_URI lists the actual names of files we want grabbed out of these locations, and in the case of patch files, they will all be automatically applied during the do_compile task.

As the .bbappend suggests, we also need to add our patch file the meta layer, named heartbeatD30.patch here. This guide assumes you backed it up to the home directory as instructed in the Modify The BSP guide.

Create the directory called for in the .bbappend file and copy the patch there:

Host (Ubuntu)

mkdir recipes-kernel/linux/linux-ti-customPatches
cp ~/heartbeatD30.patch recipes-kernel/linux/linux-ti-customPatches

Now your patch should get automatically applied every time the kernel is built.

Clean and rebuild the kernel, and then also rebuild the overall target image to update all the files in your $BUILDDIR/deploy directory:

Host (Ubuntu)

bitbake linux-ti -c clean && bitbake linux-ti && bitbake phytec-headless-image