Recipes are the fundamental building block of bitbake and therefore of the yocto project. Recipes are stored in layers and contain the instructions on how to build a particular piece of software.
There should be a recipe for each 'thing' to be built. Usually this means that one recipe builds one package, but a single recipe can also build multiple packages.
For example, libraries are usually described by several different packages. For example, a repository might contain code for the library and also some utility programs that use this library. Here it may make sense to create 2 packages: myLib and myLib-utils, where the former contains the library and the latter contains the utility programs.
Another example is libraries being split into -dev (shared objects), -staticdev (static libraries), and -src (source code) packages.
Each recipe undergoes multiple stages while being built:
| name | function | description |
|---|---|---|
| fetch | do_fetch* | fetch sources |
| unpack | do_unpack* | unpack sources |
| patch | do_patch | apply patches (if any) |
| compile | do_compile | build from sources |
| install | do_install | install into temporary destination |
| package | do_package | package installed files into their package(s) |
| package_qa | do_package_qa | perform sanity checks on package |
*: it seems that do_fetch and do_unpack can not be modified/overridden in a recipe. More about overriding see below.
Each of the listed functions is called when building the package, or can explicitly be invoked using
bitbake <recipe-name> -c <name>
where <name> corresponds to a name in the 'name' column above.
They can also be customized in the recipe by appending their corresponding functions (see below).
In essence, a recipe needs to provide 4 things:
This information is contained in a bitbake recipe file, with .bb as a file extension.
This file is plain text adhering to its own syntax to specify all things needed by bitbake.
Almost all recipes need some source code or other source from which to build the software.
In bitbake this step is called fetch.
Sources are specified by setting the SRC_URI variable and can be fetched from a variety of sources.
For example, setting SRC_URI as shown below will fetch 2 local files heloworld.c and Makefile.
There is a variety of fetchers available for downloading files from the internet or cloning git repositories and more. Each has their own requirements and options, which can be found here.
SRC_URI = "file://helloworld.c file://Makefile"
SRC_URI contains a list of all sources needed by the recipe deliminated by spaces. Each source entry starts with its fetcher and then its source location.
Note that '\' before a line break can be used to allow the list to span multiple lines like so:
SRC_URI = " \ file://helloworld.c \ file://Makefile \ "
This is often used in recipes with multiple sources, since it significantly increases readablitity with multiple sources, especially when URLs are involved.
Each recipe needs to explicitly set its source directory S.
This is will be a subdirectory of WORKDIR, the recipe's working directory, but the specific location depends on the fetchers and recipe.
If the source is a git repository, S needs to be set to
S = "${WORKDIR}/git"
When a source entry ends in .patch or patch.xz (and probably other similar extensions) it is recognized it as a patch and will automatically be applied when calling do_patch, which is invoked before compilation or explicitly by using bitbake <recipe-name> -c patch.
Building usually consists of 2 steps: configuration and the actual build itself. bitbake comes with classes to handle standard build systems such as cmake and autotools. These can be used by inheriting from them. For cmake based projects:
inherit cmake
or for autotools based projects:
inherit autotools
For makefile based projects, see Building a Makefile-Based Package.
Sometimes it is necessary to perform extra steps for a particular task. This can be achieved by appending custom commands to a function. The syntax for this is
<function>_append () {
# shell commands go here
}
for example
do_install_append () {
install -d ${D}/usr/bin/
install -m 755 my_extra_executable ${D}/usr/bin
}
D is the destination direcory, which points to the package's install directory.
All destination paths must be relative to it to end up in the right place to be packaged (this is unique to do_install, the other functions should not need to access D).
devtool is a command line utility that comes with yocto that can be used to facilitate development. One of the things it can be used for is semi-automatically creating recipes using the following command:
devtool add <src> [name]
The name is optional, as devtool will try to infer it from the source (e.g. from the name of the repository). If it fails to infer one, it will return an error asking to specify one.
If successful, the recipe can be found in build/workspace/recipes/<recipe-name>.
devtool will also print where it placed the recipe for further modification.
The recipe can now be built using
bitbake <recipe-name>
Manual creation of recipes may be required when devtool fails to automatically create one.
bitbake will look for recipes in any sub directory of recipes-ost, but not in recipes-ost itself! Create a folder inside recipes-ost called helloworld and inside that create a file called helloworld_1_0.bb with the following content:
DESCRIPTION = "Example Hello World"
SECTION = "ost"
DEPENDS = ""
LICENSE = "MIT"
LIC_FILES_CHKSUM = "file://LICENSE;md5=96af5705d6f64a88e035781ef00e98a8"
FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}-${PV}:"
SRCREV = "b9fb7785e9e1f357f29bef63dce8f1d91adb6170"
SRC_URI = "git://github.com/DynamicDevices/bbexample.git"
S = "${WORKDIR}/git"
inherit autotools
bitbake is very particular about licenses to ensure no closed source software ends up in a project that only wants open source software. Hence the recipe needs to specify the license used (MIT in this case) and a checksum for the license file to ensure it has not been altered. All this is handled by the LIC_FILES_CHKSUM field. The other two interesting fields are SRC_URI and SRC_REV. SRC_URI specifies where the source for the application/module/… for this recipe is. In this case git:// lets bitbake know the source lives in a git repository. Note that https:// will not work. Also note that inherit autotools is only necessary because the hello world uses autotools.
To add the new recipe to the build edit oe-core/build/conf/local.conf and append IMAGE_INSTALL_append = „ helloworld“ (make sure to include the space before helloworld).
Now running bitbake core-image-minimal should run without errors and the image should include a hello executable that prints Hello World when executed.
replace inherit autotools from above with the following:
inherit cmake OECMAKE_FIND_ROOT_PATH_MODE_PROGRAM = "BOTH"
OECMAKE_FIND_ROOT_PATH_MODE_PROGRAM = „BOTH“ allows cmake to find git from within yocto, otherwise cmake will generate an error (missing: GIT_EXECUTABLE).
This part is an extension of the previous and assumes the meta-ost layer exists and was added to bblayers.conf as described above. This part uses the fpga_loader kernel module to demonstrate how to add an out-of-tree kernel module to yocto.
Create a new directory recipes-kernel under meta-ost and in that create another folder inside that called fpga-loader. Create a file called fpga-loader_1.0.bb in fpga-loader and add the following content:
DESCRIPTION = "FPGA Loader Kernel Module"
SECTION = "ost"
DEPENDS = ""
LICENSE = "CLOSED"
FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}-${PV}:"
SRCREV = "df83789290cd8fe8b9d9af8dd7ad509ea25c6b46"
SRC_URI = "git://github.com/zechenturm/fpga_loader.git"
S = "${WORKDIR}/git"
inherit module
export KERNELDIR="${KERNEL_SRC}"
Since there is no LICENSE file in the fpga-loader git repository, the simplest way to not have bitbake complain about it is to set LICENSE to CLOSED even though it actually is open (source). Note that in comparison with helloworld there is no inherit autotools since fpga-loader does not rely on autotools. However, thjere is inherit module which lets bitbake know that this recipe is building a kernel module.
Since fpga_modules Makefile uses KERNELDIR but yocto uses KERNEL_SRC, KERNEL_DIR needs to be explicitly set in the recipe for the build to succeed.
Finally, fpga-loader needs to be added to the image in oe-core/build/conf/local.conf:
IMAGE_INSTALL_append = " fpga-loader" MACHINE_EXTRA_RRECOMMENDS = " kernel-modules"
While IMAGE_INSTALL_append was sufficient for helloworld, kernel modules need an extra step to make sure kernel modules are included in the image/rootfs. By default, minimal yocto images do not include them which would mean that fpga-loader would be built but not added to the rootfs. Setting MACHINE_EXTRA_RECOMMENDS = „ kernel-modules“ ensures they are included.