Yocto Recipes

A recipe is file (or set of files) which tells Yocto how to build and include a particular application into a image.

Getting Code From Online Git Repositories

Yocto supports the ability to pull code from online git repositories as part of the build process.

What about private repositories? Private repositories have the added complexity of requiring authentication before you can download (a.k.a clone) them. Luckily, Yocto supports the ssh protocol.

To make Yocto use a GitHub repository:

SRC_URI="git://[email protected]/group_name/repo_name.git;protocol=ssh"

GitLab repositories require a slightly different syntax:

SRC_URI = "git://[email protected]_name.com:~/group_name/repo_name.git;protocol=ssh"

Note the inclusion of ~/ before group_name in the above URL (as well as the inclusion of git:// at the start). This ~/ is important for Yocto to clone the git repo, but is not required (and not included in the GitLab example) when cloning a private GitLab repo normally.

Specifying A Branch

By default, the master branch is used when looking for a particular commit as specified by the SRCREV hash. However, you can change this default behaviour and specify a particular branch by adding the branch=<branch-name> option to the SRC_URI parameter:

SRC_URI = "git://github.com/gbmhunter/SerialFiller;branch=develop"

Checking Out Git Submodules

By default, Yocto will not clone submodules when cloning a git repository. This can be a problem for many builds, as usually dependent libraries are added to git repositories as submodules.

Luckily, Yocto provides a way to tell it to check out all git submodules in a recipe. All you have to do is replace the git:// statement with gitsm://. e.g.

SRC_URI="gitsm://[email protected]/group_name/repo_name.git;protocol=ssh"

A Complete GitHub Example

This is a complete example of a Yocto recipe that downloads and builds the source code from a remote Git repository.

DESCRIPTION = "An example recipe using a remote Git repo."
SECTION = "examples"
DEPENDS = ""
LICENSE = "MIT"
LIC_FILES_CHKSUM = "file://LICENSE;md5=96af5705d6f64a88e035781ef00e98a8"

FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}-${PV}:"

SRCREV = "ed189c8f5a4df717180b1353824d443c382f9587"

## Notice how "http://" has been replaced with "git://"
# NOTE: This is not the same as the SSH address, which
# has the format git@...
SRC_URI = "git://github.com/example/example.git"

S = "${WORKDIR}/git"

## If the repo contains a root-level CMakeLists.txt, this following line is all you need to invoke the build/install process!
inherit cmake

This assumes the CMakeLists.txt contains at least one INSTALL command. bitbake will automatically call cmake, make and make install (if there are no INSTALL commands in the CMakeLists.txt, this part will fail!!!) on the repositories source code.

Licenses

Recipes need to specify LICENSE and LICENSE_FILES_CHKSUM values. This is so that Yocto can guarantee that certain image builds meet specific licensing requirements (e.g. all applications are open-source and free to re-distribute).

Most source code/binary packages and remote repositories will include a LICENSE file in the root directory. Here is an example snippet from a recipe which points to the license file called LICENSE within the root directory of the repository:

LICENSE = "MIT"
LIC_FILES_CHKSUM = "file://LICENSE;md5=96af5705d6f64a88e035781ef00e98a8"

LIC_FILES_CHKSUM is a checksum of a file which includes the license (or, a specific portion of it, e.g. a portion of the README.md). Yocto uses this checksum at build time to make sure the license has not changed, and will produce an error if it has. If the license is an entire file, you can calculate the MD5 checksum by running the following command (in a UNIX system):

~$ md5sum LICENSE

The following directory contains license definitions for most common licenses:

poky/meta/files/common-licenses

This includes BSD, GPL-3.0 and MIT.

Patches

Yocto supports patches, which is a way of modifying third-party code before it is included in the build, without first having to duplicate the source code or ask the maintainer to make the change for you.

Patch icon (band-aid).

Patches can be easily created using Git. If you can download the third-party source code as a Git repository, this is definitely the easiest solution. After downloading the repository, make the required changes to the code, and add these changes to the repository as a new commit. You can then tell Git to make a patch file.

If all the changes are contained within a single additional commit, you can use the following command:

~$ git show HEAD > my-patch.patch

These generated patches should be bundled with your recipe files. The patches should always be in a sub-directory of where the recipe lives. The sub-directory name should either be the same name as the recipe, or the name files (I prefer the name files as it seems more intuitive).

The following diagram shows the correct directory structure for both the recipes (.bb file) and the patch(es) (.patch file(s)). We will pretend we are creating a recipe to include gtest (the Google unit test library) in our image.

meta-example
    |--recipes-example
        |--gtest
        |--gtest_1.7.0.bb
        |--files
            |--my-patch.patch

The last thing you have to do is add a path to your patch in the recipe file.

SRC_URI = "\
    https://github.com/google/googletest/archive/release-1.7.0.zip \
    file://my-patch.patch \
"

Yocto will automatically apply these patches when it needs to build your recipe.