Richard Purdie, Chris Larson, and Phil Blundell, BitBake
Community <bitbake-devel@lists.openembedded.org>
by Richard Purdie, Chris Larson, and Phil Blundell
Copyright © 2004-2015 Richard Purdie, Chris Larson, and Phil Blundell
This work is licensed under the Creative Commons Attribution License. To view a copy of this license, visit
http://creativecommons.org/licenses/by/2.5/ or send a letter to Creative Commons, 444 Castro Street, Suite 900,
Mountain View, California 94041, USA.
iii
Table of Contents
1. Overview ............................................................................................................................... 1
1.1. Introduction ................................................................................................................ 1
1.2. History and Goals ....................................................................................................... 1
1.3. Concepts .................................................................................................................... 2
1.3.1. Recipes ............................................................................................................ 2
1.3.2. Configuration Files ........................................................................................... 3
1.3.3. Classes ............................................................................................................ 3
1.3.4. Layers ............................................................................................................. 3
1.3.5. Append Files .................................................................................................... 3
1.4. Obtaining BitBake ....................................................................................................... 4
1.5. The BitBake Command ............................................................................................... 4
1.5.1. Usage and syntax ............................................................................................ 5
1.5.2. Examples ......................................................................................................... 6
2. Execution .............................................................................................................................. 8
2.1. Parsing the Base Configuration Metadata .................................................................... 8
2.2. Locating and Parsing Recipes .................................................................................... 10
2.3. Providers .................................................................................................................. 11
2.4. Preferences ............................................................................................................... 11
2.5. Dependencies ........................................................................................................... 12
2.6. The Task List ............................................................................................................ 12
2.7. Executing Tasks ........................................................................................................ 13
2.8. Checksums (Signatures) ............................................................................................ 13
2.9. Setscene ................................................................................................................... 15
3. Syntax and Operators .......................................................................................................... 16
3.1. Basic Syntax ............................................................................................................. 16
3.1.1. Basic Variable Setting .................................................................................... 16
3.1.2. Variable Expansion ......................................................................................... 16
3.1.3. Setting a default value (?=) ........................................................................... 16
3.1.4. Setting a weak default value (??=) ................................................................. 17
3.1.5. Immediate variable expansion (:=) ................................................................. 17
3.1.6. Appending (+=) and prepending (=+) With Spaces ......................................... 17
3.1.7. Appending (.=) and Prepending (=.) Without Spaces ....................................... 17
3.1.8. Appending and Prepending (Override Style Syntax) ......................................... 18
3.1.9. Removal (Override Style Syntax) .................................................................... 18
3.1.10. Variable Flag Syntax ..................................................................................... 18
3.1.11. Inline Python Variable Expansion .................................................................. 19
3.1.12. Providing Pathnames .................................................................................... 19
3.2. Conditional Syntax (Overrides) .................................................................................. 19
3.2.1. Conditional Metadata ..................................................................................... 19
3.2.2. Key Expansion ............................................................................................... 20
3.2.3. Examples ....................................................................................................... 20
3.3. Sharing Functionality ................................................................................................. 21
3.3.1. Locating Include and Class Files ..................................................................... 22
3.3.2. inherit Directive .......................................................................................... 22
3.3.3. include Directive .......................................................................................... 22
3.3.4. require Directive .......................................................................................... 22
3.3.5. INHERIT Configuration Directive ..................................................................... 23
3.4. Functions .................................................................................................................. 23
3.4.1. Shell Functions ............................................................................................... 23
3.4.2. BitBake Style Python Functions ....................................................................... 24
3.4.3. Python Functions ............................................................................................ 24
3.4.4. Anonymous Python Functions ......................................................................... 24
3.4.5. Flexible Inheritance for Class Functions ........................................................... 25
3.5. Tasks ........................................................................................................................ 26
3.5.1. Promoting a Function to a Task ....................................................................... 26
3.5.2. Deleting a Task .............................................................................................. 26
3.5.3. Passing Information Into the Build Task Environment ....................................... 26
3.6. Variable Flags ........................................................................................................... 27
3.7. Events ...................................................................................................................... 28
3.8. Variants - Class Extension Mechanism ....................................................................... 29
3.9. Dependencies ........................................................................................................... 30
BitBake User Manual
iv
3.9.1. Dependencies Internal to the .bb File ............................................................. 30
3.9.2. Build Dependencies ........................................................................................ 30
3.9.3. Runtime Dependencies ................................................................................... 30
3.9.4. Recursive Dependencies ................................................................................. 31
3.9.5. Inter-Task Dependencies ................................................................................. 31
3.10. Accessing Datastore Variables Using Python ............................................................ 31
3.11. Task Checksums and Setscene ................................................................................ 32
4. File Download Support ......................................................................................................... 33
4.1. The Download (Fetch) ............................................................................................... 33
4.2. The Unpack .............................................................................................................. 35
4.3. Fetchers .................................................................................................................... 35
4.3.1. Local file fetcher (file://) ............................................................................ 35
4.3.2. HTTP/FTP wget fetcher (http://, ftp://, https://) ....................................... 35
4.3.3. CVS fetcher ((cvs://) ................................................................................... 36
4.3.4. Subversion (SVN) Fetcher (svn://) ................................................................. 37
4.3.5. Git Fetcher (git://) ...................................................................................... 37
4.3.6. Git Submodule Fetcher (gitsm://) ................................................................. 38
4.3.7. ClearCase Fetcher (ccrc://) .......................................................................... 38
4.3.8. Other Fetchers ............................................................................................... 39
4.4. Auto Revisions .......................................................................................................... 39
5. Variables Glossary ............................................................................................................... 40
A. Hello World Example ........................................................................................................... 57
A.1. BitBake Hello World .................................................................................................. 57
A.2. Obtaining BitBake ..................................................................................................... 57
A.3. Setting Up the BitBake Environment .......................................................................... 57
A.4. The Hello World Example .......................................................................................... 58
1
Chapter1.Overview
Welcome to the BitBake User Manual. This manual provides information on the BitBake tool. The
information attempts to be as independent as possible regarding systems that use BitBake, such as
OpenEmbedded and the Yocto Project. In some cases, scenarios or examples within the context of a
build system are used in the manual to help with understanding. For these cases, the manual clearly
states the context.
1.1.Introduction
Fundamentally, BitBake is a generic task execution engine that allows shell and Python tasks to be
run efficiently and in parallel while working within complex inter-task dependency constraints. One
of BitBake's main users, OpenEmbedded, takes this core and builds embedded Linux software stacks
using a task-oriented approach.
Conceptually, BitBake is similar to GNU Make in some regards but has significant differences:
• BitBake executes tasks according to provided metadata that builds up the tasks. Metadata is stored
in recipe (.bb) and related recipe "append" (.bbappend) files, configuration (.conf) and underlying
include (.inc) files, and in class (.bbclass) files. The metadata 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 local files,
source control systems, or websites.
• The instructions for each unit to be built (e.g. a piece of software) are known as "recipe" files
and contain all the information about the unit (dependencies, source file locations, checksums,
description and so on).
• BitBake includes a client/server abstraction and can be used from a command line or used as a
service over XML-RPC and has several different user interfaces.
1.2.History and Goals
BitBake was originally a part of the OpenEmbedded project. It was inspired by the Portage package
management system used by the Gentoo Linux distribution. On December 7, 2004, OpenEmbedded
project team member Chris Larson split the project into two distinct pieces:
• BitBake, a generic task executor
• OpenEmbedded, a metadata set utilized by BitBake
Today, BitBake is the primary basis of the OpenEmbedded [http://www.openembedded.org/] project,
which is being used to build and maintain Linux distributions such as the Angstrom Distribution [http://
www.angstrom-distribution.org/], and which is also being used as the build tool for Linux projects such
as the Yocto Project [http://www.yoctoproject.org].
Prior to BitBake, no other build tool adequately met the needs of an aspiring embedded Linux
distribution. All of the build systems used by traditional desktop Linux distributions lacked important
functionality, and none of the ad hoc Buildroot-based systems, prevalent in the embedded space,
were scalable or maintainable.
Some important original goals for BitBake were:
• Handle cross-compilation.
• Handle inter-package dependencies (build time on target architecture, build time on native
architecture, and runtime).
• Support running any number of tasks within a given package, including, but not limited to, fetching
upstream sources, unpacking them, patching them, configuring them, and so forth.
• Be Linux distribution agnostic for both build and target systems.