.. _custommeta-8x: 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 :ref:`BuildTheBSP-8X` 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: .. code-block:: none :caption: Example Output 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] ... 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: 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 --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: .. code-block:: none :caption: Host (Ubuntu) cd ~ git clone 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': .. code-block:: none :caption: Host (Ubuntu) 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: .. code-block:: none :caption: Host (Ubuntu) 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: .. code-block:: none :caption: Host (Ubuntu) cd meta-custom .. note:: A handy command to view the structure of a directory is 'tree', install it with the following command: .. code-block:: none :caption: Host (Ubuntu) sudo apt-get install tree Once 'tree' is installed, use it to view the directory recursively! .. code-block:: none :caption: Example Output 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: .. code-block:: none :caption: 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 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: .. code-block:: none :caption: Host (Ubuntu) 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: .. code-block:: none :caption: Host (Ubuntu) vim recipes-kernel/linux/linux-phytec-fsl_5.4.24.bbappend Modify the contents of the .bbappend file to reflect the following: .. code-block:: none :caption: recipes-kernel/linux/linux-phytec-fsl_5.4.24.bbappend 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. Create the directory called for in the .bbappend file and copy the patch there: .. code-block:: none :caption: Host (Ubuntu) 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: .. code-block:: none :caption: Host (Ubuntu) bitbake linux-phytec-fsl -c clean && bitbake linux-phytec-fsl && bitbake imx-image-multimedia