Create a Custom Meta-Layer
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-AM57x-PD23.1.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-AM57x, the AM57x soc, or the BSP-Yocto-AM57x-PD23.1.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-AM57x-PD23.1.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-AM57x-PD23.1.0 is linux-ti_5.10.168-phy7.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/phycore-am57xx-1.conf
COMPATIBLE_MACHINE = "phycore-am57xx-1"
FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}-customPatches:"
SRC_URI += " file://heartbeatD1.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-AM57x 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 heartbeatD1.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 ~/heartbeatD1.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-qt5demo-image