Customization
Create a layer
In Yocto a layer can be seen as a collection of related recipes (instructions) that tell the build system what to do. As an example,
Embedded Artists created the layer meta-ea-rz to contain all recipes needed to build an image for one of our boards.
For these instructions you should first have built an image as described in Build Images chapter. We are using the
name meta-example in these examples. Change this to the name you want to use for your layer.
Create the layer
The instruction is run from the build directory and the layer will be created in the sources directory.
bitbake-layers create-layer ../sources/meta-example
The meta-example layer will be created with a number of files including an example recipe. The directory structure will look like below.
meta-example
| -- conf
| | -- layer.conf
| -- COPYING.MIT
| -- README
| -- recipes-example
| | -- example
| | | -- example_0.1.bb
Add the layer
The previous instruction only created the layer, but you also need to add it to the build. You can do this by either manually editing <build-dir>/conf/bblayers.bb or running the command below.
bitbake-layers add-layer ../sources/meta-example
The disadvantage of running bitbake-layers is that it will add the layer with an absolute path and not a relative path as the other layers in bblayers.conf. Below is an example of bblayers.conf were meta-example has been added using bitbake-layers.
...
#Embedded Artists Yocto layer
BBLAYERS += "${TOPDIR}/../sources/meta-ea-rz "
BBLAYERS += "${TOPDIR}/../sources/meta-ea-dx "
BBLAYERS += "${TOPDIR}/../sources/meta-rz-features/meta-rz-codecs "
BBLAYERS += "${TOPDIR}/../sources/meta-rz-features/meta-rz-graphics "
BBLAYERS += "/home/user/builds/build-dir/sources/meta-example"
Version control
It is recommended that you add your new layer to a version-controlled repository such as GitHub. It is out of the scope of this document to describe how you do this, but there are many guides online such as the link below that describes how to create a new repository on GitHub.
https://docs.github.com/en/get-started/quickstart/create-a-repo
By adding the layer to a repository, you can also add it to a repo manifest that will keep track of all repositories needed to do a full Yocto image. Embedded Artists has created the repository ea-rz-manifest that contains a repo manifest. See an example by following the link below.
https://github.com/embeddedartists/ea-rz-manifest/blob/scarthgap/default.xml#L16
Create a recipe
It is the recipe that contains the settings and tasks needed to build a package. The recipe contains the information about where the source code can be found, which version to use and if any patches should be applied. It can also specify dependencies to other recipes.
When a new layer was created in the Create a layer section an example recipe was also created. This example only contains one .bb file which will print a message during the build.
example_0.1.bb
SUMMARY = "bitbake-layers recipe"
DESCRIPTION = "Recipe created by bitbake-layers"
LICENSE = "MIT"
python do_build() {
bb.plain("***********************************************");
bb.plain("* *");
bb.plain("* Example recipe created by bitbake-layers *");
bb.plain("* *");
bb.plain("***********************************************");
}
A better example is to create a recipe that will build and install a hello world application. The instructions below are based on the example described in Yocto’s official documentation.
https://docs.yoctoproject.org/dev-manual/new-recipe.html#building-a-single-c-file-package
Create recipe directory
Within the meta-example layer create the directories needed for the new recipe. The first directory, recipes-example, is a container directory where you can put several recipes (using the same directory as was created when creating the layer). The directory hello-world is the actual recipe directory for this example. The sub-directory files will contain the source code, helloworld.c in this example.
cd ../sources/meta-example
mkdir -p recipes-example/hello-world/files
Create recipe file
Create a file called hello-world.bb within the hello-world directory. The content of the file should be as shown below.
SUMMARY = "Simple helloworld application"
SECTION = "examples"
LICENSE = "MIT"
LIC_FILES_CHKSUM =
"file://${COMMON_LICENSE_DIR}/MIT;md5=0835ade698e0bcf8506ecda2f7b4f302"
SRC_URI = "file://helloworld.c"
S = "${WORKDIR}"
do_compile() {
${CC} helloworld.c -o helloworld
}
do_install() {
install -d ${D}${bindir}
install -m 0755 helloworld ${D}${bindir}
}
INSANE_SKIP_${PN} = "ldflags"
The recipe file begins with short description of the recipe and also specifies which license that will apply.
The file continues with specifying the path to the source code (SRC_URI). It only lists the name of the file, but Yocto will know to look for this file in the sub-directory files.
Then comes the compile and install steps. In do_compile the file will be compiled into an executable program and in do_install the program will be installed into the file system at the location defined by ${bindir} (typically /usr/bin).
The last line (INSANE_SKIP_${PN}) was added to skip ldflags. Without this line, QA errors were generated (like below).
ERROR: hello-world-1.0-r0 do_package_qa: QA Issue: No GNU_HASH in the elf binary:
Create helloworld.c
Within hello-world/files create the file helloworld.c and add the content below to that file.
#include <stdio.h>
int main() {
printf("Hello world\n");
return 0;
}
Build the recipe
You can now try to build the recipe by running the command below from your build directory
cd ../../<build-dir>
bitbake hello-world
To make sure the hello world application is included in the image you are building add the following to conf/local.conf.
IMAGE_INSTALL:append = " hello-world"
Then build the image (in this example we are using ea-image-base, but you can change to the image you are using).
bitbake ea-image-base
Add content or change behavior of existing recipe
It is possible to modify an existing recipe by using a bbappend file. This avoids duplication of functionality and allows for modifying a recipe from another layer. One common usage of bbappend files is to apply patches to existing recipes without having to modify the original source.
As an example of a bbappend file, this is opencv_%.bbappend:
PACKAGECONFIG:append = " gtk"
All the bbappend file does is to add the " gtk" to the PACKAGECONFIG flag (needed to get the correct backend for opencv).
The original file can be found on GitHub.
More information in the Yocto documentation:
https://docs.yoctoproject.org/kernel-dev/common.html#creating-the-append-file