Recipes are the fundamental building block of bitbake and therefore of the yocto project Yocto. Recipes are stored in layers and contain the instructions on how to build a particular piece of software.
...
Another example is libraries being split into -dev (shared objects), -staticdev (static libraries), and -src (source code) packages.
Tasks
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).
Anatomy of a Recipe
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.
The Sources
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.
...
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.
| Codeblock | ||||
|---|---|---|---|---|
| ||||
SRC_URI = "file://helloworld.c file://Makefile" |
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.
The Source Directory
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"Patches
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 and Installation
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:
...
For makefile based projects, see Building a Makefile-Based Package.
Appending a Function
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
...
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).
Creating a Recipe using devtool
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:
...
The recipe can now be built using
bitbake <recipe-name>
Manually Creating a Recipe
Manual creation of recipes may be required when devtool fails to automatically create one.
Adding a Recipe to the Layer
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:
...
Now running bitbake core-image-minimal should run without errors and the image should include a hello executable that prints Hello World when executed.
Using cmake
replace inherit autotools from above with the following:
...
OECMAKE_FIND_ROOT_PATH_MODE_PROGRAM = „BOTH“ allows cmake to find git from within yocto, otherwise cmake will generate an error (missing: GIT_EXECUTABLE).
Additional Information
https://wiki.yoctoproject.org/wiki/Building_your_own_recipes_from_first_principles
Adding a kernel module
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.
...