Customize Yocto (General Guide)

During the evaluation, package(s) may be missing in the TQ BSP default image configuration. If you're looking for specific recipes or layers, the OpenEmbedded layer index layer index is a good place to start.

Adding package(s) to the build may require adding additional Yocto meta layer(s)
The easiest approach to add a package recipe to the build, is to use the use IMAGE_INSTALL:append variable in the conf/local.conf file, which is located in the current build space.

Open a new terminal on the development host and navigate into the workspace directory and initialize the build environment as described in the Quickstart BSP:

cd ~/workspace/<path-to-ci-meta-tq>
source setup-environment <build-dir>

The example below demonstrates how to add the editor nano (which is part of the meta-oe Yocto layer) to the build.
Open conf/local.conf with an editor of choice and insert the following lines at the end of the file:

IMAGE_INSTALL:append = " nano"

Multiple packages can also be added using the IMAGE_INSTALL:append variable. This can be done in one line or multiple lines, shown in the two code examples below.

IMAGE_INSTALL:append = " <recipe-name_1> <recipe-name_2>" 
# OR
IMAGE_INSTALL:append = " \
                       <recipe-name_1> \
                       <recipe-name_2> \
                       "

Once the desired package(s) have been added, the image can be rebuilt by executing:

bitbake tq-image-weston-debug

Note: Changes to local.conf only affect the current build space. They will be lost when the build space is reset.

For customer-specific adaptations, we recommend creating an own Yocto meta-layer. For this purpose Bitbake provides a script that simplifies the process of creating new layers.
It creates a template meta-layer with basic structure.
To add a template layer to ci-meta-tq/sources, using the bitbake-layers create-layer script:

cd ~/workspace/<path-to-ci-meta-tq>/sources
bitbake-layers create-layer meta-custom

Before making changes to the new layer, it is recommended to perform the following actions:

1. Initialize the new layer as a git repository.
2. Edit README template.
3. Check and, if necessary, adjust the layer license.
4. Configure the layer priority in layer.conf.

📂 meta-custom/
├── 📄 conf/layer.conf
├── 📄 README
├── 📂 recipes-images/
│   └── 📂 images/
│       └── 📄 tq-image-weston-debug.bbappend  (Add packages)
└── 📂 recipes-kernel/
    └── 📂 linux/
        ├── 📂 <kernel-recipe>/
        │   ├── 📄 example.cfg                (Kernel Config Fragments)
        │   └── 📄 example.patch              (Kernel source code patch)
        └── 📄 <kernel-recipe>.bbappend       (Includes .cfg and .patch)

Create a git repository for the new layer
Version control with Git is best practice in software development, so we recommend initializing the new meta-layer as a Git repository.
Move into the directory of the new custom layer:

cd ~/workspace/<path-to-ci-meta-tq>/sources/meta-custom
git init
git add .
git commit -m "Initial Commit"

Configure layer priority
The bitbake-layers create-layer script sets a layer priority of 6 by default. To ensure the custom layer has the higher priority, set the priority BBFILE_PRIORITY_meta-custom to a higher value (e.g., “10”) in conf/layer.conf.

BBFILE_PRIORITY_meta-custom = "10"

Adding the new layer to the build
Before the new layer can be used, it must be added to conf/bblayers.conf in the build directory.

echo 'BBLAYERS += "${BSPDIR}/sources/meta-custom"' >> conf/bblayers.conf

The advanced approach is to add packages by creating *.bbappend files to expand the original image recipe (Yocto recipe) without changing it.

In general:

1. Locate the original image recipe (e.g., tq-image-weston-debug.bb). This is typically found in meta-tq/meta-dumpling.
2. Create a .bbappend file in the custom layer that matches the path structure of the original layer, or place it in a generic recipes-images/images/ directory.
   

Create the .bbappend file in custom Yocto layer:

mkdir -p ~/workspace/<path-to-ci-meta-tq>/sources/meta-custom/recipes-images/images
cd ~/workspace/<path-to-ci-meta-tq>/sources/meta-custom/recipes-images/images
touch tq-image-weston-debug.bbappend
nano tq-image-weston-debug.bbappend

Add lines below to the new .bbappend file:

IMAGE_INSTALL:append = " <recipe-name>"
# Example:
IMAGE_INSTALL:append = " nano"

For your .bbappend file to work properly, please keep in mind that you should have removed the package (e.g. nano) from the local.conf file if it was added to the build there before. Rebuild the image:

bitbake tq-image-weston-debug

The Linux kernel configuration is usually defined in a defconfig file (in-tree or out-of-tree) and expanded by TQ-specific fragments.
Using Linux kernel config fragments requires that the kernel recipe is based on linux-yocto.
Create the path:
Recreate the path to the kernel recipe in the custom layer.
Find the kernel recipe corresponding to the machine configuration linux-ti-tq, linux-imx, linux-tq.
Path: ci-meta-tq/sources/meta-custom/recipes-kernel/linux/<kernel-recipe>/<machine>

Menuconfig:
Navigate to the build directory and open menuconfig:

bitbake -c menuconfig virtual/kernel

Diffconfig:
After making changes and saving, create the fragment:

bitbake -c diffconfig virtual/kernel
# The shell will output the path to a fragment.cfg.

Move Fragment:
Move this file to the custom layer path created in Step 1 and rename it (e.g., example.cfg).

Create bbappend:
Create a .bbappend file for the kernel (e.g., <kernel-recipe>.bbappend) in recipes-kernel/linux/ inside the custom layer.

FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:"
SRC_URI += "file://example.cfg"

Rebuild:

bitbake -c cleansstate virtual/kernel 
bitbake tq-image-weston-debug

Creating the patch
1. Navigate to the kernel source directory (usually located in tmp/work-shared/…/kernel-source):

cd ~/workspace/ci-meta-tq/<build-dir>/tmp/work-shared/<machine>/kernel-source

2. Make changes to the source code (e.g., Device Tree in arch/<arch>/boot/dts/…).
3. Create a patch using git:

git diff > example.patch

4. Move example.patch to the custom layer (same path as the .cfg file above).

Add patch to the build
Add the patch to the SRC_URI variable in the kernel .bbappend file (created in the previous section):

FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:"
SRC_URI += "file://example.patch"

Rebuild the kernel and image as described above.

For extensive development, using a local git repository is recommended.

1. Clone sources:
Clone the relevant TQ kernel repository to a local folder (e.g., local_repos).
2. Branch:
Create a custom branch and commit the changes locally.
3. Get Commit ID:
Note the commit ID using git rev-parse HEAD.
4. Update bbappend:
In the meta-custom layer, update the kernel .bbappend to point to the local file path.

# Remove the original upstream source
SRC_URI_remove = "${TQ_GIT_BASEURL}/<repo-name>.git;protocol=${TQ_GIT_PROTOCOL};branch=${SRCBRANCH}"
 
# Add local source
SRC_URI_append = "git://${BSPDIR}/../local_repos/<repo-name>;protocol=file;branch=${SRCBRANCH}"
 
SRCBRANCH = "custom-branch"
SRCREV = "<Commit-ID>"

Finally, rebuild the kernel:

bitbake -c build virtual/kernel