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 in the poky distribution of The Yocto Project:
phytec@phytec-virtual-machine:~/BSP-Yocto-FSL-i.MX8X-PD21.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 OpenEmbedded Metadata Index for a list of layers from the OpenEmbedded community that can be used in the Yocto Project.
Note
Not all community layers are going to be compatible with the phyCORE-i.MX8X, the i.MX8X soc, or the Linux BSP PD21.1.0.
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:
cd ~
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’:
cd $BUILDDIR
bitbake-layers create-layer 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.
This command sets up a meta-custom layer directory and automatically populates it with examples a configuration and recipe for an example, in the current working directory.
Add Layers
Now that you have a meta layer (perhaps you manually cloned an existing layer), we can add it to the build system:
bitbake-layers add-layer 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!
Tip
Remember, you can always ask questions in the PHYTEC’s Support Portal! We want your projects to succeed!
Extend a RecipeLink to 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:
cd meta-custom
Note
A handy command to view the structure of a directory is ‘tree’, install it with the following command:
sudo apt-get install tree
Once ‘tree’ is installed, use it to view the directory recursively!
phytec@phytec-virtual-machine:~/BSP-Yocto-FSL-i.MX8X-PD21.1.0/build/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:
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 the phyCORE-i.MX8X PD21.1.0 BSP is linux-phytec-fsl_5.4.24.bb, we can extend it by changing the example recipe like so:
mv recipes-kernel/linux/example_0.1.bb recipes-kernel/linux/linux-phytec-fsl_5.4.24.bbappend
Now the build system will know that this recipe needs to be applied to the .bb file of the same name.
Open the .bbappend file using your favorite text editor:
vim recipes-kernel/linux/linux-phytec-fsl_5.4.24.bbappend
Modify the contents of the .bbappend file to reflect the following:
COMPATIBLE_MACHINE = "imx8x-phycore-kit"
FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}-customPatches:"
SRC_URI += " file://heartbeatD31.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-i.MX8X 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. Feel free to download it here if you need it (heartbeatD31.patch), this guide will assume you backed it up to the home directory as instructed in the :ref: modifyBSP-8X guide.
Create the directory called for in the .bbappend file and copy the patch there:
mkdir recipes-kernel/linux/linux-phytec-fsl-customPatches
cp ~/heartbeatD31.patch recipes-kernel/linux/linux-phytec-fsl-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 deployment directory:
bitbake linux-phytec-fsl -c clean && bitbake linux-phytec-fsl && bitbake imx-image-multimedia