Building custom Yocto Linux distribution: adding recipes

Writing recipe

In previous article we have created custom Yocto image that was basically identical to st-image-core, but with added Vim editor. In this article we will extend our image and include custom application, specifically I will be building new version of dashboard for electric motorcycle (the previous one is described here).

Custom applications are added to Yocto using recipes. Recipes are files that specify how to download, compile and package software into Yocto images. Let’s start with adding a new recipe to meta-cybbed layer:

$ mkdir -p recipes-gui/pygui/
$ touch recipes-gui/pygui/pygui_1.0.bb

Below is pygui_1.0.bb structure:

DESCRIPTION = "Cybbed electric motorcycle GUI based on Python TkInter"
HOMEPAGE = "https://bitbucket.org/rostokus/emoto_ui_firmware"

# Recipe license type
LICENSE = "GPL-2.0-or-later"
LIC_FILES_CHKSUM ?= "file://${COMMON_LICENSE_DIR}/GPL-2.0-or-later;md5=fed54355545ffd980b814dab4a3b312c"

# Set package name
PN = "pygui"

# Specify external dependencies
RDEPENDS:${PN} = "python3 python3-pillow tcl"

# Git repo details
SRCBRANCH = "stm32mp1_port"
SRCREV = "f445e30f0c96e8fd2afa6d8ed6a8c2b08d29b3bb"

# Source location
SRC_URI = "git://git@bitbucket.org/rostokus/emoto_ui_firmware.git;protocol=ssh;branch=${SRCBRANCH}"

# If SRC_URI is set to git, set "S" as follows
S = "${WORKDIR}/git"

# Install files to rootfs
do_install() {
  install -d ${D}/home/root/gui
  install -m 755 ${S}/*.py ${D}/home/root/gui
  cp -r ${S}/icons/ ${D}/home/root/gui
}

# Add files to image
FILES:${PN} = "/home/root/gui/*"

Recipe begins with DESCRIPTION section which provides general details. If you want to include WEB address of the project in the recipe use HOMEPAGE variable.

Recipes can have different software licenses so one must set the correct value in LICENSE variable. I suggest looking at layers/openembedded-core/meta/files/common-licenses for available options. Note that if you want to ignore the license you can set it to CLOSED.
LIC_FILES_CHKSUM – location of the license file and it’s checksum. File can be download from remote source or located locally. The checksum help to ensure that if license text has changed, this will not go unnoticed as bitbake will trigger a build error if this is detected.

PN variable sets package name. This name is used, for example, when referring to this package from bitbake, for example, it is possible to type “bitbake pygui” instead of “bitbake pygui_1.0”.

RDEPENDS:${PN} specify which external packages are required to run pygui. In case if recipe has compile-time dependencies – set them using DEPENDS variable.

Recipe has to specify the location of source files which will be download (or copy if sources are located locally) during Yocto image build. This is set using SRC_URI variable. Sources can be download from local location, remote git repository, via http(s), ssh, etc. Details can be found here.
When selecting git as a source, additionally set branch using SRCBRANCH variable and commit ID via SRCREV.

By default, Git repositories are cloned to ${WORKDIR}/git during download. Since this path is different from the default value of S, S must be redefined to point to correct location with sources.

Recipes based on python does not require configuration/compilation as would normally be done for make/cmake recipes, so here we only define do_install function which will copy python files and additional data to rootfs.

Files that are located in rootfs are not automatically added to Yocto image, unless they are listed in FILES:${PN} variable.

Rebuilding image

Once recipe is created we need to add it to image. For this open file st-image-cybbed.bb and add pygui recipe to IMAGE_INSTALL.

...
# Additional software to be included in image
IMAGE_INSTALL += "vim pygui"
...

Tkinter requires python3 to be built with tk (details here), let’s update python3 recipe by adding corresponding bbappend file – layers/meta-cybbed/recipes-devtools/python/python3_%.bbappend.

PACKAGECONFIG:append:pn-python3 = " tk"

Build the image and flash to board:

$ bitbake st-image-cybbed
$ ./flash.sh /dev/mmcblk0

Once the SD card is flashed with new image, boot the board and ensure that pygui files were successfully installed.

$ # ls -la gui/
total 37
drwxr-xr-x 4 root root  1024 Apr 28 17:43 .
drwx------ 3 root root  1024 Apr 28 17:43 ..
drwxr-xr-x 2 root root  1024 Apr 28 17:43 __pycache__
-rwxr-xr-x 1 root root   616 Mar  9  2018 crc.py
-rwxr-xr-x 1 root root 32686 Mar  9  2018 emoto_dash.py
drwxr-xr-x 2 root root  1024 Mar  9  2018 icons

Important to mention that current image is not capable of displaying GUI application as it lacks graphical framework support. In next article, we will create new Yocto image with Weston support and add pygui to systemd so that our application automatically starts at linux boot.