BitBake User Manual

BitBake Recipes, which are denoted by the file extension .bb, are the most basic metadata files. These recipe files provide BitBake with the following:

Within the context of BitBake, or any project utilizing BitBake as its build system, files with the .bb extension are referred to as recipes.

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.

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. You can find this file in the classes directory. The base.bbclass class files 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 allow you to isolate different types of customizations from each other. While you might find it tempting to keep everything in one layer when working on a single project, the more modular you organize your metadata, the easier it is to cope with future changes.

To illustrate how you can use layers to keep things modular, consider customizations you might make to support a specific target machine. These types of customizations typically reside in a special layer, rather than a general layer, called a Board Support 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 you a couple of layers: one for the machine configurations and one for the GUI environment. It is important to understand, however, 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, which are files that have the .bbappend file extension, extend or override information in 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 extends or overrides the information in the underlying, similarly-named recipe files.

When you name an append file, you can use the wildcard character (%) to allow for matching recipe names. For example, suppose you have an append file named as follows:

     busybox_1.21.%.bbappend
                

That append file would match any busybox_1.21.x.bb version of the recipe. So, the append file would match the following recipe names:

     busybox_1.21.1.bb
     busybox_1.21.2.bb
     busybox_1.21.3.bb
                

If the busybox recipe was updated to busybox_1.3.0.bb, the append name would not match. However, if you named the append file busybox_1.%.bbappend, then you would have a match.

In the most general case, you could name the append file something as simple as busybox_%.bbappend to be entirely version independent.

Following is the usage and syntax for BitBake:

     $ bitbake -h
     Usage: bitbake [options] [recipename/target recipe:do_task ...]

         Executes the specified task (default is 'build') for a given set of target recipes (.bb files).
         It is assumed there is a conf/bblayers.conf available in cwd or in BBPATH which
         will provide the layer, BBFILES and other configuration information.

     Options:
       --version             show program's version number and exit
       -h, --help            show this help message and exit
       -b BUILDFILE, --buildfile=BUILDFILE
                             Execute tasks from a specific .bb recipe directly.
                             WARNING: Does not handle any dependencies from other
                             recipes.
       -k, --continue        Continue as much as possible after an error. While the
                             target that failed and anything depending on it cannot
                             be built, as much as possible will be built before
                             stopping.
       -a, --tryaltconfigs   Continue with builds by trying to use alternative
                             providers where possible.
       -f, --force           Force the specified targets/task to run (invalidating
                             any existing stamp file).
       -c CMD, --cmd=CMD     Specify the task to execute. The exact options
                             available depend on the metadata. Some examples might
                             be 'compile' or 'populate_sysroot' or 'listtasks' may
                             give a list of the tasks available.
       -C INVALIDATE_STAMP, --clear-stamp=INVALIDATE_STAMP
                             Invalidate the stamp for the specified task such as
                             'compile' and then run the default task for the
                             specified target(s).
       -r PREFILE, --read=PREFILE
                             Read the specified file before bitbake.conf.
       -R POSTFILE, --postread=POSTFILE
                             Read the specified file after bitbake.conf.
       -v, --verbose         Enable tracing of shell tasks (with 'set -x').
                             Also print bb.note(...) messages to stdout (in
                             addition to writing them to ${T}/log.do_<task>).
       -D, --debug           Increase the debug level. You can specify this
                             more than once. -D sets the debug level to 1,
                             where only bb.debug(1, ...) messages are printed
                             to stdout; -DD sets the debug level to 2, where
                             both bb.debug(1, ...) and bb.debug(2, ...)
                             messages are printed; etc. Without -D, no debug
                             messages are printed. Note that -D only affects
                             output to stdout. All debug messages are written
                             to ${T}/log.do_taskname, regardless of the debug
                             level.
       -n, --dry-run         Don't execute, just go through the motions.
       -S SIGNATURE_HANDLER, --dump-signatures=SIGNATURE_HANDLER
                             Dump out the signature construction information, with
                             no task execution. The SIGNATURE_HANDLER parameter is
                             passed to the handler. Two common values are none and
                             printdiff but the handler may define more/less. none
                             means only dump the signature, printdiff means compare
                             the dumped signature with the cached one.
       -p, --parse-only      Quit after parsing the BB recipes.
       -s, --show-versions   Show current and preferred versions of all recipes.
       -e, --environment     Show the global or per-recipe environment complete
                             with information about where variables were
                             set/changed.
       -g, --graphviz        Save dependency tree information for the specified
                             targets in the dot syntax.
       -I EXTRA_ASSUME_PROVIDED, --ignore-deps=EXTRA_ASSUME_PROVIDED
                             Assume these dependencies don't exist and are already
                             provided (equivalent to ASSUME_PROVIDED). Useful to
                             make dependency graphs more appealing
       -l DEBUG_DOMAINS, --log-domains=DEBUG_DOMAINS
                             Show debug logging for the specified logging domains
       -P, --profile         Profile the command and save reports.
       -u UI, --ui=UI        The user interface to use (taskexp, knotty or
                             ncurses - default knotty).
       -t SERVERTYPE, --servertype=SERVERTYPE
                             Choose which server type to use (process or xmlrpc -
                             default process).
       --token=XMLRPCTOKEN   Specify the connection token to be used when
                             connecting to a remote server.
       --revisions-changed   Set the exit code depending on whether upstream
                             floating revisions have changed or not.
       --server-only         Run bitbake without a UI, only starting a server
                             (cooker) process.
       -B BIND, --bind=BIND  The name/address for the bitbake server to bind to.
       --no-setscene         Do not run any setscene tasks. sstate will be ignored
                             and everything needed, built.
       --setscene-only       Only run setscene tasks, don't run any real tasks.
       --remote-server=REMOTE_SERVER
                             Connect to the specified server.
       -m, --kill-server     Terminate the remote server.
       --observe-only        Connect to a server as an observing-only client.
       --status-only         Check the status of the remote bitbake server.
       -w WRITEEVENTLOG, --write-log=WRITEEVENTLOG
                             Writes the event log of the build to a bitbake event
                             json file. Use '' (empty string) to assign the name
                             automatically.
                

