Welcome to our comprehensive guide on customizing the Yocto image. This platform is designed for high flexibility and adaptability, catering to a wide range of specific requirements. In this document, we will guide you through the process of adding your own layer to our standard Board Support Package (BSP). This addition is crucial for integrating bespoke features and functionalities, ensuring they align perfectly with your project's unique goals and objectives.

Before starting this customization journey, ensure you have:

• A fundamental understanding of the Yocto Project and its layering system.
• A Yocto Project environment set up and configured according to the official Yocto Project documentation.
• Access to our standard BSP for baseline integration.

Follow these steps to integrate your custom layer into the Yocto build:

1. Creating Your Layer:

   • In the Yocto Project directory, run:

     bitbake-layers create-layer path/to/your-layer

   • Replace path/to/your-layer with the desired directory path for your new layer.
   • This command creates a new layer directory with essential configuration files.

2. Incorporating Your Layer into the Build:

   • Add your layer to the build process:

     bitbake-layers add-layer path/to/your-layer

   • This step registers your layer in the bblayers.conf file, acknowledging its role in the build configuration.

3. Layer Customization:

   • Your layer directory is now set for customization. You can introduce new recipes, append files, and modify configurations as needed.
   • Use recipes to add new packages or modify existing ones.
   • Use .bbappend files for extending or altering the functionalities of existing recipes.

4. Building Your Customized Image:

   • Compile your image after customization:

     bitbake your-image-name

   • Replace your-image-name with the name of your customized image.

• Set up a Manifest repository.
• Create a Meta Layer repository.

Creating a Yocto layer involves setting up a specific directory structure. A basic Yocto layer typically includes the following folders and files:

1. conf Directory: This directory contains configuration files for the layer.

   • layer.conf: The main configuration file for the layer. It informs BitBake about the layer's existence and its compatibility with different Yocto releases.

2. recipes-<category> Directories: These directories contain the recipes. Each directory typically corresponds to a category of software or functionality (e.g., recipes-kernel, recipes-graphics). Within these directories, you structure your recipes into appropriate subdirectories.

   • For example, if you have a recipe for an application named example, you might create a directory structure like recipes-apps/example/example_1.0.bb.

3. classes Directory (Optional): If your layer provides custom BitBake classes, they go here.

4. files Directory (Optional): This directory typically contains auxiliary files that are used by the recipes, such as patches or configuration files.

5. licenses Directory (Optional): If your layer includes custom licenses, they are placed here.

6. documentation Directory (Optional): For storing any documentation specific to the layer.

Here is a visual representation of the most basic project structure for a Yocto layer:

meta-yourlayer/
├── conf/
│   └── layer.conf
└── recipes-example/
    └── example/
        └── example_1.0.bb

In this example, meta-yourlayer is the name of your custom layer. The recipes-example directory contains a recipe for an example application. The actual recipe file (example_1.0.bb) includes the instructions for building the example application.

This structure can be expanded as needed to include more recipes, classes, and other files relevant to your layer's functionality. The naming convention for recipes and directories should be consistent and descriptive to ensure clarity and ease of navigation.

• On GitHub, create a new repository, ensuring it's publicly visible.
• For example: https://github.com/YourUsername/meta-mylayer

Next, clone your repository locally:

git clone https://github.com/YourUsername/meta-mylayer

Create a tools directory to contain a script for initializing your project's bblayers file, which will reference all layers in your Yocto Project directory:

mkdir tools
touch tools/mylayer-setup-release.sh

Refer to our script for guidance and modify it to include your layer. In the echo chain, add your layer's line, omitting the + sign in your script:

# [Existing echo statements]
+ echo "BBLAYERS += \"\${BSPDIR}/sources/meta-mylayer\"" >> $BUILD_DIR/conf/bblayers.conf
# [Additional echo statements if any]

echo "BBLAYERS += \"\${BSPDIR}/sources/meta-nxp-demo-experience\"" >> $BUILD_DIR/conf/bblayers.conf
echo "BBLAYERS += \"\${BSPDIR}/sources/meta-qt6\"" >> $BUILD_DIR/conf/bblayers.conf
echo "BBLAYERS += \"\${BSPDIR}/sources/meta-python2\"" >> $BUILD_DIR/conf/bblayers.conf
echo "BBLAYERS += \"\${BSPDIR}/sources/meta-security/meta-tpm\"" >> $BUILD_DIR/conf/bblayers.conf
echo "BBLAYERS += \"\${BSPDIR}/sources/meta-winsys\"" >> $BUILD_DIR/conf/bblayers.conf
+ echo "BBLAYERS += \"\${BSPDIR}/sources/meta-mylayer\"" >> $BUILD_DIR/conf/bblayers.conf

