BitBake is a program written in the Python language that interprets metadata, decides what tasks are required to run, and executes those tasks. Similar to GNU Make, BitBake controls how software is built. GNU Make achieves its control through “makefiles”. BitBake uses “recipes”.
BitBake executes tasks according to provided metadata that builds up the tasks.
Metadata is stored in recipe (.bb), configuration (.conf), and class (.bbclass) files and provides BitBake with instructions on what tasks to run and the dependencies between those tasks. BitBake includes a fetcher library for obtaining source code from various places such as source control systems or websites.
Useful BitBake Commads
| bitbake <image> Bake an image (add -k to continue building even errors are found in the tasks execution) |
| bitbake <package> -c <task> Execute a particular package’s task. Default Tasks names: fetch, unpack, patch, configure, compile, install, package, package_write, and build. Example: To (force) compiling a kernel and then build, type: bitbake linux-imx -f -c compile bitbake linux-imx |
| bitbake <package> -c listtasks List all tasks for package |
| bitbake -c clean foo bitbake -c cleanall foo -c clean: cleans up the build artifacts for the specified recipe, but leaves downloaded source code and intermediate files intact. This can be useful if you want to rebuild the recipe from scratch, but don’t want to download the source code again. -c cleanall: cleans up all build artifacts for the specified recipe, including downloaded source code and intermediate files. This can be useful if you want to completely clean up the build environment and start over from scratch. |
| bitbake -f -c compile foo Forces bitbake to compile the specified recipe from scratch, even if its output files are already up-to-date. |
| bitbake -e foo Prints out the environment variables and their values used by bitbake when building the specified recipe. |
| bitbake-layers show-layers Displays information about the OpenEmbedded layers being used in the current project. This can be useful if you want to see a list of the layers being used, their priorities, and their locations. The layer priority determines the order in which the layers are searched for recipes and other metadata, and can have an impact on the build process and the resulting images. |
| bitbake-layers show-recipes <“*-image-*”> Display a list of available recipes that can be used to build packages for the target system. Parse all the recipe files in the Yocto Project and output a list of available recipes that can be built. The output includes the name of each recipe, its version, and a brief description of what it does. This command is useful for finding out what recipes are available for building and for identifying the names of recipes that can be added to your build configuration. When “*-image-*” is used, bitbake-layers will search for all available image recipes that match the pattern “-image-” and display a list of them. |
| bitbake-layers show-appends <recipe-name > Displays information about the (layer append/ bbappend )files being used in the current project. <recipe-name>: This specifies the name of the recipe to display information about |
| bitbake -s | grep <pkg> Lists all the available recipes that can be built by the bitbake build. The grep command is used as filter to check if certain package is available in the BitBake project, and if so, what its name is. |
| bitbake <package> -c devshell e.g bitbake busybox -c devshell Launches an interactive shell session within the build environment of the specified package. |
| bitbake virtual/kernel -c menuconfig Opens the Linux kernel configuration menu in an interactive session, allowing you to configure various kernel options for the specified target architecture. |
| bitbake –v <image> 2>&1 | tee image_build.log Builds the specified image with verbose output and saves the output to a log file named “image_build.log”. The output can also be seen on the screen. |
| bitbake -g pkg BitBake reads the metadata for the specified package and its dependencies in the current build environment and generates a dependency graph in DOT format. The graph shows the relationships between targets, such as recipes, tasks, and files, for the specified package. bitbake -g <image/pkg> && cat dependencies.dot | grep -v -e ‘-native’ | grep -v digraph | grep -v -e ‘-image’ | awk ‘{print $1}’ | sort | uniq Show image/package dependency packages |
Recipes
Recipes are denoted by the file extension .bb, are the most basic metadata files.
These recipe files provide BitBake with the following:
- Descriptive information about the package
- The version of the recipe
- Existing Dependencies
- Where the source code resides
- Whether the source code requires any patches
- How to compile the source code
- Where on the target machine to install the package being compiled
Configuration Files
Configuration files, which are denoted by the .conf extension, define various configuration variables that govern the project’s build process. These files fall into several areas that define machine configuration options, distribution configuration options, compiler tuning options, general common configuration options, and user configuration options. The main configuration file is the sample bitbake.conf file, which is located within the BitBake source tree conf directory.
Classes
Class files, which are denoted by the .bbclass extension, contain information that is useful to share between metadata files. The BitBake source tree currently comes with one class metadata file called base.bbclass. The base.bbclass is special since it is always included automatically for all recipes and classes. This class contains definitions for standard basic tasks such as fetching, unpacking, configuring (empty by default), compiling (runs any Makefile present), installing (empty by default) and packaging (empty by default). These tasks are often overridden or extended by other classes added during the project development process.
Layers
Layers allows to isolate different types of customizations from each other.
To illustrate how layers can be used to keep things modular, consider customizations to support a specific target machine. These types of customizations typically reside in a special layer, rather than a general layer, called a Board Specific Package (BSP) Layer. Furthermore, the machine customizations should be isolated from recipes and metadata that support a new GUI environment, for example. This situation gives a couple of layers: one for the machine configurations and one for the GUI environment.
It is important to note that that the BSP layer can still make machine-specific additions to recipes within the GUI environment layer without polluting the GUI layer itself with those machine-specific changes. You can accomplish this through a recipe that is a BitBake append (.bbappend) file.
Append Files
Append files, which are files that have the .bbappend file extension, add or extend build information to an existing recipe file.
BitBake expects every append file to have a corresponding recipe file. Furthermore, the append file and corresponding recipe file must use the same root filename. The filenames can differ only in the file type suffix used (e.g. formfactor_0.0.bb and formfactor_0.0.bbappend).
Information in append files overrides the information in the similarly-named recipe file.
Wildcard character (%) are used for matching recipe names. For example, foo_1.41.%.bbappend append file would match any foo_1.41.x.bb version of the recipe like foo_1.41.1.bb, foo_1.41.2.bb, foo_1.41.3.bb recipes. But it will not match foo_1.35.bb.