Chapter 2. Metadata

Table of Contents

Description
Basic variable setting
Variable expansion
Immediate variable expansion (:=)
Appending (+=) and prepending (=+)
Appending (.=) and prepending (=.) without spaces
Conditional metadata set
Conditional appending
Inclusion
Requiring Inclusion
Python variable expansion
Defining executable metadata
Defining python functions into the global python namespace
Variable Flags
Inheritance
Tasks
Events
Dependency Handling
Dependencies internal to the .bb file
DEPENDS
RDEPENDS
Recursive DEPENDS
Recursive RDEPENDS
Inter Task
Parsing
Configuration Files
Classes
.bb Files

Description

BitBake metadata can be classified into 3 major areas:

  • Configuration Files

  • .bb Files

  • Classes

What follows are a large number of examples of BitBake metadata. Any syntax which isn't supported in any of the aforementioned areas will be documented as such.

Basic variable setting

VARIABLE = "value"

In this example, VARIABLE is value.

Variable expansion

BitBake supports variables referencing one another's contents using a syntax which is similar to shell scripting

A = "aval"
B = "pre${A}post"

This results in A containing aval and B containing preavalpost.

Immediate variable expansion (:=)

:= results in a variable's contents being expanded immediately, rather than when the variable is actually used.

T = "123"
A := "${B} ${A} test ${T}"
T = "456"
B = "${T} bval"

C = "cval"
C := "${C}append"

In that example, A would contain test 123, B would contain 456 bval, and C would be cvalappend.

Appending (+=) and prepending (=+)

B = "bval"
B += "additionaldata"
C = "cval"
C =+ "test"

In this example, B is now bval additionaldata and C is test cval.

Appending (.=) and prepending (=.) without spaces

B = "bval"
B .= "additionaldata"
C = "cval"
C =. "test"

In this example, B is now bvaladditionaldata and C is testcval. In contrast to the above Appending and Prepending operators no additional space will be introduced.

Conditional metadata set

OVERRIDES is a : seperated variable containing each item you want to satisfy conditions. So, if you have a variable which is conditional on arm, and arm is in OVERRIDES, then the arm specific version of the variable is used rather than the non-conditional version. Example:

OVERRIDES = "architecture:os:machine"
TEST = "defaultvalue"
TEST_os = "osspecificvalue"
TEST_condnotinoverrides = "othercondvalue"

In this example, TEST would be osspecificvalue, due to the condition os being in OVERRIDES.

Conditional appending

BitBake also supports appending and prepending to variables based on whether something is in OVERRIDES. Example:

DEPENDS = "glibc ncurses"
OVERRIDES = "machine:local"
DEPENDS_append_machine = " libmad"

In this example, DEPENDS is set to glibc ncurses libmad.

Inclusion

Next, there is the include directive, which causes BitBake to parse in whatever file you specify, and insert it at that location, which is not unlike make. However, if the path specified on the include line is a relative path, BitBake will locate the first one it can find within BBPATH.

Requiring Inclusion

In contrast to the include directive, require will raise an ParseError if the to be included file can not be found. Otherwise it will behave just like the include directive.

Python variable expansion

DATE = "${@time.strftime('%Y%m%d',time.gmtime())}"

This would result in the DATE variable containing today's date.

Defining executable metadata

NOTE: This is only supported in .bb and .bbclass files.

do_mytask () {
    echo "Hello, world!"
}

This is essentially identical to setting a variable, except that this variable happens to be executable shell code.

python do_printdate () {
    import time
    print time.strftime('%Y%m%d', time.gmtime())
}

This is the similar to the previous, but flags it as python so that BitBake knows it is python code.

Defining python functions into the global python namespace

NOTE: This is only supported in .bb and .bbclass files.

def get_depends(bb, d):
    if bb.data.getVar('SOMECONDITION', d, True):
        return "dependencywithcond"
    else:
        return "dependency"

SOMECONDITION = "1"
DEPENDS = "${@get_depends(bb, d)}"

This would result in DEPENDS containing dependencywithcond.

Variable Flags

Variables can have associated flags which provide a way of tagging extra information onto a variable. Several flags are used internally by bitbake but they can be used externally too if needed. The standard operations mentioned above also work on flags.

VARIABLE[SOMEFLAG] = "value"

In this example, VARIABLE has a flag, SOMEFLAG which is set to value.

Inheritance

NOTE: This is only supported in .bb and .bbclass files.

The inherit directive is a means of specifying what classes of functionality your .bb requires. It is a rudamentary form of inheritence. For example, you can easily abstract out the tasks involved in building a package that uses autoconf and automake, and put that into a bbclass for your packages to make use of. A given bbclass is located by searching for classes/filename.oeclass in BBPATH, where filename is what you inherited.

Tasks

NOTE: This is only supported in .bb and .bbclass files.

In BitBake, each step that needs to be run for a given .bb is known as a task. There is a command addtask to add new tasks (must be a defined python executable metadata and must start with do_) and describe intertask dependencies.

python do_printdate () {
    import time
    print time.strftime('%Y%m%d', time.gmtime())
}

addtask printdate before do_build

This defines the necessary python function and adds it as a task which is now a dependency of do_build (the default task). If anyone executes the do_build task, that will result in do_printdate being run first.

Events

NOTE: This is only supported in .bb and .bbclass files.

BitBake allows to install event handlers. Events are triggered at certain points during operation, such as, the beginning of operation against a given .bb, the start of a given task, task failure, task success, et cetera. The intent was to make it easy to do things like email notifications on build failure.

addhandler myclass_eventhandler
python myclass_eventhandler() {
    from bb.event import NotHandled, getName
    from bb import data

    print "The name of the Event is %s" % getName(e)
    print "The file we run for is %s" % data.getVar('FILE', e.data, True)

    return NotHandled
}

This event handler gets called every time an event is triggered. A global variable e is defined. e.data contains an instance of bb.data. With the getName(e) method one can get the name of the triggered event.

The above event handler prints the name of the event and the content of the FILE variable.