if [ -d ../sources/meta-ivi ]; then
    echo -e "\n## Genivi layers" >> $BUILD_DIR/conf/bblayers.conf
    echo "BBLAYERS += \"\${BSPDIR}/sources/meta-gplv2\"" >> $BUILD_DIR/conf/bblayers.conf
    echo "BBLAYERS += \"\${BSPDIR}/sources/meta-ivi/meta-ivi\"" >> $BUILD_DIR/conf/bblayers.conf
    echo "BBLAYERS += \"\${BSPDIR}/sources/meta-ivi/meta-ivi-bsp\"" >> $BUILD_DIR/conf/bblayers.conf
    echo "BBLAYERS += \"\${BSPDIR}/sources/meta-ivi/meta-ivi-test\"" >> $BUILD_DIR/conf/bblayers.conf

Create a conf directory and a file named layer.conf within it. This file informs Bitbake about the contents of your meta layer:

mkdir conf
touch conf/layer.conf

Include the following in conf/layer.conf:

# Configuration details for the layer
BBPATH .= ":${LAYERDIR}"
BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \
            ${LAYERDIR}/recipes-*/*/*.bbappend"

BBFILE_COLLECTIONS += "mylayer"
BBFILE_PATTERN_mylayer:= "^${LAYERDIR}"
BBFILE_PRIORITY_mylayer = "11"
LAYERSERIES_COMPAT_mylayer = "kirkstone"

Next, add a recipe to create a custom image based on the WinSystems BSP image:

mkdir -p recipes-mylayer/images
touch recipes-mylayer/images/my-custom-image.bb

In recipes-mylayer/images/my-custom-image.bb, add the following:

DESCRIPTION = "My Layer Description"
LICENSE = "MIT"

require recipes-winsys/images/winsys-image-demo.bb

CORE_IMAGE_EXTRA_INSTALL += " \
	picocom \
"

• Fork our Manifest from GitHub for easier updates: https://github.com/WinSystems/c444-manifest/tree/5.15
• Ensure to clone all branches, not just the main one.

When working with Yocto, the manifest file plays a crucial role in managing multiple repositories. Integrating your meta layer into the manifest ensures that your custom layer is properly fetched and positioned in the build system. Here's a more detailed explanation of each step involved:

1. Edit the XML Manifest File:

   • Locate the XML manifest file relevant to your build, for example, itx-p-c444_5.15.32.xml.
   • This file contains the information about various repositories (including layers) that the Yocto Project will fetch and use during the build process.

2. Prepare Your Meta Layer Repository Link:

   • On GitHub, navigate to your Meta Layer repository.
   • Copy the HTTPS clone link, but modify it slightly for the manifest file.
   • Exclude the repository's .git name at the end and append a /. For instance, if your repo's URL is https://github.com/YourUsername/meta-mylayer.git, modify it to https://github.com/YourUsername/.

3. Add the Repository Link to the XML File:

   • In the manifest file, define a new remote element with the fetch attribute pointing to the URL you prepared. For example:

     <remote fetch="https://github.com/YourUsername/" name="myremote"/>     

   • Here, name="myremote" is an identifier for your remote URL that will be referenced in other parts of the manifest.

4. Configure the XML for Cloning Your Meta Layer:

   • After defining the remote, specify the project element to instruct the repo tool on how to handle your custom layer.
   • The project tag includes several attributes:
     • remote="myremote": This links to the remote defined earlier.
     • name="meta-mylayer": The actual repository name on GitHub.
     • path="sources/meta-mylayer": The local directory path where the layer will be cloned. It's usually within the sources directory.
     • revision="main": The branch of your repository to be used.
   • For example:

     <project remote="myremote" name="meta-mylayer" path="sources/meta-mylayer" revision="main">
       <linkfile src="tools/mylayer-setup-release.sh" dest="mylayer-setup-release.sh"/>
     </project>

   • The linkfile tag is used to create a symbolic link. This example creates a link from the tools/mylayer-setup-release.sh in your meta-layer to the root of your Yocto project. This makes it easier to execute the script without navigating into the layer's directory.

By following these steps, you ensure that your custom meta layer is correctly integrated into the Yocto build system. The repo tool will recognize and fetch your layer according to the instructions specified in the manifest, making it a part of the build environment.

Google's repo tool helps manage repositories defined in a manifest file:

mkdir ~/bin
curl https://storage.googleapis.com/git-repo-downloads/repo > ~/bin/repo
chmod a+x ~/bin/repo
export PATH=~/bin:$PATH

• Use -m for the XML file and -b for your manifest's branch:

cd ~/winYocto
repo init -u https://github.com/YourUsername/c444-manifest-mylayer.git -b main -m itx-p-c444_5.15.32.xml
repo sync

Set up your environment and start the build process:

MACHINE=imx8mq-itx-p-c444 DISTRO=c444-xwayland source mylayer-setup-release.sh -b build
bitbake -k my-custom-image

• Thoroughly test the built image in your target environment.
• Ensure all custom features and configurations work as intended.

• Ensure layer paths are correctly specified in bblayers.conf.
• Check for syntax errors in your recipes and append files.
• Refer to the Yocto Project documentation for common troubleshooting tips.

• Yocto Project Documentation
• BitBake User Manual