%poky; ] > This chapter lists common variables used by BitBake and gives an overview of their function and contents. A B D E F H L M O P R S T ASSUME_PROVIDED Recipe names (PN values) BitBake does not attempt to build. Instead, BitBake assumes these recipes have already been built. ASSUMED_PROVIDED often specifies native tools. A good example is git-native, which allows for the the Git binary from the host to be used rather than building git-native. B The directory in which BitBake executes functions during a recipe's build process. BB_CURRENTTASK Contains the name of the currently running task. The name does not include the do_ prefix. BB_DANGLINGAPPENDS_WARNONLY Defines how BitBake handles situations where an append file (.bbappend) has no corresponding recipe file (.bb). This condition often occurs when layers get out of sync (e.g. oe-core bumps a recipe version and the old recipe no longer exists and the other layer has not been updated to the new version of the recipe yet). The default fatal behavior is safest because it is the sane reaction given something is out of sync. It is important to realize when your changes are no longer being applied. BB_DISKMON_DIRS Monitors disk space and available inodes during the build and allows you to control the build based on these parameters. Disk space monitoring is disabled by default. When setting this variable, use the following form: BB_DISKMON_DIRS = "<action>,<dir>,<threshold> [...]" where: <action> is: ABORT: Immediately abort the build when a threshold is broken. STOPTASKS: Stop the build after the currently executing tasks have finished when a threshold is broken. WARN: Issue a warning but continue the build when a threshold is broken. Subsequent warnings are issued as defined by the BB_DISKMON_WARNINTERVAL variable, which must be defined. <dir> is: Any directory you choose. You can specify one or more directories to monitor by separating the groupings with a space. If two directories are on the same device, only the first directory is monitored. <threshold> is: Either the minimum available disk space, the minimum number of free inodes, or both. You must specify at least one. To omit one or the other, simply omit the value. Specify the threshold using G, M, K for Gbytes, Mbytes, and Kbytes, respectively. If you do not specify G, M, or K, Kbytes is assumed by default. Do not use GB, MB, or KB. Here are some examples: BB_DISKMON_DIRS = "ABORT,${TMPDIR},1G,100K WARN,${SSTATE_DIR},1G,100K" BB_DISKMON_DIRS = "STOPTASKS,${TMPDIR},1G" BB_DISKMON_DIRS = "ABORT,${TMPDIR},,100K" The first example works only if you also set the BB_DISKMON_WARNINTERVAL variable. This example causes the build system to immediately abort when either the disk space in ${TMPDIR} drops below 1 Gbyte or the available free inodes drops below 100 Kbytes. Because two directories are provided with the variable, the build system also issues a warning when the disk space in the ${SSTATE_DIR} directory drops below 1 Gbyte or the number of free inodes drops below 100 Kbytes. Subsequent warnings are issued during intervals as defined by the BB_DISKMON_WARNINTERVAL variable. The second example stops the build after all currently executing tasks complete when the minimum disk space in the ${TMPDIR} directory drops below 1 Gbyte. No disk monitoring occurs for the free inodes in this case. The final example immediately aborts the build when the number of free inodes in the ${TMPDIR} directory drops below 100 Kbytes. No disk space monitoring for the directory itself occurs in this case. BB_DISKMON_WARNINTERVAL Defines the disk space and free inode warning intervals. If you are going to use the BB_DISKMON_WARNINTERVAL variable, you must also use the BB_DISKMON_DIRS variable and define its action as "WARN". During the build, subsequent warnings are issued each time disk space or number of free inodes further reduces by the respective interval. If you do not provide a BB_DISKMON_WARNINTERVAL variable and you do use BB_DISKMON_DIRS with the "WARN" action, the disk monitoring interval defaults to the following: BB_DISKMON_WARNINTERVAL = "50M,5K" When specifying the variable in your configuration file, use the following form: BB_DISKMON_WARNINTERVAL = "<disk_space_interval>,<disk_inode_interval>" where: <disk_space_interval> is: An interval of memory expressed in either G, M, or K for Gbytes, Mbytes, or Kbytes, respectively. You cannot use GB, MB, or KB. <disk_inode_interval> is: An interval of free inodes expressed in either G, M, or K for Gbytes, Mbytes, or Kbytes, respectively. You cannot use GB, MB, or KB. Here is an example: BB_DISKMON_DIRS = "WARN,${SSTATE_DIR},1G,100K" BB_DISKMON_WARNINTERVAL = "50M,5K" These variables cause BitBake to issue subsequent warnings each time the available disk space further reduces by 50 Mbytes or the number of free inodes further reduces by 5 Kbytes in the ${SSTATE_DIR} directory. Subsequent warnings based on the interval occur each time a respective interval is reached beyond the initial warning (i.e. 1 Gbytes and 100 Kbytes). BB_FETCH_PREMIRRORONLY When set to "1", causes BitBake's fetcher module to only search PREMIRRORS for files. BitBake will not search the main SRC_URI or MIRRORS. BB_FILENAME Contains the filename of the recipe that owns the currently running task. For example, if the do_fetch task that resides in the my-recipe.bb is executing, the BB_FILENAME variable contains "/foo/path/my-recipe.bb". BB_GENERATE_MIRROR_TARBALLS Causes tarballs of the Git repositories, including the Git metadata, to be placed in the DL_DIR directory. For performance reasons, creating and placing tarballs of the Git repositories is not the default action by BitBake. BB_GENERATE_MIRROR_TARBALLS = "1" BB_HASHCONFIG_WHITELIST A list of variables that BitBake excludes from checksum comparisons. One of the ways BitBake determines whether to re-parse the main metadata is by using a checksum of the variables in the datastore of the base configuration data. There are variables that you typically want to exclude from these checksum comparisons. As an example, you would usually exclude TIME and DATE because these variables are always changing. If you did not exclude them, BitBake would never use the cache. BB_NICE_LEVEL Allows BitBake to run at a specific priority (i.e. nice level). System permissions usually mean that BitBake can reduce its priority but not raise it again. See BB_TASK_NICE_LEVEL for additional information. BB_NO_NETWORK Disables network access in the BitBake fetcher modules. With this access disabled, any command that attempts to access the network becomes an error. Disabling network access is useful for testing source mirrors, running builds when not connected to the Internet, and when operating in certain kinds of firewall environments. BB_NUMBER_PARSE_THREADS Sets the number of threads BitBake uses when parsing. By default, the number of threads is equal to the number of cores on the system. BB_NUMBER_THREADS The maximum number of tasks BitBake should run in parallel at any one time. If your host development system supports multiple cores, a good rule of thumb is to set this variable to twice the number of cores. BB_TASK_NICE_LEVEL Allows specific tasks to change their priority (i.e. nice level). You can use this variable in combination with task overrides to raise or lower priorities of specific tasks. For example, on the Yocto Project autobuilder, QEMU emulation in images is given a higher priority as compared to build tasks to ensure that images do not suffer timeouts on loaded systems. BBCLASSEXTEND Allows you to extend a recipe so that it builds variants of the software. Common variants for recipes exist such as "natives" like quilt-native, which is a copy of Quilt built to run on the build system; "crosses" such as gcc-cross, which is a compiler built to run on the build machine but produces binaries that run on the target MACHINE; "nativesdk", which targets the SDK machine instead of MACHINE; and "mulitlibs" in the form "multilib:<multilib_name>". To build a different variant of the recipe with a minimal amount of code, it usually is as simple as adding the following to your recipe: BBCLASSEXTEND =+ "native nativesdk" BBCLASSEXTEND =+ "multilib:<multilib_name>" BBFILE_COLLECTIONS Lists the names of configured layers. These names are used to find the other BBFILE_* variables. Typically, each layer appends its name to this variable in its conf/layer.conf file. BBFILE_PATTERN Variable that expands to match files from BBFILES in a particular layer. This variable is used in the conf/layer.conf file and must be suffixed with the name of the specific layer (e.g. BBFILE_PATTERN_emenlow). BBFILE_PRIORITY Assigns the priority for recipe files in each layer. This variable is useful in situations where the same recipe appears in more than one layer. Setting this variable allows you to prioritize a layer against other layers that contain the same recipe - effectively letting you control the precedence for the multiple layers. The precedence established through this variable stands regardless of a recipe's version (PV variable). For example, a layer that has a recipe with a higher PV value but for which the BBFILE_PRIORITY is set to have a lower precedence still has a lower precedence. A larger value for the BBFILE_PRIORITY variable results in a higher precedence. For example, the value 6 has a higher precedence than the value 5. If not specified, the BBFILE_PRIORITY variable is set based on layer dependencies (see the LAYERDEPENDS variable for more information. The default priority, if unspecified for a layer with no dependencies, is the lowest defined priority + 1 (or 1 if no priorities are defined). You can use the command bitbake-layers show-layers to list all configured layers along with their priorities. BBFILES List of recipe files BitBake uses to build software. BBINCLUDELOGS Variable that controls how BitBake displays logs on build failure. BBLAYERS Lists the layers to enable during the build. This variable is defined in the bblayers.conf configuration file in the build directory. Here is an example: BBLAYERS = " \ /home/scottrif/poky/meta \ /home/scottrif/poky/meta-yocto \ /home/scottrif/poky/meta-yocto-bsp \ /home/scottrif/poky/meta-mykernel \ " This example enables four layers, one of which is a custom, user-defined layer named meta-mykernel. BBMASK Prevents BitBake from processing recipes and recipe append files. You can use the BBMASK variable to "hide" these .bb and .bbappend files. BitBake ignores any recipe or recipe append files that match the expression. It is as if BitBake does not see them at all. Consequently, matching files are not parsed or otherwise used by BitBake. The value you provide is passed to Python's regular expression compiler. The expression is compared against the full paths to the files. For complete syntax information, see Python's documentation at . The following example uses a complete regular expression to tell BitBake to ignore all recipe and recipe append files in the meta-ti/recipes-misc/ directory: BBMASK = "meta-ti/recipes-misc/" If you want to mask out multiple directories or recipes, use the vertical bar to separate the regular expression fragments. This next example masks out multiple directories and individual recipes: BBMASK = "meta-ti/recipes-misc/|meta-ti/recipes-ti/packagegroup/" BBMASK .= "|.*meta-oe/recipes-support/" BBMASK .= "|.*openldap" BBMASK .= "|.*opencv" BBMASK .= "|.*lzma" Notice how the vertical bar is used to append the fragments. When specifying a directory name, use the trailing slash character to ensure you match just that directory name. BBPATH Used by BitBake to locate class (.bbclass) and configuration (.conf) files. This variable is analogous to the PATH variable. If you run BitBake from a directory outside of the build directory, you must be sure to set BBPATH to point to the build directory. Set the variable as you would any environment variable and then run BitBake: $ BBPATH = "<build_directory>" $ export BBPATH $ bitbake <target> BBSERVER Points to the server that runs memory-resident BitBake. The variable is only used when you employ memory-resident BitBake. DEFAULT_PREFERENCE Specifies a weak bias for recipe selection priority. The most common usage of this is variable is to set it to "-1" within a recipe for a development version of a piece of software. Using the variable in this way causes the stable version of the recipe to build by default in the absence of PREFERRED_VERSION being used to build the development version. The bias provided by DEFAULT_PREFERENCE is weak and is overridden by BBFILE_PRIORITY if that variable is different between two layers that contain different versions of the same recipe. DEPENDS Lists a recipe's build-time dependencies (i.e. other recipe files). Consider this simple example for two recipes named "a" and "b" that produce similarly named packages. In this example, the DEPENDS statement appears in the "a" recipe: DEPENDS = "b" Here, the dependency is such that the do_configure task for recipe "a" depends on the do_populate_sysroot task of recipe "b". This means anything that recipe "b" puts into sysroot is available when recipe "a" is configuring itself. For information on runtime dependencies, see the RDEPENDS variable. DESCRIPTION A long description for the recipe. DL_DIR The central download directory used by the build process to store downloads. By default, DL_DIR gets files suitable for mirroring for everything except Git repositories. If you want tarballs of Git repositories, use the BB_GENERATE_MIRROR_TARBALLS variable. EXCLUDE_FROM_WORLD Directs BitBake to exclude a recipe from world builds (i.e. bitbake world). During world builds, BitBake locates, parses and builds all recipes found in every layer exposed in the bblayers.conf configuration file. To exclude a recipe from a world build using this variable, set the variable to "1" in the recipe. Recipes added to EXCLUDE_FROM_WORLD may still be built during a world build in order to satisfy dependencies of other recipes. Adding a recipe to EXCLUDE_FROM_WORLD only ensures that the recipe is not explicitly added to the list of build targets in a world build. FILESPATH The default set of directories BitBake uses when searching for patches and files. During the build process, BitBake searches each directory in FILESPATH in the specified order when looking for files and patches specified by each file:// URI in a recipe. HOMEPAGE Website where more information about the software the recipe is building can be found. INHERIT Causes the named class to be inherited at this point during parsing. The variable is only valid in configuration files. LAYERDEPENDS Lists the layers, separated by spaces, upon which this recipe depends. Optionally, you can specify a specific layer version for a dependency by adding it to the end of the layer name with a colon, (e.g. "anotherlayer:3" to be compared against LAYERVERSION_anotherlayer in this case). BitBake produces an error if any dependency is missing or the version numbers do not match exactly (if specified). You use this variable in the conf/layer.conf file. You must also use the specific layer name as a suffix to the variable (e.g. LAYERDEPENDS_mylayer). LAYERDIR When used inside the layer.conf configuration file, this variable provides the path of the current layer. This variable is not available outside of layer.conf and references are expanded immediately when parsing of the file completes. LAYERVERSION Optionally specifies the version of a layer as a single number. You can use this variable within LAYERDEPENDS for another layer in order to depend on a specific version of the layer. You use this variable in the conf/layer.conf file. You must also use the specific layer name as a suffix to the variable (e.g. LAYERDEPENDS_mylayer). LICENSE The list of source licenses for the recipe. MIRRORS Specifies additional paths from which BitBake gets source code. When the build system searches for source code, it first tries the local download directory. If that location fails, the build system tries locations defined by PREMIRRORS, the upstream source, and then locations specified by MIRRORS in that order. Assuming your distribution (DISTRO) is "poky", the default value for MIRRORS is defined in the conf/distro/poky.conf file in the meta-yocto Git repository. OVERRIDES BitBake uses OVERRIDES to control what variables are overridden after BitBake parses recipes and configuration files. You can find more information on how overrides are handled in the "Conditional Syntax (Overrides)" section. PACKAGES The list of packages the recipe creates. PACKAGES_DYNAMIC A promise that your recipe satisfies runtime dependencies for optional modules that are found in other recipes. PACKAGES_DYNAMIC does not actually satisfy the dependencies, it only states that they should be satisfied. For example, if a hard, runtime dependency (RDEPENDS) of another package is satisfied during the build through the PACKAGES_DYNAMIC variable, but a package with the module name is never actually produced, then the other package will be broken. Thus, if you attempt to include that package in an image, you will get a dependency failure from the packaging system during do_rootfs. PE The epoch of the recipe. By default, this variable is unset. The variable is used to make upgrades possible when the versioning scheme changes in some backwards incompatible way. PF Specifies the recipe or package name and includes all version and revision numbers (i.e. eglibc-2.13-r20+svnr15508/ and bash-4.2-r1/). PN The recipe name. PR The revision of the recipe. PREFERRED_PROVIDER If multiple recipes provide an item, this variable determines which recipe should be given preference. You should always suffix the variable with the name of the provided item, and you should set it to the PN of the recipe to which you want to give precedence. Some examples: PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto" PREFERRED_PROVIDER_virtual/xserver = "xserver-xf86" PREFERRED_PROVIDER_virtual/libgl ?= "mesa" PREFERRED_VERSION If there are multiple versions of recipes available, this variable determines which recipe should be given preference. You must always suffix the variable with the PN you want to select, and you should set PV accordingly for precedence. You can use the "%" character as a wildcard to match any number of characters, which can be useful when specifying versions that contain long revision numbers that could potentially change. Here are two examples: PREFERRED_VERSION_python = "2.7.3" PREFERRED_VERSION_linux-yocto = "3.10%" PREMIRRORS Specifies additional paths from which BitBake gets source code. When the build system searches for source code, it first tries the local download directory. If that location fails, the build system tries locations defined by PREMIRRORS, the upstream source, and then locations specified by MIRRORS in that order. Assuming your distribution (DISTRO) is "poky", the default value for PREMIRRORS is defined in the conf/distro/poky.conf file in the meta-yocto Git repository. Typically, you would add a specific server for the build system to attempt before any others by adding something like the following to your configuration: PREMIRRORS_prepend = "\ git://.*/.* http://www.yoctoproject.org/sources/ \n \ ftp://.*/.* http://www.yoctoproject.org/sources/ \n \ http://.*/.* http://www.yoctoproject.org/sources/ \n \ https://.*/.* http://www.yoctoproject.org/sources/ \n" These changes cause the build system to intercept Git, FTP, HTTP, and HTTPS requests and direct them to the http:// sources mirror. You can use file:// URLs to point to local directories or network shares as well. PROVIDES A list of aliases that a recipe also provides. These aliases are useful for satisfying dependencies of other recipes during the build (as specified by DEPENDS). A recipe's own PN is implicitly already in its PROVIDES list. PRSERV_HOST The network based PR service host and port. Following is an example of how the PRSERV_HOST variable is set: PRSERV_HOST = "localhost:0" You must set the variable if you want to automatically start a local PR service. You can set PRSERV_HOST to other values to use a remote PR service. PV The version of the recipe. RDEPENDS Lists a package's runtime dependencies (i.e. other packages) that must be installed in order for the built package to run correctly. If a package in this list cannot be found during the build, you will get a build error. Because the RDEPENDS variable applies to packages being built, you should always use the variable in a form with an attached package name. For example, suppose you are building a development package that depends on the perl package. In this case, you would use the following RDEPENDS statement: RDEPENDS_${PN}-dev += "perl" In the example, the development package depends on the perl package. Thus, the RDEPENDS variable has the ${PN}-dev package name as part of the variable. BitBake supports specifying versioned dependencies. Although the syntax varies depending on the packaging format, BitBake hides these differences from you. Here is the general syntax to specify versions with the RDEPENDS variable: RDEPENDS_${PN} = "<package> (<operator> <version>)" For operator, you can specify the following: = < > <= >= For example, the following sets up a dependency on version 1.2 or greater of the package foo: RDEPENDS_${PN} = "foo (>= 1.2)" For information on build-time dependencies, see the DEPENDS variable. RPROVIDES A list of package name aliases that a package also provides. These aliases are useful for satisfying runtime dependencies of other packages both during the build and on the target (as specified by RDEPENDS). As with all package-controlling variables, you must always use the variable in conjunction with a package name override. Here is an example: RPROVIDES_${PN} = "widget-abi-2" RRECOMMENDS A list of packages that extends the usability of a package being built. The package being built does not depend on this list of packages in order to successfully build, but needs them for the extended usability. To specify runtime dependencies for packages, see the RDEPENDS variable. BitBake supports specifying versioned recommends. Although the syntax varies depending on the packaging format, BitBake hides these differences from you. Here is the general syntax to specify versions with the RRECOMMENDS variable: RRECOMMENDS_${PN} = "<package> (<operator> <version>)" For operator, you can specify the following: = < > <= >= For example, the following sets up a recommend on version 1.2 or greater of the package foo: RRECOMMENDS_${PN} = "foo (>= 1.2)" SECTION The section in which packages should be categorized. SRC_URI The list of source files - local or remote. This variable tells BitBake which bits to pull in for the build and how to pull them in. For example, if the recipe or append file only needs to fetch a tarball from the Internet, the recipe or append file uses a SRC_URI entry that specifies just the tarball. On the other hand, if the recipe or append file needs to fetch a tarball, apply two patches, and include a custom file, the recipe or append file needs an SRC_URI variable that specifies all those sources. The following list explains the available URI protocols: file:// - Fetches files, which are usually files shipped with the metadata, from the local machine. The path is relative to the FILESPATH variable. Thus, the build system searches, in order, from the following directories, which are assumed to be a subdirectories of the directory in which the recipe file (.bb) or append file (.bbappend) resides: ${BPN} - The base recipe name without any special suffix or version numbers. ${BP} - ${BPN}-${PV}. The base recipe name and version but without any special package name suffix. files - Files within a directory that is named files and is also alongside the recipe or append file. If you want the build system to pick up files specified through a SRC_URI statement from your append file, you need to be sure to extend the FILESPATH variable by also using the FILESEXTRAPATHS variable from within your append file. bzr:// - Fetches files from a Bazaar revision control repository. git:// - Fetches files from a Git revision control repository. osc:// - Fetches files from an OSC (OpenSUSE Build service) revision control repository. repo:// - Fetches files from a repo (Git) repository. svk:// - Fetches files from an SVK revision control repository. http:// - Fetches files from the Internet using HTTP. https:// - Fetches files from the Internet using HTTPS. ftp:// - Fetches files from the Internet using FTP. cvs:// - Fetches files from a CVS revision control repository. hg:// - Fetches files from a Mercurial (hg) revision control repository. p4:// - Fetches files from a Perforce (p4) revision control repository. ssh:// - Fetches files from a secure shell. svn:// - Fetches files from a Subversion (svn) revision control repository. Standard and recipe-specific options for SRC_URI exist. Here are standard options: apply - Whether to apply the patch or not. The default action is to apply the patch. striplevel - Which striplevel to use when applying the patch. The default level is 1. patchdir - Specifies the directory in which the patch should be applied. The default is ${S}. Here are options specific to recipes building code from a revision control system: mindate - Apply the patch only if SRCDATE is equal to or greater than mindate. maxdate - Apply the patch only if SRCDATE is not later than mindate. minrev - Apply the patch only if SRCREV is equal to or greater than minrev. maxrev - Apply the patch only if SRCREV is not later than maxrev. rev - Apply the patch only if SRCREV is equal to rev. notrev - Apply the patch only if SRCREV is not equal to rev. Here are some additional options worth mentioning: unpack - Controls whether or not to unpack the file if it is an archive. The default action is to unpack the file. subdir - Places the file (or extracts its contents) into the specified subdirectory of WORKDIR. This option is useful for unusual tarballs or other archives that do not have their files already in a subdirectory within the archive. name - Specifies a name to be used for association with SRC_URI checksums when you have more than one file specified in SRC_URI. downloadfilename - Specifies the filename used when storing the downloaded file. SRCDATE The date of the source code used to build the package. This variable applies only if the source was fetched from a Source Code Manager (SCM). SRCREV The revision of the source code used to build the package. This variable applies only when using Subversion, Git, Mercurial and Bazaar. If you want to build a fixed revision and you want to avoid performing a query on the remote repository every time BitBake parses your recipe, you should specify a SRCREV that is a full revision identifier and not just a tag. STAMP Specifies the base path used to create recipe stamp files. The path to an actual stamp file is constructed by evaluating this string and then appending additional information. STAMPCLEAN Specifies the base path used to create recipe stamp files. Unlike the STAMP variable, STAMPCLEAN can contain wildcards to match the range of files a clean operation should remove. BitBake uses a clean operation to remove any other stamps it should be removing when creating a new stamp. SUMMARY A short summary for the recipe, which is 72 characters or less. T Points to a directory were BitBake places temporary files, which consist mostly of task logs and scripts, when building a particular recipe. TOPDIR Points to the build directory. BitBake automatically sets this variable.