diff options
author | Nicolas Dechesne <nicolas.dechesne@linaro.org> | 2020-07-01 17:17:11 +0200 |
---|---|---|
committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2020-09-16 18:13:44 +0100 |
commit | e8359fd85ce0358019e2a32b4c47ba76613f48f0 (patch) | |
tree | 30b85a0713fe37102da7ff890634d586dfde1a30 /doc/bitbake-user-manual | |
parent | 6bf6c8d63787aed7624793c24af3fa603b5ac961 (diff) | |
download | bitbake-contrib-e8359fd85ce0358019e2a32b4c47ba76613f48f0.tar.gz |
sphinx: bitbake-user-manual: use builtin sphinx glossary
Sphinx has a glossary directive. From the documentation:
This directive must contain a reST definition list with terms and
definitions. The definitions will then be referencable with the 'term'
role.
So anywhere in *any* manual, we can do :term:`VAR` to refer to an item
from the glossary, and create a link.
An HTML anchor is created for each term in the glossary, and can be
accessed as:
<link>/ref-variables.html#term-<NAME>
To convert to a glossary, we needed proper indentation (e.g. added 3
spaces to each line)
Signed-off-by: Nicolas Dechesne <nicolas.dechesne@linaro.org>
Diffstat (limited to 'doc/bitbake-user-manual')
-rw-r--r-- | doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst | 2438 |
1 files changed, 1236 insertions, 1202 deletions
diff --git a/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst b/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst index 41a77b3bc..efc496039 100644 --- a/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst +++ b/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst @@ -23,1213 +23,1247 @@ overview of their function and contents. not appear in the BitBake glossary. These other variables are variables used in systems that use BitBake. -`A <#var-bb-ASSUME_PROVIDED>`__ `B <#var-bb-B>`__ `C <#var-bb-CACHE>`__ -`D <#var-bb-DEFAULT_PREFERENCE>`__ `E <#var-bb-EXCLUDE_FROM_WORLD>`__ -`F <#var-bb-FAKEROOT>`__ `G <#var-bb-GITDIR>`__ `H <#var-bb-HGDIR>`__ -`I <#var-bb-INHERIT>`__ `L <#var-bb-LAYERDEPENDS>`__ -`M <#var-bb-MIRRORS>`__ `O <#var-bb-OVERRIDES>`__ `P <#var-bb-P4DIR>`__ -`R <#var-bb-RDEPENDS>`__ `S <#var-bb-SECTION>`__ `T <#var-bb-T>`__ - -ASSUME_PROVIDED - Lists recipe names (```PN`` <#var-bb-PN>`__ values) BitBake does not - attempt to build. Instead, BitBake assumes these recipes have already - been built. - - In OpenEmbedded-Core, ``ASSUME_PROVIDED`` mostly specifies native - tools that should not be built. An example is ``git-native``, which - when specified allows for 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_ALLOWED_NETWORKS - Specifies a space-delimited list of hosts that the fetcher is allowed - to use to obtain the required source code. Following are - considerations surrounding this variable: - - - This host list is only used if - ```BB_NO_NETWORK`` <#var-bb-BB_NO_NETWORK>`__ is either not set or - set to "0". - - - Limited support for the "``*``" wildcard character for matching - against the beginning of host names exists. For example, the - following setting matches ``git.gnu.org``, ``ftp.gnu.org``, and - ``foo.git.gnu.org``. BB_ALLOWED_NETWORKS = "*.gnu.org" +.. glossary:: + + ASSUME_PROVIDED + Lists recipe names (```PN`` <#var-bb-PN>`__ values) BitBake does not + attempt to build. Instead, BitBake assumes these recipes have already + been built. + + In OpenEmbedded-Core, ``ASSUME_PROVIDED`` mostly specifies native + tools that should not be built. An example is ``git-native``, which + when specified allows for 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_ALLOWED_NETWORKS + Specifies a space-delimited list of hosts that the fetcher is allowed + to use to obtain the required source code. Following are + considerations surrounding this variable: + + - This host list is only used if + ```BB_NO_NETWORK`` <#var-bb-BB_NO_NETWORK>`__ is either not set or + set to "0". + + - Limited support for the "``*``" wildcard character for matching + against the beginning of host names exists. For example, the + following setting matches ``git.gnu.org``, ``ftp.gnu.org``, and + ``foo.git.gnu.org``. BB_ALLOWED_NETWORKS = "*.gnu.org" + + .. note:: + + The use of the "``*``" character only works at the beginning of + a host name and it must be isolated from the remainder of the + host name. You cannot use the wildcard character in any other + location of the name or combined with the front part of the + name. + + For example, ``*.foo.bar`` is supported, while ``*aa.foo.bar`` + is not. + + - Mirrors not in the host list are skipped and logged in debug. + + - Attempts to access networks not in the host list cause a failure. + + Using ``BB_ALLOWED_NETWORKS`` in conjunction with + ```PREMIRRORS`` <#var-bb-PREMIRRORS>`__ is very useful. Adding the + host you want to use to ``PREMIRRORS`` results in the source code + being fetched from an allowed location and avoids raising an error + when a host that is not allowed is in a + ```SRC_URI`` <#var-bb-SRC_URI>`__ statement. This is because the + fetcher does not attempt to use the host listed in ``SRC_URI`` after + a successful fetch from the ``PREMIRRORS`` occurs. + + BB_CONSOLELOG + Specifies the path to a log file into which BitBake's user interface + writes output during the build. + + 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_DEFAULT_TASK + The default task to use when none is specified (e.g. with the ``-c`` + command line option). The task name specified should not include the + ``do_`` prefix. + + 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 <#var-bb-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`` <#var-bb-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`` <#var-bb-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_ENV_WHITELIST + Specifies the internal whitelist of variables to allow through from + the external environment into BitBake's datastore. If the value of + this variable is not specified (which is the default), the following + list is used: ```BBPATH`` <#var-bb-BBPATH>`__, + ```BB_PRESERVE_ENV`` <#var-bb-BB_PRESERVE_ENV>`__, + ```BB_ENV_WHITELIST`` <#var-bb-BB_ENV_WHITELIST>`__, and + ```BB_ENV_EXTRAWHITE`` <#var-bb-BB_ENV_EXTRAWHITE>`__. .. note:: - The use of the "``*``" character only works at the beginning of - a host name and it must be isolated from the remainder of the - host name. You cannot use the wildcard character in any other - location of the name or combined with the front part of the - name. - - For example, ``*.foo.bar`` is supported, while ``*aa.foo.bar`` - is not. - - - Mirrors not in the host list are skipped and logged in debug. - - - Attempts to access networks not in the host list cause a failure. - - Using ``BB_ALLOWED_NETWORKS`` in conjunction with - ```PREMIRRORS`` <#var-bb-PREMIRRORS>`__ is very useful. Adding the - host you want to use to ``PREMIRRORS`` results in the source code - being fetched from an allowed location and avoids raising an error - when a host that is not allowed is in a - ```SRC_URI`` <#var-bb-SRC_URI>`__ statement. This is because the - fetcher does not attempt to use the host listed in ``SRC_URI`` after - a successful fetch from the ``PREMIRRORS`` occurs. - -BB_CONSOLELOG - Specifies the path to a log file into which BitBake's user interface - writes output during the build. - -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_DEFAULT_TASK - The default task to use when none is specified (e.g. with the ``-c`` - command line option). The task name specified should not include the - ``do_`` prefix. - -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 <#var-bb-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`` <#var-bb-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`` <#var-bb-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_ENV_WHITELIST - Specifies the internal whitelist of variables to allow through from - the external environment into BitBake's datastore. If the value of - this variable is not specified (which is the default), the following - list is used: ```BBPATH`` <#var-bb-BBPATH>`__, - ```BB_PRESERVE_ENV`` <#var-bb-BB_PRESERVE_ENV>`__, - ```BB_ENV_WHITELIST`` <#var-bb-BB_ENV_WHITELIST>`__, and - ```BB_ENV_EXTRAWHITE`` <#var-bb-BB_ENV_EXTRAWHITE>`__. - - .. note:: - - You must set this variable in the external environment in order - for it to work. - -BB_ENV_EXTRAWHITE - Specifies an additional set of variables to allow through (whitelist) - from the external environment into BitBake's datastore. This list of - variables are on top of the internal list set in - ```BB_ENV_WHITELIST`` <#var-bb-BB_ENV_WHITELIST>`__. - - .. note:: - - You must set this variable in the external environment in order - for it to work. - -BB_FETCH_PREMIRRORONLY - When set to "1", causes BitBake's fetcher module to only search - ```PREMIRRORS`` <#var-bb-PREMIRRORS>`__ for files. BitBake will not - search the main ```SRC_URI`` <#var-bb-SRC_URI>`__ or - ```MIRRORS`` <#var-bb-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`` <#var-bb-DL_DIR>`__ directory. Anyone - wishing to create a source mirror would want to enable this variable. - - 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 - Lists variables that are excluded from base configuration checksum, - which is used to determine if the cache can be reused. - - One of the ways BitBake determines whether to re-parse the main - metadata is through checksums of the variables in the datastore of - the base configuration data. There are variables that you typically - want to exclude when checking whether or not to re-parse and thus - rebuild the cache. 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 reuse the cache. - -BB_HASHBASE_WHITELIST - Lists variables that are excluded from checksum and dependency data. - Variables that are excluded can therefore change without affecting - the checksum mechanism. A common example would be the variable for - the path of the build. BitBake's output should not (and usually does - not) depend on the directory in which it was built. - -BB_HASHCHECK_FUNCTION - Specifies the name of the function to call during the "setscene" part - of the task's execution in order to validate the list of task hashes. - The function returns the list of setscene tasks that should be - executed. - - At this point in the execution of the code, the objective is to - quickly verify if a given setscene function is likely to work or not. - It's easier to check the list of setscene functions in one pass than - to call many individual tasks. The returned list need not be - completely accurate. A given setscene task can still later fail. - However, the more accurate the data returned, the more efficient the - build will be. - -BB_INVALIDCONF - Used in combination with the ``ConfigParsed`` event to trigger - re-parsing the base metadata (i.e. all the recipes). The - ``ConfigParsed`` event can set the variable to trigger the re-parse. - You must be careful to avoid recursive loops with this functionality. - -BB_LOGCONFIG - Specifies the name of a config file that contains the user logging - configuration. See `Logging <#logging>`__ for additional information - -BB_LOGFMT - Specifies the name of the log files saved into - ``${``\ ```T`` <#var-bb-T>`__\ ``}``. By default, the ``BB_LOGFMT`` - variable is undefined and the log file names get created using the - following form: log.{task}.{pid} If you want to force log files to - take a specific name, you can set this variable in a configuration - file. - -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`` <#var-bb-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_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_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_ORIGENV - Contains a copy of the original external environment in which BitBake - was run. The copy is taken before any whitelisted variable values are - filtered into BitBake's datastore. - - .. note:: - - The contents of this variable is a datastore object that can be - queried using the normal datastore operations. - -BB_PRESERVE_ENV - Disables whitelisting and instead allows all variables through from - the external environment into BitBake's datastore. - - .. note:: - - You must set this variable in the external environment in order - for it to work. - -BB_RUNFMT - Specifies the name of the executable script files (i.e. run files) - saved into ``${``\ ```T`` <#var-bb-T>`__\ ``}``. By default, the - ``BB_RUNFMT`` variable is undefined and the run file names get - created using the following form: run.{task}.{pid} If you want to - force run files to take a specific name, you can set this variable in - a configuration file. - -BB_RUNTASK - Contains the name of the currently executing task. The value includes - the "do_" prefix. For example, if the currently executing task is - ``do_config``, the value is "do_config". - -BB_SCHEDULER - Selects the name of the scheduler to use for the scheduling of - BitBake tasks. Three options exist: - - - *basic* - The basic framework from which everything derives. Using - this option causes tasks to be ordered numerically as they are - parsed. - - - *speed* - Executes tasks first that have more tasks depending on - them. The "speed" option is the default. - - - *completion* - Causes the scheduler to try to complete a given - recipe once its build has started. - -BB_SCHEDULERS - Defines custom schedulers to import. Custom schedulers need to be - derived from the ``RunQueueScheduler`` class. - - For information how to select a scheduler, see the - ```BB_SCHEDULER`` <#var-bb-BB_SCHEDULER>`__ variable. - -BB_SETSCENE_DEPVALID - Specifies a function BitBake calls that determines whether BitBake - requires a setscene dependency to be met. - - When running a setscene task, BitBake needs to know which - dependencies of that setscene task also need to be run. Whether - dependencies also need to be run is highly dependent on the metadata. - The function specified by this variable returns a "True" or "False" - depending on whether the dependency needs to be met. - -BB_SETSCENE_VERIFY_FUNCTION2 - Specifies a function to call that verifies the list of planned task - execution before the main task execution happens. The function is - called once BitBake has a list of setscene tasks that have run and - either succeeded or failed. - - The function allows for a task list check to see if they make sense. - Even if BitBake was planning to skip a task, the returned value of - the function can force BitBake to run the task, which is necessary - under certain metadata defined circumstances. - -BB_SIGNATURE_EXCLUDE_FLAGS - Lists variable flags (varflags) that can be safely excluded from - checksum and dependency data for keys in the datastore. When - generating checksum or dependency data for keys in the datastore, the - flags set against that key are normally included in the checksum. - - For more information on varflags, see the "`Variable - Flags <#variable-flags>`__" section. - -BB_SIGNATURE_HANDLER - Defines the name of the signature handler BitBake uses. The signature - handler defines the way stamp files are created and handled, if and - how the signature is incorporated into the stamps, and how the - signature itself is generated. - - A new signature handler can be added by injecting a class derived - from the ``SignatureGenerator`` class into the global namespace. - -BB_SRCREV_POLICY - Defines the behavior of the fetcher when it interacts with source - control systems and dynamic source revisions. The - ``BB_SRCREV_POLICY`` variable is useful when working without a - network. - - The variable can be set using one of two policies: - - - *cache* - Retains the value the system obtained previously rather - than querying the source control system each time. - - - *clear* - Queries the source controls system every time. With this - policy, there is no cache. The "clear" policy is the default. - -BB_STAMP_POLICY - Defines the mode used for how timestamps of stamp files are compared. - You can set the variable to one of the following modes: - - - *perfile* - Timestamp comparisons are only made between timestamps - of a specific recipe. This is the default mode. - - - *full* - Timestamp comparisons are made for all dependencies. - - - *whitelist* - Identical to "full" mode except timestamp - comparisons are made for recipes listed in the - ```BB_STAMP_WHITELIST`` <#var-bb-BB_STAMP_WHITELIST>`__ variable. - - .. note:: - - Stamp policies are largely obsolete with the introduction of - setscene tasks. - -BB_STAMP_WHITELIST - Lists files whose stamp file timestamps are compared when the stamp - policy mode is set to "whitelist". For information on stamp policies, - see the ```BB_STAMP_POLICY`` <#var-bb-BB_STAMP_POLICY>`__ variable. - -BB_STRICT_CHECKSUM - Sets a more strict checksum mechanism for non-local URLs. Setting - this variable to a value causes BitBake to report an error if it - encounters a non-local URL that does not have at least one checksum - specified. - -BB_TASK_IONICE_LEVEL - Allows adjustment of a task's Input/Output priority. During - Autobuilder testing, random failures can occur for tasks due to I/O - starvation. These failures occur during various QEMU runtime - timeouts. You can use the ``BB_TASK_IONICE_LEVEL`` variable to adjust - the I/O priority of these tasks. - - .. note:: - - This variable works similarly to the - BB_TASK_NICE_LEVEL - variable except with a task's I/O priorities. - - Set the variable as follows: BB_TASK_IONICE_LEVEL = "class.prio" For - class, the default value is "2", which is a best effort. You can use - "1" for realtime and "3" for idle. If you want to use realtime, you - must have superuser privileges. - - For prio, you can use any value from "0", which is the highest - priority, to "7", which is the lowest. The default value is "4". You - do not need any special privileges to use this range of priority - values. - - .. note:: - - In order for your I/O priority settings to take effect, you need - the Completely Fair Queuing (CFQ) Scheduler selected for the - backing block device. To select the scheduler, use the following - command form where - device - is the device (e.g. sda, sdb, and so forth): - :: - - $ sudo sh -c “echo cfq > /sys/block/device/queu/scheduler - - -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 <http://www.yoctoproject.org>`__ 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. - -BB_TASKHASH - Within an executing task, this variable holds the hash of the task as - returned by the currently enabled signature generator. - -BB_VERBOSE_LOGS - Controls how verbose BitBake is during builds. If set, shell scripts - echo commands and shell script output appears on standard out - (stdout). - -BB_WORKERCONTEXT - Specifies if the current context is executing a task. BitBake sets - this variable to "1" when a task is being executed. The value is not - set when the task is in server context during parsing or event - handling. - -BBCLASSEXTEND - Allows you to extend a recipe so that it builds variants of the - software. Some examples of these variants for recipes from the - OpenEmbedded-Core metadata are "natives" such as ``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 variable to your recipe. - Here are two examples. The "native" variants are from the - OpenEmbedded-Core metadata: BBCLASSEXTEND =+ "native nativesdk" - BBCLASSEXTEND =+ "multilib:multilib_name" - - .. note:: - - Internally, the ``BBCLASSEXTEND`` mechanism generates recipe - variants by rewriting variable values and applying overrides such - as ``_class-native``. For example, to generate a native version of - a recipe, a ```DEPENDS`` <#var-bb-DEPENDS>`__ on "foo" is - rewritten to a ``DEPENDS`` on "foo-native". - - Even when using ``BBCLASSEXTEND``, the recipe is only parsed once. - Parsing once adds some limitations. For example, it is not - possible to include a different file depending on the variant, - since ``include`` statements are processed when the recipe is - parsed. - -BBDEBUG - Sets the BitBake debug output level to a specific value as - incremented by the ``-D`` command line option. - - .. note:: - - You must set this variable in the external environment in order - for it to work. - -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`` <#var-bb-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`` <#var-bb-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). - - .. tip:: - - You can use the command - bitbake-layers show-layers - to list all configured layers along with their priorities. - -BBFILES - A space-separated list of recipe files BitBake uses to build - software. - - When specifying recipe files, you can pattern match using Python's - ```glob`` <https://docs.python.org/3/library/glob.html>`__ syntax. - For details on the syntax, see the documentation by following the - previous link. - -BBINCLUDED - Contains a space-separated list of all of all files that BitBake's - parser included during parsing of the current file. - -BBINCLUDELOGS - If set to a value, enables printing the task log when reporting a - failed task. - -BBINCLUDELOGS_LINES - If ```BBINCLUDELOGS`` <#var-bb-BBINCLUDELOGS>`__ is set, specifies - the maximum number of lines from the task log file to print when - reporting a failed task. If you do not set ``BBINCLUDELOGS_LINES``, - the entire log is printed. - -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``. - -BBLAYERS_FETCH_DIR - Sets the base location where layers are stored. This setting is used - in conjunction with ``bitbake-layers layerindex-fetch`` and tells - ``bitbake-layers`` where to place the fetched layers. - -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 any of the expressions. It is as if BitBake does not - see them at all. Consequently, matching files are not parsed or - otherwise used by BitBake. - - The values you provide are passed to Python's regular expression - compiler. Consequently, the syntax follows Python's Regular - Expression (re) syntax. The expressions are compared against the full - paths to the files. For complete syntax information, see Python's - documentation at ` <http://docs.python.org/3/library/re.html#re>`__. - - 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, you can - specify multiple 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 += "/meta-foo/.*/openldap" BBMASK - += "opencv.*\.bbappend" BBMASK += "lzma" - - .. note:: - - When specifying a directory name, use the trailing slash character - to ensure you match just that directory name. - -BBMULTICONFIG - Enables BitBake to perform multiple configuration builds and lists - each separate configuration (multiconfig). You can use this variable - to cause BitBake to build multiple targets where each target has a - separate configuration. Define ``BBMULTICONFIG`` in your - ``conf/local.conf`` configuration file. - - As an example, the following line specifies three multiconfigs, each - having a separate configuration file: BBMULTIFONFIG = "configA - configB configC" Each configuration file you use must reside in the - build directory within a directory named ``conf/multiconfig`` (e.g. - build_directory\ ``/conf/multiconfig/configA.conf``). - - For information on how to use ``BBMULTICONFIG`` in an environment - that supports building targets with multiple configurations, see the - "`Executing a Multiple Configuration - Build <#executing-a-multiple-configuration-build>`__" section. - -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. - -BBTARGETS - Allows you to use a configuration file to add to the list of - command-line target recipes you want to build. - -BBVERSIONS - Allows a single recipe to build multiple versions of a project from a - single recipe file. You also able to specify conditional metadata - using the ```OVERRIDES`` <#var-bb-OVERRIDES>`__ mechanism for a - single version or for an optionally named range of versions. - - For more information on ``BBVERSIONS``, see the "`Variants - Class - Extension Mechanism <#variants-class-extension-mechanism>`__" - section. - -BITBAKE_UI - Used to specify the UI module to use when running BitBake. Using this - variable is equivalent to using the ``-u`` command-line option. - - .. note:: - - You must set this variable in the external environment in order - for it to work. - -BUILDNAME - A name assigned to the build. The name defaults to a datetime stamp - of when the build was started but can be defined by the metadata. - -BZRDIR - The directory in which files checked out of a Bazaar system are - stored. - -CACHE - Specifies the directory BitBake uses to store a cache of the metadata - so it does not need to be parsed every time BitBake is started. - -CVSDIR - The directory in which files checked out under the CVS system are - stored. - -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. - - .. note:: - - 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`` <#var-bb-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`` <#var-bb-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. - - .. note:: - - 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. - -FAKEROOT - Contains the command to use when running a shell script in a fakeroot - environment. The ``FAKEROOT`` variable is obsolete and has been - replaced by the other ``FAKEROOT*`` variables. See these entries in - the glossary for more information. - -FAKEROOTBASEENV - Lists environment variables to set when executing the command defined - by ```FAKEROOTCMD`` <#var-bb-FAKEROOTCMD>`__ that starts the - bitbake-worker process in the fakeroot environment. - -FAKEROOTCMD - Contains the command that starts the bitbake-worker process in the - fakeroot environment. - -FAKEROOTDIRS - Lists directories to create before running a task in the fakeroot - environment. - -FAKEROOTENV - Lists environment variables to set when running a task in the - fakeroot environment. For additional information on environment - variables and the fakeroot environment, see the - ```FAKEROOTBASEENV`` <#var-bb-FAKEROOTBASEENV>`__ variable. - -FAKEROOTNOENV - Lists environment variables to set when running a task that is not in - the fakeroot environment. For additional information on environment - variables and the fakeroot environment, see the - ```FAKEROOTENV`` <#var-bb-FAKEROOTENV>`__ variable. - -FETCHCMD - Defines the command the BitBake fetcher module executes when running - fetch operations. You need to use an override suffix when you use the - variable (e.g. ``FETCHCMD_git`` or ``FETCHCMD_svn``). - -FILE - Points at the current file. BitBake sets this variable during the - parsing process to identify the file being parsed. BitBake also sets - this variable when a recipe is being executed to identify the recipe - file. - -FILESPATH - Specifies directories BitBake uses when searching for patches and - files. The "local" fetcher module uses these directories when - handling ``file://`` URLs. The variable behaves like a shell ``PATH`` - environment variable. The value is a colon-separated list of - directories that are searched left-to-right in order. - -GITDIR - The directory in which a local copy of a Git repository is stored - when it is cloned. - -HGDIR - The directory in which files checked out of a Mercurial system are - stored. - -HOMEPAGE - Website where more information about the software the recipe is - building can be found. - -INHERIT - Causes the named class or classes to be inherited globally. Anonymous - functions in the class or classes are not executed for the base - configuration and in each individual recipe. The OpenEmbedded build - system ignores changes to ``INHERIT`` in individual recipes. - - For more information on ``INHERIT``, see the "```INHERIT`` - Configuration Directive <#inherit-configuration-directive>`__" - section. - -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`` <#var-bb-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. - -LAYERDIR_RE - When used inside the ``layer.conf`` configuration file, this variable - provides the path of the current layer, escaped for use in a regular - expression (```BBFILE_PATTERN`` <#var-bb-BBFILE_PATTERN>`__). 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`` <#var-bb-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`` <#var-bb-PREMIRRORS>`__, the - upstream source, and then locations specified by ``MIRRORS`` in that - order. - -MULTI_PROVIDER_WHITELIST - Allows you to suppress BitBake warnings caused when building two - separate recipes that provide the same output. - - BitBake normally issues a warning when building two different recipes - where each provides the same output. This scenario is usually - something the user does not want. However, cases do exist where it - makes sense, particularly in the ``virtual/*`` namespace. You can use - this variable to suppress BitBake's warnings. - - To use the variable, list provider names (e.g. recipe names, - ``virtual/kernel``, and so forth). - -OVERRIDES - BitBake uses ``OVERRIDES`` to control what variables are overridden - after BitBake parses recipes and configuration files. - - Following is a simple example that uses an overrides list based on - machine architectures: OVERRIDES = "arm:x86:mips:powerpc" You can - find information on how to use ``OVERRIDES`` in the "`Conditional - Syntax (Overrides) <#conditional-syntax-overrides>`__" section. - -P4DIR - The directory in which a local copy of a Perforce depot is stored - when it is fetched. - -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`` <#var-bb-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. - -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. - -PERSISTENT_DIR - Specifies the directory BitBake uses to store data that should be - preserved between builds. In particular, the data stored is the data - that uses BitBake's persistent data API and the data used by the PR - Server and PR Service. - -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 - Determines which recipe should be given preference when multiple - recipes provide the same item. You should always suffix the variable - with the name of the provided item, and you should set it to the - ```PN`` <#var-bb-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_PROVIDERS - Determines which recipe should be given preference for cases where - multiple recipes provide the same item. Functionally, - ``PREFERRED_PROVIDERS`` is identical to - ```PREFERRED_PROVIDER`` <#var-bb-PREFERRED_PROVIDER>`__. However, the - ``PREFERRED_PROVIDERS`` variable lets you define preferences for - multiple situations using the following form: PREFERRED_PROVIDERS = - "xxx:yyy aaa:bbb ..." This form is a convenient replacement for the - following: PREFERRED_PROVIDER_xxx = "yyy" PREFERRED_PROVIDER_aaa = - "bbb" - -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`` <#var-bb-PN>`__ you want to - select, and you should set ```PV`` <#var-bb-PV>`__ accordingly for - precedence. - - The ``PREFERRED_VERSION`` variable supports limited wildcard use - through the "``%``" character. You can use the character to match any - number of characters, which can be useful when specifying versions - that contain long revision numbers that potentially change. Here are - two examples: PREFERRED_VERSION_python = "2.7.3" - PREFERRED_VERSION_linux-yocto = "4.12%" - - .. note:: - - The use of the " - % - " character is limited in that it only works at the end of the - string. You cannot use the wildcard character in any other - location of the string. - -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`` <#var-bb-MIRRORS>`__ in that - order. - - 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 by which a particular recipe can be known. By - default, a recipe's own ``PN`` is implicitly already in its - ``PROVIDES`` list. If a recipe uses ``PROVIDES``, the additional - aliases are synonyms for the recipe and can be useful satisfying - dependencies of other recipes during the build as specified by - ``DEPENDS``. - - Consider the following example ``PROVIDES`` statement from a recipe - file ``libav_0.8.11.bb``: PROVIDES += "libpostproc" The ``PROVIDES`` - statement results in the "libav" recipe also being known as - "libpostproc". - - In addition to providing recipes under alternate names, the - ``PROVIDES`` mechanism is also used to implement virtual targets. A - virtual target is a name that corresponds to some particular - functionality (e.g. a Linux kernel). Recipes that provide the - functionality in question list the virtual target in ``PROVIDES``. - Recipes that depend on the functionality in question can include the - virtual target in ```DEPENDS`` <#var-bb-DEPENDS>`__ to leave the - choice of provider open. - - Conventionally, virtual targets have names on the form - "virtual/function" (e.g. "virtual/kernel"). The slash is simply part - of the name and has no syntactical significance. - -PRSERV_HOST - The network based ```PR`` <#var-bb-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`` <#var-bb-DEPENDS>`__ variable. - -REPODIR - The directory in which a local copy of a ``google-repo`` directory is - stored when it is synced. - -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 for the build and how to pull them. For - example, if the recipe or append file needs to fetch a single tarball - from the Internet, the recipe or append file uses a ``SRC_URI`` entry - that specifies that tarball. On the other hand, if the recipe or - append file needs to fetch a tarball 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`` <#var-bb-FILESPATH>`__ variable. - - - *``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. - - - *``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. - - 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. 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. - -SRCREV_FORMAT - Helps construct valid ```SRCREV`` <#var-bb-SRCREV>`__ values when - multiple source controlled URLs are used in - ```SRC_URI`` <#var-bb-SRC_URI>`__. - - The system needs help constructing these values under these - circumstances. Each component in the ``SRC_URI`` is assigned a name - and these are referenced in the ``SRCREV_FORMAT`` variable. Consider - an example with URLs named "machine" and "meta". In this case, - ``SRCREV_FORMAT`` could look like "machine_meta" and those names - would have the SCM versions substituted into each position. Only one - ``AUTOINC`` placeholder is added and if needed. And, this placeholder - is placed at the start of the returned string. - -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. + You must set this variable in the external environment in order + for it to work. -STAMPCLEAN - Specifies the base path used to create recipe stamp files. Unlike the - ```STAMP`` <#var-bb-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. + BB_ENV_EXTRAWHITE + Specifies an additional set of variables to allow through (whitelist) + from the external environment into BitBake's datastore. This list of + variables are on top of the internal list set in + ```BB_ENV_WHITELIST`` <#var-bb-BB_ENV_WHITELIST>`__. -SUMMARY - A short summary for the recipe, which is 72 characters or less. + .. note:: + + You must set this variable in the external environment in order + for it to work. + + BB_FETCH_PREMIRRORONLY + When set to "1", causes BitBake's fetcher module to only search + ```PREMIRRORS`` <#var-bb-PREMIRRORS>`__ for files. BitBake will not + search the main ```SRC_URI`` <#var-bb-SRC_URI>`__ or + ```MIRRORS`` <#var-bb-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". + + BBFILES_DYNAMIC + Activates content depending on presence of identified layers. You + identify the layers by the collections that the layers define. + + Use the ``BBFILES_DYNAMIC`` variable to avoid ``.bbappend`` files whose + corresponding ``.bb`` file is in a layer that attempts to modify other + layers through ``.bbappend`` but does not want to introduce a hard + dependency on those other layers. + + Additionally you can prefix the rule with "!" to add ``.bbappend`` and + ``.bb`` files in case a layer is not present. Use this avoid hard + dependency on those other layers. + + Use the following form for ``BBFILES_DYNAMIC``: :: + + collection_name:filename_pattern + + The following example identifies two collection names and two filename + patterns: :: + + BBFILES_DYNAMIC += "\ + clang-layer:${LAYERDIR}/bbappends/meta-clang/*/*/*.bbappend \ + core:${LAYERDIR}/bbappends/openembedded-core/meta/*/*/*.bbappend \ + " + + When the collection name is prefixed with "!" it will add the file pattern in case + the layer is absent: :: + + BBFILES_DYNAMIC += "\ + !clang-layer:${LAYERDIR}/backfill/meta-clang/*/*/*.bb \ + " + + This next example shows an error message that occurs because invalid + entries are found, which cause parsing to abort: :: + + ERROR: BBFILES_DYNAMIC entries must be of the form {!}<collection name>:<filename pattern>, not: + /work/my-layer/bbappends/meta-security-isafw/*/*/*.bbappend + /work/my-layer/bbappends/openembedded-core/meta/*/*/*.bbappend + + BB_GENERATE_MIRROR_TARBALLS + Causes tarballs of the Git repositories, including the Git metadata, + to be placed in the ```DL_DIR`` <#var-bb-DL_DIR>`__ directory. Anyone + wishing to create a source mirror would want to enable this variable. + + 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 + Lists variables that are excluded from base configuration checksum, + which is used to determine if the cache can be reused. + + One of the ways BitBake determines whether to re-parse the main + metadata is through checksums of the variables in the datastore of + the base configuration data. There are variables that you typically + want to exclude when checking whether or not to re-parse and thus + rebuild the cache. 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 reuse the cache. + + BB_HASHBASE_WHITELIST + Lists variables that are excluded from checksum and dependency data. + Variables that are excluded can therefore change without affecting + the checksum mechanism. A common example would be the variable for + the path of the build. BitBake's output should not (and usually does + not) depend on the directory in which it was built. + + BB_HASHCHECK_FUNCTION + Specifies the name of the function to call during the "setscene" part + of the task's execution in order to validate the list of task hashes. + The function returns the list of setscene tasks that should be + executed. + + At this point in the execution of the code, the objective is to + quickly verify if a given setscene function is likely to work or not. + It's easier to check the list of setscene functions in one pass than + to call many individual tasks. The returned list need not be + completely accurate. A given setscene task can still later fail. + However, the more accurate the data returned, the more efficient the + build will be. + + BB_INVALIDCONF + Used in combination with the ``ConfigParsed`` event to trigger + re-parsing the base metadata (i.e. all the recipes). The + ``ConfigParsed`` event can set the variable to trigger the re-parse. + You must be careful to avoid recursive loops with this functionality. + + BB_LOGCONFIG + Specifies the name of a config file that contains the user logging + configuration. See `Logging <#logging>`__ for additional information + + BB_LOGFMT + Specifies the name of the log files saved into + ``${``\ ```T`` <#var-bb-T>`__\ ``}``. By default, the ``BB_LOGFMT`` + variable is undefined and the log file names get created using the + following form: log.{task}.{pid} If you want to force log files to + take a specific name, you can set this variable in a configuration + file. + + 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`` <#var-bb-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_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_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_ORIGENV + Contains a copy of the original external environment in which BitBake + was run. The copy is taken before any whitelisted variable values are + filtered into BitBake's datastore. + + .. note:: + + The contents of this variable is a datastore object that can be + queried using the normal datastore operations. + + BB_PRESERVE_ENV + Disables whitelisting and instead allows all variables through from + the external environment into BitBake's datastore. + + .. note:: + + You must set this variable in the external environment in order + for it to work. + + BB_RUNFMT + Specifies the name of the executable script files (i.e. run files) + saved into ``${``\ ```T`` <#var-bb-T>`__\ ``}``. By default, the + ``BB_RUNFMT`` variable is undefined and the run file names get + created using the following form: run.{task}.{pid} If you want to + force run files to take a specific name, you can set this variable in + a configuration file. + + BB_RUNTASK + Contains the name of the currently executing task. The value includes + the "do_" prefix. For example, if the currently executing task is + ``do_config``, the value is "do_config". + + BB_SCHEDULER + Selects the name of the scheduler to use for the scheduling of + BitBake tasks. Three options exist: + + - *basic* - The basic framework from which everything derives. Using + this option causes tasks to be ordered numerically as they are + parsed. + + - *speed* - Executes tasks first that have more tasks depending on + them. The "speed" option is the default. + + - *completion* - Causes the scheduler to try to complete a given + recipe once its build has started. + + BB_SCHEDULERS + Defines custom schedulers to import. Custom schedulers need to be + derived from the ``RunQueueScheduler`` class. + + For information how to select a scheduler, see the + ```BB_SCHEDULER`` <#var-bb-BB_SCHEDULER>`__ variable. + + BB_SETSCENE_DEPVALID + Specifies a function BitBake calls that determines whether BitBake + requires a setscene dependency to be met. + + When running a setscene task, BitBake needs to know which + dependencies of that setscene task also need to be run. Whether + dependencies also need to be run is highly dependent on the metadata. + The function specified by this variable returns a "True" or "False" + depending on whether the dependency needs to be met. + + BB_SETSCENE_VERIFY_FUNCTION2 + Specifies a function to call that verifies the list of planned task + execution before the main task execution happens. The function is + called once BitBake has a list of setscene tasks that have run and + either succeeded or failed. + + The function allows for a task list check to see if they make sense. + Even if BitBake was planning to skip a task, the returned value of + the function can force BitBake to run the task, which is necessary + under certain metadata defined circumstances. + + BB_SIGNATURE_EXCLUDE_FLAGS + Lists variable flags (varflags) that can be safely excluded from + checksum and dependency data for keys in the datastore. When + generating checksum or dependency data for keys in the datastore, the + flags set against that key are normally included in the checksum. + + For more information on varflags, see the "`Variable + Flags <#variable-flags>`__" section. + + BB_SIGNATURE_HANDLER + Defines the name of the signature handler BitBake uses. The signature + handler defines the way stamp files are created and handled, if and + how the signature is incorporated into the stamps, and how the + signature itself is generated. + + A new signature handler can be added by injecting a class derived + from the ``SignatureGenerator`` class into the global namespace. + + BB_SRCREV_POLICY + Defines the behavior of the fetcher when it interacts with source + control systems and dynamic source revisions. The + ``BB_SRCREV_POLICY`` variable is useful when working without a + network. + + The variable can be set using one of two policies: + + - *cache* - Retains the value the system obtained previously rather + than querying the source control system each time. + + - *clear* - Queries the source controls system every time. With this + policy, there is no cache. The "clear" policy is the default. + + BB_STAMP_POLICY + Defines the mode used for how timestamps of stamp files are compared. + You can set the variable to one of the following modes: + + - *perfile* - Timestamp comparisons are only made between timestamps + of a specific recipe. This is the default mode. + + - *full* - Timestamp comparisons are made for all dependencies. + + - *whitelist* - Identical to "full" mode except timestamp + comparisons are made for recipes listed in the + ```BB_STAMP_WHITELIST`` <#var-bb-BB_STAMP_WHITELIST>`__ variable. + + .. note:: + + Stamp policies are largely obsolete with the introduction of + setscene tasks. + + BB_STAMP_WHITELIST + Lists files whose stamp file timestamps are compared when the stamp + policy mode is set to "whitelist". For information on stamp policies, + see the ```BB_STAMP_POLICY`` <#var-bb-BB_STAMP_POLICY>`__ variable. + + BB_STRICT_CHECKSUM + Sets a more strict checksum mechanism for non-local URLs. Setting + this variable to a value causes BitBake to report an error if it + encounters a non-local URL that does not have at least one checksum + specified. + + BB_TASK_IONICE_LEVEL + Allows adjustment of a task's Input/Output priority. During + Autobuilder testing, random failures can occur for tasks due to I/O + starvation. These failures occur during various QEMU runtime + timeouts. You can use the ``BB_TASK_IONICE_LEVEL`` variable to adjust + the I/O priority of these tasks. + + .. note:: + + This variable works similarly to the + BB_TASK_NICE_LEVEL + variable except with a task's I/O priorities. + + Set the variable as follows: BB_TASK_IONICE_LEVEL = "class.prio" For + class, the default value is "2", which is a best effort. You can use + "1" for realtime and "3" for idle. If you want to use realtime, you + must have superuser privileges. + + For prio, you can use any value from "0", which is the highest + priority, to "7", which is the lowest. The default value is "4". You + do not need any special privileges to use this range of priority + values. + + .. note:: + + In order for your I/O priority settings to take effect, you need + the Completely Fair Queuing (CFQ) Scheduler selected for the + backing block device. To select the scheduler, use the following + command form where + device + is the device (e.g. sda, sdb, and so forth): + :: + + $ sudo sh -c “echo cfq > /sys/block/device/queu/scheduler + + + 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 <http://www.yoctoproject.org>`__ 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. + + BB_TASKHASH + Within an executing task, this variable holds the hash of the task as + returned by the currently enabled signature generator. + + BB_VERBOSE_LOGS + Controls how verbose BitBake is during builds. If set, shell scripts + echo commands and shell script output appears on standard out + (stdout). + + BB_WORKERCONTEXT + Specifies if the current context is executing a task. BitBake sets + this variable to "1" when a task is being executed. The value is not + set when the task is in server context during parsing or event + handling. + + BBCLASSEXTEND + Allows you to extend a recipe so that it builds variants of the + software. Some examples of these variants for recipes from the + OpenEmbedded-Core metadata are "natives" such as ``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 variable to your recipe. + Here are two examples. The "native" variants are from the + OpenEmbedded-Core metadata: BBCLASSEXTEND =+ "native nativesdk" + BBCLASSEXTEND =+ "multilib:multilib_name" + + .. note:: + + Internally, the ``BBCLASSEXTEND`` mechanism generates recipe + variants by rewriting variable values and applying overrides such + as ``_class-native``. For example, to generate a native version of + a recipe, a ```DEPENDS`` <#var-bb-DEPENDS>`__ on "foo" is + rewritten to a ``DEPENDS`` on "foo-native". + + Even when using ``BBCLASSEXTEND``, the recipe is only parsed once. + Parsing once adds some limitations. For example, it is not + possible to include a different file depending on the variant, + since ``include`` statements are processed when the recipe is + parsed. + + BBDEBUG + Sets the BitBake debug output level to a specific value as + incremented by the ``-D`` command line option. + + .. note:: + + You must set this variable in the external environment in order + for it to work. + + 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`` <#var-bb-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`` <#var-bb-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). + + .. tip:: + + You can use the command + bitbake-layers show-layers + to list all configured layers along with their priorities. + + BBFILES + A space-separated list of recipe files BitBake uses to build + software. + + When specifying recipe files, you can pattern match using Python's + ```glob`` <https://docs.python.org/3/library/glob.html>`__ syntax. + For details on the syntax, see the documentation by following the + previous link. + + BBINCLUDED + Contains a space-separated list of all of all files that BitBake's + parser included during parsing of the current file. + + BBINCLUDELOGS + If set to a value, enables printing the task log when reporting a + failed task. + + BBINCLUDELOGS_LINES + If ```BBINCLUDELOGS`` <#var-bb-BBINCLUDELOGS>`__ is set, specifies + the maximum number of lines from the task log file to print when + reporting a failed task. If you do not set ``BBINCLUDELOGS_LINES``, + the entire log is printed. + + 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``. + + BBLAYERS_FETCH_DIR + Sets the base location where layers are stored. This setting is used + in conjunction with ``bitbake-layers layerindex-fetch`` and tells + ``bitbake-layers`` where to place the fetched layers. + + 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 any of the expressions. It is as if BitBake does not + see them at all. Consequently, matching files are not parsed or + otherwise used by BitBake. + + The values you provide are passed to Python's regular expression + compiler. Consequently, the syntax follows Python's Regular + Expression (re) syntax. The expressions are compared against the full + paths to the files. For complete syntax information, see Python's + documentation at ` <http://docs.python.org/3/library/re.html#re>`__. + + 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, you can + specify multiple 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 += "/meta-foo/.*/openldap" BBMASK + += "opencv.*\.bbappend" BBMASK += "lzma" + + .. note:: + + When specifying a directory name, use the trailing slash character + to ensure you match just that directory name. + + BBMULTICONFIG + Enables BitBake to perform multiple configuration builds and lists + each separate configuration (multiconfig). You can use this variable + to cause BitBake to build multiple targets where each target has a + separate configuration. Define ``BBMULTICONFIG`` in your + ``conf/local.conf`` configuration file. + + As an example, the following line specifies three multiconfigs, each + having a separate configuration file: BBMULTIFONFIG = "configA + configB configC" Each configuration file you use must reside in the + build directory within a directory named ``conf/multiconfig`` (e.g. + build_directory\ ``/conf/multiconfig/configA.conf``). + + For information on how to use ``BBMULTICONFIG`` in an environment + that supports building targets with multiple configurations, see the + "`Executing a Multiple Configuration + Build <#executing-a-multiple-configuration-build>`__" section. + + 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. + + BBTARGETS + Allows you to use a configuration file to add to the list of + command-line target recipes you want to build. + + BBVERSIONS + Allows a single recipe to build multiple versions of a project from a + single recipe file. You also able to specify conditional metadata + using the ```OVERRIDES`` <#var-bb-OVERRIDES>`__ mechanism for a + single version or for an optionally named range of versions. + + For more information on ``BBVERSIONS``, see the "`Variants - Class + Extension Mechanism <#variants-class-extension-mechanism>`__" + section. + + BITBAKE_UI + Used to specify the UI module to use when running BitBake. Using this + variable is equivalent to using the ``-u`` command-line option. + + .. note:: + + You must set this variable in the external environment in order + for it to work. + + BUILDNAME + A name assigned to the build. The name defaults to a datetime stamp + of when the build was started but can be defined by the metadata. + + BZRDIR + The directory in which files checked out of a Bazaar system are + stored. + + CACHE + Specifies the directory BitBake uses to store a cache of the metadata + so it does not need to be parsed every time BitBake is started. + + CVSDIR + The directory in which files checked out under the CVS system are + stored. + + 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. + + .. note:: + + 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`` <#var-bb-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`` <#var-bb-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. + + .. note:: + + 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. + + FAKEROOT + Contains the command to use when running a shell script in a fakeroot + environment. The ``FAKEROOT`` variable is obsolete and has been + replaced by the other ``FAKEROOT*`` variables. See these entries in + the glossary for more information. + + FAKEROOTBASEENV + Lists environment variables to set when executing the command defined + by ```FAKEROOTCMD`` <#var-bb-FAKEROOTCMD>`__ that starts the + bitbake-worker process in the fakeroot environment. + + FAKEROOTCMD + Contains the command that starts the bitbake-worker process in the + fakeroot environment. + + FAKEROOTDIRS + Lists directories to create before running a task in the fakeroot + environment. + + FAKEROOTENV + Lists environment variables to set when running a task in the + fakeroot environment. For additional information on environment + variables and the fakeroot environment, see the + ```FAKEROOTBASEENV`` <#var-bb-FAKEROOTBASEENV>`__ variable. + + FAKEROOTNOENV + Lists environment variables to set when running a task that is not in + the fakeroot environment. For additional information on environment + variables and the fakeroot environment, see the + ```FAKEROOTENV`` <#var-bb-FAKEROOTENV>`__ variable. + + FETCHCMD + Defines the command the BitBake fetcher module executes when running + fetch operations. You need to use an override suffix when you use the + variable (e.g. ``FETCHCMD_git`` or ``FETCHCMD_svn``). + + FILE + Points at the current file. BitBake sets this variable during the + parsing process to identify the file being parsed. BitBake also sets + this variable when a recipe is being executed to identify the recipe + file. + + FILESPATH + Specifies directories BitBake uses when searching for patches and + files. The "local" fetcher module uses these directories when + handling ``file://`` URLs. The variable behaves like a shell ``PATH`` + environment variable. The value is a colon-separated list of + directories that are searched left-to-right in order. + + GITDIR + The directory in which a local copy of a Git repository is stored + when it is cloned. + + HGDIR + The directory in which files checked out of a Mercurial system are + stored. + + HOMEPAGE + Website where more information about the software the recipe is + building can be found. + + INHERIT + Causes the named class or classes to be inherited globally. Anonymous + functions in the class or classes are not executed for the base + configuration and in each individual recipe. The OpenEmbedded build + system ignores changes to ``INHERIT`` in individual recipes. + + For more information on ``INHERIT``, see the "```INHERIT`` + Configuration Directive <#inherit-configuration-directive>`__" + section. + + 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`` <#var-bb-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. + + LAYERDIR_RE + When used inside the ``layer.conf`` configuration file, this variable + provides the path of the current layer, escaped for use in a regular + expression (```BBFILE_PATTERN`` <#var-bb-BBFILE_PATTERN>`__). 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`` <#var-bb-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`` <#var-bb-PREMIRRORS>`__, the + upstream source, and then locations specified by ``MIRRORS`` in that + order. + + MULTI_PROVIDER_WHITELIST + Allows you to suppress BitBake warnings caused when building two + separate recipes that provide the same output. + + BitBake normally issues a warning when building two different recipes + where each provides the same output. This scenario is usually + something the user does not want. However, cases do exist where it + makes sense, particularly in the ``virtual/*`` namespace. You can use + this variable to suppress BitBake's warnings. + + To use the variable, list provider names (e.g. recipe names, + ``virtual/kernel``, and so forth). + + OVERRIDES + BitBake uses ``OVERRIDES`` to control what variables are overridden + after BitBake parses recipes and configuration files. + + Following is a simple example that uses an overrides list based on + machine architectures: OVERRIDES = "arm:x86:mips:powerpc" You can + find information on how to use ``OVERRIDES`` in the "`Conditional + Syntax (Overrides) <#conditional-syntax-overrides>`__" section. + + P4DIR + The directory in which a local copy of a Perforce depot is stored + when it is fetched. + + 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`` <#var-bb-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. + + 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. + + PERSISTENT_DIR + Specifies the directory BitBake uses to store data that should be + preserved between builds. In particular, the data stored is the data + that uses BitBake's persistent data API and the data used by the PR + Server and PR Service. + + 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 + Determines which recipe should be given preference when multiple + recipes provide the same item. You should always suffix the variable + with the name of the provided item, and you should set it to the + ```PN`` <#var-bb-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_PROVIDERS + Determines which recipe should be given preference for cases where + multiple recipes provide the same item. Functionally, + ``PREFERRED_PROVIDERS`` is identical to + ```PREFERRED_PROVIDER`` <#var-bb-PREFERRED_PROVIDER>`__. However, the + ``PREFERRED_PROVIDERS`` variable lets you define preferences for + multiple situations using the following form: PREFERRED_PROVIDERS = + "xxx:yyy aaa:bbb ..." This form is a convenient replacement for the + following: PREFERRED_PROVIDER_xxx = "yyy" PREFERRED_PROVIDER_aaa = + "bbb" + + 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`` <#var-bb-PN>`__ you want to + select, and you should set ```PV`` <#var-bb-PV>`__ accordingly for + precedence. + + The ``PREFERRED_VERSION`` variable supports limited wildcard use + through the "``%``" character. You can use the character to match any + number of characters, which can be useful when specifying versions + that contain long revision numbers that potentially change. Here are + two examples: PREFERRED_VERSION_python = "2.7.3" + PREFERRED_VERSION_linux-yocto = "4.12%" + + .. note:: + + The use of the " + % + " character is limited in that it only works at the end of the + string. You cannot use the wildcard character in any other + location of the string. + + 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`` <#var-bb-MIRRORS>`__ in that + order. + + 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 by which a particular recipe can be known. By + default, a recipe's own ``PN`` is implicitly already in its + ``PROVIDES`` list. If a recipe uses ``PROVIDES``, the additional + aliases are synonyms for the recipe and can be useful satisfying + dependencies of other recipes during the build as specified by + ``DEPENDS``. + + Consider the following example ``PROVIDES`` statement from a recipe + file ``libav_0.8.11.bb``: PROVIDES += "libpostproc" The ``PROVIDES`` + statement results in the "libav" recipe also being known as + "libpostproc". + + In addition to providing recipes under alternate names, the + ``PROVIDES`` mechanism is also used to implement virtual targets. A + virtual target is a name that corresponds to some particular + functionality (e.g. a Linux kernel). Recipes that provide the + functionality in question list the virtual target in ``PROVIDES``. + Recipes that depend on the functionality in question can include the + virtual target in ```DEPENDS`` <#var-bb-DEPENDS>`__ to leave the + choice of provider open. + + Conventionally, virtual targets have names on the form + "virtual/function" (e.g. "virtual/kernel"). The slash is simply part + of the name and has no syntactical significance. + + PRSERV_HOST + The network based ```PR`` <#var-bb-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`` <#var-bb-DEPENDS>`__ variable. + + REPODIR + The directory in which a local copy of a ``google-repo`` directory is + stored when it is synced. + + 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 for the build and how to pull them. For + example, if the recipe or append file needs to fetch a single tarball + from the Internet, the recipe or append file uses a ``SRC_URI`` entry + that specifies that tarball. On the other hand, if the recipe or + append file needs to fetch a tarball 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`` <#var-bb-FILESPATH>`__ variable. + + - *``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. + + - *``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. + + 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. 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. + + SRCREV_FORMAT + Helps construct valid ```SRCREV`` <#var-bb-SRCREV>`__ values when + multiple source controlled URLs are used in + ```SRC_URI`` <#var-bb-SRC_URI>`__. + + The system needs help constructing these values under these + circumstances. Each component in the ``SRC_URI`` is assigned a name + and these are referenced in the ``SRCREV_FORMAT`` variable. Consider + an example with URLs named "machine" and "meta". In this case, + ``SRCREV_FORMAT`` could look like "machine_meta" and those names + would have the SCM versions substituted into each position. Only one + ``AUTOINC`` placeholder is added and if needed. And, this placeholder + is placed at the start of the returned string. + + 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`` <#var-bb-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. -SVNDIR - The directory in which files checked out of a Subversion system are - stored. + SVNDIR + The directory in which files checked out of a Subversion system are + stored. -T - Points to a directory were BitBake places temporary files, which - consist mostly of task logs and scripts, when building a particular - recipe. + 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. + TOPDIR + Points to the build directory. BitBake automatically sets this + variable. |