This section presents some examples showing how to use BitBake.

     $ bitbake -b foo_1.0.bb
                    

     $ bitbake -b foo.bb -c clean
                    

     $ bitbake foo
                    

     $ bitbake -c clean foo
                    

     $ bitbake myfirstrecipe:do_taskA mysecondrecipe:do_taskB
                    

     $ bitbake -g foo

     $ bitbake -g -I virtual/kernel -I eglibc foo
                    

The following example sets VARIABLE to "value". This assignment occurs immediately as the statement is parsed. It is a "hard" assignment.

     VARIABLE = "value"
                

As expected, if you include leading or trailing spaces as part of an assignment, the spaces are retained:

     VARIABLE = " value"
     VARIABLE = "value "
                

Setting VARIABLE to "" sets it to an empty string, while setting the variable to " " sets it to a blank space (i.e. these are not the same values).

     VARIABLE = ""
     VARIABLE = " "
                

You can use single quotes instead of double quotes when setting a variable's value. Doing so allows you to use values that contain the double quote character:

     VARIABLE = 'I have a " in my value'
                

Outside of functions, BitBake joins any line ending in a backslash character ("\") with the following line before parsing statements. The most common use for the "\" character is to split variable assignments over multiple lines, as in the following example:

     FOO = "bar \
            baz \
            qaz"
                

Both the "\" character and the newline character that follow it are removed when joining lines. Thus, no newline characters end up in the value of FOO.

Consider this additional example where the two assignments both assign "barbaz" to FOO:

     FOO = "barbaz"

     FOO = "bar\
     baz"
                

Variables can reference the contents of other variables using a syntax that is similar to variable expansion in Bourne shells. The following assignments result in A containing "aval" and B evaluating to "preavalpost".

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

The "=" operator does not immediately expand variable references in the right-hand side. Instead, expansion is deferred until the variable assigned to is actually used. The result depends on the current values of the referenced variables. The following example should clarify this behavior:

     A = "${B} baz"
     B = "${C} bar"
     C = "foo"
     *At this point, ${A} equals "foo bar baz"*
     C = "qux"
     *At this point, ${A} equals "qux bar baz"*
     B = "norf"
     *At this point, ${A} equals "norf baz"*
                

Contrast this behavior with the immediate variable expansion operator (i.e. ":=").

If the variable expansion syntax is used on a variable that does not exist, the string is kept as is. For example, given the following assignment, BAR expands to the literal string "${FOO}" as long as FOO does not exist.

     BAR = "${FOO}"
                

You can use the "?=" operator to achieve a "softer" assignment for a variable. This type of assignment allows you to define a variable if it is undefined when the statement is parsed, but to leave the value alone if the variable has a value. Here is an example:

     A ?= "aval"
                

If A is set at the time this statement is parsed, the variable retains its value. However, if A is not set, the variable is set to "aval".

It is possible to use a "weaker" assignment than in the previous section by using the "??=" operator. This assignment behaves identical to "?=" except that the assignment is made at the end of the parsing process rather than immediately. Consequently, when multiple "??=" assignments exist, the last one is used. Also, any "=" or "?=" assignment will override the value set with "??=". Here is an example:

     A ??= "somevalue"
     A ??= "someothervalue"
                

If A is set before the above statements are parsed, the variable retains its value. If A is not set, the variable is set to "someothervalue".

Again, this assignment is a "lazy" or "weak" assignment because it does not occur until the end of the parsing process.

The ":=" operator 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 this example, A contains "test 123" because ${B} and ${A} at the time of parsing are undefined, which leaves "test 123". And, the variable C contains "cvalappend" since ${C} immediately expands to "cval".

Appending and prepending values is common and can be accomplished using the "+=" and "=+" operators. These operators insert a space between the current value and prepended or appended value.

These operators take immediate effect during parsing. Here are some examples:

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

The variable B contains "bval additionaldata" and C contains "test cval".

If you want to append or prepend values without an inserted space, use the ".=" and "=." operators.

These operators take immediate effect during parsing. Here are some examples:

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

The variable B contains "bvaladditionaldata" and C contains "testcval".

You can also append and prepend a variable's value using an override style syntax. When you use this syntax, no spaces are inserted.

These operators differ from the ":=", ".=", "=.", "+=", and "=+" operators in that their effects are deferred until after parsing completes rather than being immediately applied. Here are some examples:

     B = "bval"
     B_append = " additional data"
     C = "cval"
     C_prepend = "additional data "
     D = "dval"
     D_append = "additional data"
                

The variable B becomes "bval additional data" and C becomes "additional data cval". The variable D becomes "dvaladditional data".

It is also possible to append and prepend to shell functions and BitBake-style Python functions. See the "Shell Functions" and "BitBake-Style Python Functions sections for examples.

You can remove values from lists using the removal override style syntax. Specifying a value for removal causes all occurrences of that value to be removed from the variable.

When you use this syntax, BitBake expects one or more strings. Surrounding spaces are removed as well. Here is an example:

     FOO = "123 456 789 123456 123 456 123 456"
     FOO_remove = "123"
     FOO_remove = "456"
     FOO2 = "abc def ghi abcdef abc def abc def"
     FOO2_remove = "abc def"
                

The variable FOO becomes "789 123456" and FOO2 becomes "ghi abcdef".

Like "_append" and "_prepend", "_remove" is deferred until after parsing completes.

An advantage of the override style operations "_append", "_prepend", and "_remove" as compared to the "+=" and "=+" operators is that the override style operators provide guaranteed operations. For example, consider a class foo.bbclass that needs to add the value "val" to the variable FOO, and a recipe that uses foo.bbclass as follows:

     inherit foo

     FOO = "initial"
                

If foo.bbclass uses the "+=" operator, as follows, then the final value of FOO will be "initial", which is not what is desired:

     FOO += "val"
                

If, on the other hand, foo.bbclass uses the "_append" operator, then the final value of FOO will be "initial val", as intended:

     FOO_append = " val"
                

     FOO_append = "bar"
     FOO_append = "baz"
                    

Another advantage of the override style operations is that you can combine them with other overrides as described in the "Conditional Syntax (Overrides)" section.

Variable flags are BitBake's implementation of variable properties or attributes. It is a way of tagging extra information onto a variable. You can find more out about variable flags in general in the "Variable Flags" section.

You can define, append, and prepend values to variable flags. All the standard syntax operations previously mentioned work for variable flags except for override style syntax (i.e. "_prepend", "_append", and "_remove").

Here are some examples showing how to set variable flags:

     FOO[a] = "abc"
     FOO[b] = "123"
     FOO[a] += "456"
                

The variable FOO has two flags: [a] and [b]. The flags are immediately set to "abc" and "123", respectively. The [a] flag becomes "abc 456".

No need exists to pre-define variable flags. You can simply start using them. One extremely common application is to attach some brief documentation to a BitBake variable as follows:

     CACHE[doc] = "The directory holding the cache of the metadata."
                

You can use inline Python variable expansion to set variables. Here is an example:

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

This example results in the DATE variable being set to the current date.

Probably the most common use of this feature is to extract the value of variables from BitBake's internal data dictionary, d. The following lines select the values of a package name and its version number, respectively:

     PN = "${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE', False),d)[0] or 'defaultpkgname'}"
     PV = "${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE', False),d)[1] or '1.0'}"
                

     FOO = "${@foo()}"
                    

     FOO := "${@foo()}"
                    

For a different way to set variables with Python code during parsing, see the "Anonymous Python Functions" section.

It is possible to completely remove a variable or a variable flag from BitBake's internal data dictionary by using the "unset" keyword. Here is an example:

        unset DATE
        unset do_fetch[noexec]
                

These two statements remove the DATE and the do_fetch[noexec] flag.

When specifying pathnames for use with BitBake, do not use the tilde ("~") character as a shortcut for your home directory. Doing so might cause BitBake to not recognize the path since BitBake does not expand this character in the same way a shell would.

Instead, provide a fuller path as the following example illustrates:

     BBLAYERS ?= " \
       /home/scott-lenovo/LayerA \
       "
                

You can use OVERRIDES to conditionally select a specific version of a variable and to conditionally append or prepend the value of a variable.

Key expansion happens when the BitBake datastore is finalized just before BitBake expands overrides. To better understand this, consider the following example:

     A${B} = "X"
     B = "2"
     A2 = "Y"
                

In this case, after all the parsing is complete, and before any overrides are handled, BitBake expands ${B} into "2". This expansion causes A2, which was set to "Y" before the expansion, to become "X".

Despite the previous explanations that show the different forms of variable definitions, it can be hard to work out exactly what happens when variable operators, conditional overrides, and unconditional overrides are combined. This section presents some common scenarios along with explanations for variable interactions that typically confuse users.

There is often confusion concerning the order in which overrides and various "append" operators take effect. Recall that an append or prepend operation using "_append" and "_prepend" does not result in an immediate assignment as would "+=", ".=", "=+", or "=.". Consider the following example:

     OVERRIDES = "foo"
     A = "Z"
     A_foo_append = "X"
                

For this case, A is unconditionally set to "Z" and "X" is unconditionally and immediately appended to the variable A_foo. Because overrides have not been applied yet, A_foo is set to "X" due to the append and A simply equals "Z".

Applying overrides, however, changes things. Since "foo" is listed in OVERRIDES, the conditional variable A is replaced with the "foo" version, which is equal to "X". So effectively, A_foo replaces A.

This next example changes the order of the override and the append:

     OVERRIDES = "foo"
     A = "Z"
     A_append_foo = "X"
                

For this case, before overrides are handled, A is set to "Z" and A_append_foo is set to "X". Once the override for "foo" is applied, however, A gets appended with "X". Consequently, A becomes "ZX". Notice that spaces are not appended.

This next example has the order of the appends and overrides reversed back as in the first example:

     OVERRIDES = "foo"
     A = "Y"
     A_foo_append = "Z"
     A_foo_append = "X"
                

For this case, before any overrides are resolved, A is set to "Y" using an immediate assignment. After this immediate assignment, A_foo is set to "Z", and then further appended with "X" leaving the variable set to "ZX". Finally, applying the override for "foo" results in the conditional variable A becoming "ZX" (i.e. A is replaced with A_foo).

This final example mixes in some varying operators:

     A = "1"
     A_append = "2"
     A_append = "3"
     A += "4"
     A .= "5"
                

For this case, the type of append operators are affecting the order of assignments as BitBake passes through the code multiple times. Initially, A is set to "1 45" because of the three statements that use immediate operators. After these assignments are made, BitBake applies the "_append" operations. Those operations result in A becoming "1 4523".

BitBake uses the BBPATH variable to locate needed include and class files. Additionally, BitBake searches the current directory for include and require directives.

In order for include and class files to be found by BitBake, they need to be located in a "classes" subdirectory that can be found in BBPATH.

When writing a recipe or class file, you can use the inherit directive to inherit the functionality of a class (.bbclass). BitBake only supports this directive when used within recipe and class files (i.e. .bb and .bbclass).

The inherit directive is a rudimentary means of specifying functionality contained in class files that your recipes require. For example, you can easily abstract out the tasks involved in building a package that uses Autoconf and Automake and put those tasks into a class file and then have your recipe inherit that class file.

As an example, your recipes could use the following directive to inherit an autotools.bbclass file. The class file would contain common functionality for using Autotools that could be shared across recipes:

     inherit autotools
                

In this case, BitBake would search for the directory classes/autotools.bbclass in BBPATH.

If you want to use the directive to inherit multiple classes, separate them with spaces. The following example shows how to inherit both the buildhistory and rm_work classes:

     inherit buildhistory rm_work
                

An advantage with the inherit directive as compared to both the include and require directives is that you can inherit class files conditionally. You can accomplish this by using a variable expression after the inherit statement. Here is an example:

     inherit ${VARNAME}
                

If VARNAME is going to be set, it needs to be set before the inherit statement is parsed. One way to achieve a conditional inherit in this case is to use overrides:

     VARIABLE = ""
     VARIABLE_someoverride = "myclass"
                

Another method is by using anonymous Python. Here is an example:

     python () {
         if condition == value:
             d.setVar('VARIABLE', 'myclass')
         else:
             d.setVar('VARIABLE', '')
     }
                

Alternatively, you could use an in-line Python expression in the following form:

     inherit ${@'classname' if condition else ''}
     inherit ${@functionname(params)}
                

In all cases, if the expression evaluates to an empty string, the statement does not trigger a syntax error because it becomes a no-op.

BitBake understands the include directive. This directive causes BitBake to parse whatever file you specify, and to insert that file at that location. The directive is much like its equivalent in Make except that if the path specified on the include line is a relative path, BitBake locates the first file it can find within BBPATH.

The include directive is a more generic method of including functionality as compared to the inherit directive, which is restricted to class (i.e. .bbclass) files. The include directive is applicable for any other kind of shared or encapsulated functionality or configuration that does not suit a .bbclass file.

As an example, suppose you needed a recipe to include some self-test definitions:

     include test_defs.inc
                

BitBake understands the require directive. This directive behaves just like the include directive with the exception that BitBake raises a parsing error if the file to be included cannot be found. Thus, any file you require is inserted into the file that is being parsed at the location of the directive.

The require directive, like the include directive previously described, is a more generic method of including functionality as compared to the inherit directive, which is restricted to class (i.e. .bbclass) files. The require directive is applicable for any other kind of shared or encapsulated functionality or configuration that does not suit a .bbclass file.

Similar to how BitBake handles include, if the path specified on the require line is a relative path, BitBake locates the first file it can find within BBPATH.

As an example, suppose you have two versions of a recipe (e.g. foo_1.2.2.bb and foo_2.0.0.bb) where each version contains some identical functionality that could be shared. You could create an include file named foo.inc that contains the common definitions needed to build "foo". You need to be sure foo.inc is located in the same directory as your two recipe files as well. Once these conditions are set up, you can share the functionality using a require directive from within each recipe:

     require foo.inc
                

When creating a configuration file (.conf), you can use the INHERIT configuration directive to inherit a class. BitBake only supports this directive when used within a configuration file.

As an example, suppose you needed to inherit a class file called abc.bbclass from a configuration file as follows:

     INHERIT += "abc"
                

This configuration directive causes the named class to be inherited at the point of the directive during parsing. As with the inherit directive, the .bbclass file must be located in a "classes" subdirectory in one of the directories specified in BBPATH.

If you want to use the directive to inherit multiple classes, you can provide them on the same line in the local.conf file. Use spaces to separate the classes. The following example shows how to inherit both the autotools and pkgconfig classes:

     INHERIT += "autotools pkgconfig"
                

Functions written in shell script and executed either directly as functions, tasks, or both. They can also be called by other shell functions. Here is an example shell function definition:

     some_function () {
         echo "Hello World"
     }
                

When you create these types of functions in your recipe or class files, you need to follow the shell programming rules. The scripts are executed by /bin/sh, which may not be a bash shell but might be something such as dash. You should not use Bash-specific script (bashisms).

Overrides and override-style operators like _append and _prepend can also be applied to shell functions. Most commonly, this application would be used in a .bbappend file to modify functions in the main recipe. It can also be used to modify functions inherited from classes.

As an example, consider the following:

     do_foo() {
         bbplain first
         fn
     }

     fn_prepend() {
         bbplain second
     }

     fn() {
         bbplain third
     }

     do_foo_append() {
         bbplain fourth
     }
                

Running do_foo prints the following:

     recipename do_foo: first
     recipename do_foo: second
     recipename do_foo: third
     recipename do_foo: fourth
                

You can use the bitbake -e recipename command to view the final assembled function after all overrides have been applied.

These functions are written in Python and executed by BitBake or other Python functions using bb.build.exec_func().

An example BitBake function is:

     python some_python_function () {
         d.setVar("TEXT", "Hello World")
         print d.getVar("TEXT")
     }
                

Because the Python "bb" and "os" modules are already imported, you do not need to import these modules. Also in these types of functions, the datastore ("d") is a global variable and is always automatically available.

Similar to shell functions, you can also apply overrides and override-style operators to BitBake-style Python functions.

As an example, consider the following:

     python do_foo_prepend() {
         bb.plain("first")
     }

     python do_foo() {
         bb.plain("second")
     }

     python do_foo_append() {
         bb.plain("third")
     }
                

Running do_foo prints the following:

     recipename do_foo: first
     recipename do_foo: second
     recipename do_foo: third
                

You can use the bitbake -e recipename command to view the final assembled function after all overrides have been applied.

These functions are written in Python and are executed by other Python code. Examples of Python functions are utility functions that you intend to call from in-line Python or from within other Python functions. Here is an example:

     def get_depends(d):
         if d.getVar('SOMECONDITION'):
             return "dependencywithcond"
         else:
             return "dependency"
     SOMECONDITION = "1"
     DEPENDS = "${@get_depends(d)}"
                

This would result in DEPENDS containing dependencywithcond.

Here are some things to know about Python functions:

Following are some important differences between BitBake-style Python functions and regular Python functions defined with "def":

Due to their simplicity, you should prefer regular Python functions over BitBake-style Python functions unless you need a feature specific to BitBake-style Python functions. Regular Python functions in metadata are a more recent invention than BitBake-style Python functions, and older code tends to use bb.build.exec_func() more often.

Sometimes it is useful to set variables or perform other operations programmatically during parsing. To do this, you can define special Python functions, called anonymous Python functions, that run at the end of parsing. For example, the following conditionally sets a variable based on the value of another variable:

     python () {
         if d.getVar('SOMEVAR') == 'value':
             d.setVar('ANOTHERVAR', 'value2')
     }
                

An equivalent way to mark a function as an anonymous function is to give it the name "__anonymous", rather than no name.

Anonymous Python functions always run at the end of parsing, regardless of where they are defined. If a recipe contains many anonymous functions, they run in the same order as they are defined within the recipe. As an example, consider the following snippet:

     python () {
         d.setVar('FOO', 'foo 2')
     }

     FOO = "foo 1"

     python () {
         d.appendVar('BAR', ' bar 2')
     }

     BAR = "bar 1"
                

The previous example is conceptually equivalent to the following snippet:

     FOO = "foo 1"
     BAR = "bar 1"
     FOO = "foo 2"
     BAR += "bar 2"
                

FOO ends up with the value "foo 2", and BAR with the value "bar 1 bar 2". Just as in the second snippet, the values set for the variables within the anonymous functions become available to tasks, which always run after parsing.

Overrides and override-style operators such as "_append" are applied before anonymous functions run. In the following example, FOO ends up with the value "foo from anonymous":

     FOO = "foo"
     FOO_append = " from outside"

     python () {
         d.setVar("FOO", "foo from anonymous")
     }
                

For methods you can use with anonymous Python functions, see the "Functions You Can Call From Within Python" section. For a different method to run Python code during parsing, see the "Inline Python Variable Expansion" section.

Through coding techniques and the use of EXPORT_FUNCTIONS, BitBake supports exporting a function from a class such that the class function appears as the default implementation of the function, but can still be called if a recipe inheriting the class needs to define its own version of the function.

To understand the benefits of this feature, consider the basic scenario where a class defines a task function and your recipe inherits the class. In this basic scenario, your recipe inherits the task function as defined in the class. If desired, your recipe can add to the start and end of the function by using the "_prepend" or "_append" operations respectively, or it can redefine the function completely. However, if it redefines the function, there is no means for it to call the class version of the function. EXPORT_FUNCTIONS provides a mechanism that enables the recipe's version of the function to call the original version of the function.

To make use of this technique, you need the following things in place:

With these conditions met, your single recipe can freely choose between the original function as defined in the class file and the modified function in your recipe. If you do not set up these conditions, you are limited to using one function or the other.

Tasks are either shell functions or BitBake-style Python functions that have been promoted to tasks by using the addtask command. The addtask command can also optionally describe dependencies between the task and other tasks. Here is an example that shows how to define a task and declare some dependencies:

     python do_printdate () {
         import time
         print time.strftime('%Y%m%d', time.gmtime())
     }
     addtask printdate after do_fetch before do_build
                

The first argument to addtask is the name of the function to promote to a task. If the name does not start with "do_", "do_" is implicitly added, which enforces the convention that all task names start with "do_".

In the previous example, the do_printdate task becomes a dependency of the do_build task, which is the default task (i.e. the task run by the bitbake command unless another task is specified explicitly). Additionally, the do_printdate task becomes dependent upon the do_fetch task. Running the do_build task results in the do_printdate task running first.

     do_printdate[nostamp] = "1"
                    

     $ bitbake recipe -c printdate -f
                    

You might wonder about the practical effects of using addtask without specifying any dependencies as is done in the following example:

     addtask printdate
                

In this example, assuming dependencies have not been added through some other means, the only way to run the task is by explicitly selecting it with bitbake recipe -c printdate. You can use the do_listtasks task to list all tasks defined in a recipe as shown in the following example:

     $ bitbake recipe -c listtasks
                

For more information on task dependencies, see the "Dependencies" section.

See the "Variable Flags" section for information on variable flags you can use with tasks.

As well as being able to add tasks, you can delete them. Simply use the deltask command to delete a task. For example, to delete the example task used in the previous sections, you would use:

     deltask printdate
                

If you delete a task using the deltask command and the task has dependencies, the dependencies are not reconnected. For example, suppose you have three tasks named do_a, do_b, and do_c. Furthermore, do_c is dependent on do_b, which in turn is dependent on do_a. Given this scenario, if you use deltask to delete do_b, the implicit dependency relationship between do_c and do_a through do_b no longer exists, and do_c dependencies are not updated to include do_a. Thus, do_c is free to run before do_a.

If you want dependencies such as these to remain intact, use the [noexec] varflag to disable the task instead of using the deltask command to delete it:

     do_b[noexec] = "1"
                

When running a task, BitBake tightly controls the shell execution environment of the build tasks to make sure unwanted contamination from the build machine cannot influence the build.

Consequently, if you do want something to get passed into the build task environment, you must take these two steps:

Sometimes, it is useful to be able to obtain information from the original execution environment. Bitbake saves a copy of the original environment into a special variable named BB_ORIGENV.

The BB_ORIGENV variable returns a datastore object that can be queried using the standard datastore operators such as getVar(, False). The datastore object is useful, for example, to find the original DISPLAY variable. Here is an example:

     origenv = d.getVar("BB_ORIGENV", False)
     bar = origenv.getVar("BAR", False)
                

The previous example returns BAR from the original execution environment.

BitBake uses the addtask directive to manage dependencies that are internal to a given recipe file. You can use the addtask directive to indicate when a task is dependent on other tasks or when other tasks depend on that recipe. Here is an example:

     addtask printdate after do_fetch before do_build
                

In this example, the do_printdate task depends on the completion of the do_fetch task, and the do_build task depends on the completion of the do_printdate task.

BitBake uses the DEPENDS variable to manage build time dependencies. The [deptask] varflag for tasks signifies the task of each item listed in DEPENDS that must complete before that task can be executed. Here is an example:

     do_configure[deptask] = "do_populate_sysroot"
                

In this example, the do_populate_sysroot task of each item in DEPENDS must complete before do_configure can execute.

BitBake uses the PACKAGES, RDEPENDS, and RRECOMMENDS variables to manage runtime dependencies.

The PACKAGES variable lists runtime packages. Each of those packages can have RDEPENDS and RRECOMMENDS runtime dependencies. The [rdeptask] flag for tasks is used to signify the task of each item runtime dependency which must have completed before that task can be executed.

     do_package_qa[rdeptask] = "do_packagedata"
                

In the previous example, the do_packagedata task of each item in RDEPENDS must have completed before do_package_qa can execute.

BitBake uses the [recrdeptask] flag to manage recursive task dependencies. BitBake looks through the build-time and runtime dependencies of the current recipe, looks through the task's inter-task dependencies, and then adds dependencies for the listed task. Once BitBake has accomplished this, it recursively works through the dependencies of those tasks. Iterative passes continue until all dependencies are discovered and added.

The [recrdeptask] flag is most commonly used in high-level recipes that need to wait for some task to finish "globally". For example, image.bbclass has the following:

     do_rootfs[recrdeptask] += "do_packagedata"
                

This statement says that the do_packagedata task of the current recipe and all recipes reachable (by way of dependencies) from the image recipe must run before the do_rootfs task can run.

You might want to not only have BitBake look for dependencies of those tasks, but also have BitBake look for build-time and runtime dependencies of the dependent tasks as well. If that is the case, you need to reference the task name itself in the task list:

     do_a[recrdeptask] = "do_a do_b"
                

BitBake uses the [depends] flag in a more generic form to manage inter-task dependencies. This more generic form allows for inter-dependency checks for specific tasks rather than checks for the data in DEPENDS. Here is an example:

     do_patch[depends] = "quilt-native:do_populate_sysroot"
                

In this example, the do_populate_sysroot task of the target quilt-native must have completed before the do_patch task can execute.

The [rdepends] flag works in a similar way but takes targets in the runtime namespace instead of the build-time dependency namespace.

It is often necessary to access variables in the BitBake datastore using Python functions. The Bitbake datastore has an API that allows you this access. Here is a list of available operations:

You can find many other functions that can be called from Python by looking at the source code of the bb module, which is in bitbake/lib/bb. For example, bitbake/lib/bb/utils.py includes the commonly used functions bb.utils.contains() and bb.utils.mkdirhier(), which come with docstrings.

This submodule handles URLs that begin with file://. The filename you specify within the URL can be either an absolute or relative path to a file. If the filename is relative, the contents of the FILESPATH variable is used in the same way PATH is used to find executables. If the file cannot be found, it is assumed that it is available in DL_DIR by the time the download() method is called.

If you specify a directory, the entire directory is unpacked.

Here are a couple of example URLs, the first relative and the second absolute:

     SRC_URI = "file://relativefile.patch"
     SRC_URI = "file:///Users/ich/very_important_software"
                

This fetcher obtains files from web and FTP servers. Internally, the fetcher uses the wget utility.

The executable and parameters used are specified by the FETCHCMD_wget variable, which defaults to sensible values. The fetcher supports a parameter "downloadfilename" that allows the name of the downloaded file to be specified. Specifying the name of the downloaded file is useful for avoiding collisions in DL_DIR when dealing with multiple files that have the same name.

Some example URLs are as follows:

     SRC_URI = "http://oe.handhelds.org/not_there.aac"
     SRC_URI = "ftp://oe.handhelds.org/not_there_as_well.aac"
     SRC_URI = "ftp://you@oe.handhelds.org/home/you/secret.plan"
                

     SRC_URI = "http://abc123.org/git/?p=gcc/gcc.git;a=snapshot;h=a5dd47"
                

     SRC_URI = "http://abc123.org/git/?p=gcc/gcc.git&a=snapshot&h=a5dd47"
                

     SRC_URI = "http://abc123.org/git/?p=gcc/gcc.git&a=snapshot&h=a5dd47;downloadfilename=myfile.bz2"
                

This submodule handles checking out files from the CVS version control system. You can configure it using a number of different variables:

As well as the standard username and password URL syntax, you can also configure the fetcher with various URL parameters:

The supported parameters are as follows:

Some example URLs are as follows:

     SRC_URI = "cvs://CVSROOT;module=mymodule;tag=some-version;method=ext"
     SRC_URI = "cvs://CVSROOT;module=mymodule;date=20060126;localdir=usethat"
                

This fetcher submodule fetches code from the Subversion source control system. The executable used is specified by FETCHCMD_svn, which defaults to "svn". The fetcher's temporary working directory is set by SVNDIR, which is usually DL_DIR/svn.

The supported parameters are as follows:

Following are three examples using svn:

     SRC_URI = "svn://myrepos/proj1;module=vip;protocol=http;rev=667"
     SRC_URI = "svn://myrepos/proj1;module=opie;protocol=svn+ssh"
     SRC_URI = "svn://myrepos/proj1;module=trunk;protocol=http;path_spec=${MY_DIR}/proj1"
                

This fetcher submodule fetches code from the Git source control system. The fetcher works by creating a bare clone of the remote into GITDIR, which is usually DL_DIR/git2. This bare clone is then cloned into the work directory during the unpack stage when a specific tree is checked out. This is done using alternates and by reference to minimize the amount of duplicate data on the disk and make the unpack process fast. The executable used can be set with FETCHCMD_git.

This fetcher supports the following parameters:

Here are some example URLs:

     SRC_URI = "git://git.oe.handhelds.org/git/vip.git;tag=version-1"
     SRC_URI = "git://git.oe.handhelds.org/git/vip.git;protocol=http"
                

This fetcher submodule inherits from the Git fetcher and extends that fetcher's behavior by fetching a repository's submodules. SRC_URI is passed to the Git fetcher as described in the "Git Fetcher (git://)" section.

This fetcher submodule fetches code from a ClearCase repository.

To use this fetcher, make sure your recipe has proper SRC_URI, SRCREV, and PV settings. Here is an example:

     SRC_URI = "ccrc://cc.example.org/ccrc;vob=/example_vob;module=/example_module"
     SRCREV = "EXAMPLE_CLEARCASE_TAG"
     PV = "${@d.getVar("SRCREV", False).replace("/", "+")}"
                

The fetcher uses the rcleartool or cleartool remote client, depending on which one is available.

Following are options for the SRC_URI statement:

By default, the fetcher creates a configuration specification. If you want this specification written to an area other than the default, use the CCASE_CUSTOM_CONFIG_SPEC variable in your recipe to define where the specification is written.

Here are a couple of other behaviors worth mentioning:

This fetcher submodule fetches code from the Perforce source control system. The executable used is specified by FETCHCMD_p4, which defaults to "p4". The fetcher's temporary working directory is set by P4DIR, which defaults to "DL_DIR/p4".

To use this fetcher, make sure your recipe has proper SRC_URI, SRCREV, and PV values. The p4 executable is able to use the config file defined by your system's P4CONFIG environment variable in order to define the Perforce server URL and port, username, and password if you do not wish to keep those values in a recipe itself. If you choose not to use P4CONFIG, or to explicitly set variables that P4CONFIG can contain, you can specify the P4PORT value, which is the server's URL and port number, and you can specify a username and password directly in your recipe within SRC_URI.

Here is an example that relies on P4CONFIG to specify the server URL and port, username, and password, and fetches the Head Revision:

    SRC_URI = "p4://example-depot/main/source/..."
    SRCREV = "${AUTOREV}"
    PV = "p4-${SRCPV}"
    S = "${WORKDIR}/p4"
                

Here is an example that specifies the server URL and port, username, and password, and fetches a Revision based on a Label:

    P4PORT = "tcp:p4server.example.net:1666"
    SRC_URI = "p4://user:passwd@example-depot/main/source/..."
    SRCREV = "release-1.0"
    PV = "p4-${SRCPV}"
    S = "${WORKDIR}/p4"
                

Fetch submodules also exist for the following:

No documentation currently exists for these lesser used fetcher submodules. However, you might find the code helpful and readable.