mirrors/poky
1
0
Fork 0
mirror of https://git.yoctoproject.org/poky synced 2026-05-30 12:29:55 +00:00
Code Issues Projects Releases Wiki Activity

bitbake: doc: bitbake-user-manual: replace `FOO by :term:FOO` where possible

Browse Source 
If a variable has a glossary entry and some rST files write about those
variables, it's better to point to the glossary entry instead of just
highlighting it by surrounding it with two tick quotes.

The script that is used to do the replacement of ``FOO`` by :term:`FOO`
is the following Python code:

import re
from pathlib import Path
from runpy import run_module
import contextlib
import io
import sys

re_term = re.compile(r'variables.html#term-([a-zA-Z_0-9]*)')
terms = []
new_terms = set()

with contextlib.redirect_stdout(io.StringIO()) as f:
    run_module('sphinx.ext.intersphinx', run_name='__main__')

objects = f.getvalue()

match = re_term.search(objects)
while match:
    if match.group(1):
        terms.append(match.group(1))
    match = re_term.search(objects, match.end())

for rst in Path('.').rglob('*.rst'):
    with open(rst, 'r') as f:
        content = "".join(f.readlines())
    for term in terms:
        content = re.sub(r'``({})``(?!.*\s+[~=-]{{{:d},}})'.format(term, len(term)), r':term:`\1`', content)

    with open(rst, 'w') as f:
        f.write(content)

This script takes one argument as input: an objects.inv which can be
gotten from doc/_build/html/objetcs.inv after running `make html`.

Note that this excludes from replacement terms that appear in section
titles as it requires refs to be changed too. This can be automated too
if need be but right now it looks a bit confusing to have an anchor link
(for sections) also have a term/reference link in it. I am not sure this
is desired today.

(Bitbake rev: aba88f40c47133ed9bc999e0298aca3bc8490912)

Signed-off-by: Quentin Schulz <quentin.schulz@theobroma-systems.com>
Signed-off-by: Quentin Schulz <foss@0leil.net>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is contained in:
Quentin Schulz
2021-07-26 17:33:57 +02:00
committed by Richard Purdie
parent 3b6742685b
commit 7ade8346b3
6 changed files with 151 additions and 151 deletions
Download Patch File Download Diff File Expand all files Collapse all files
bitbake/doc/bitbake-user-manual/bitbake-user-manual-execution.rst
+27 -27
View File
@@ -40,7 +40,7 @@ the BitBake command and its options, see ":ref:`The BitBake Command
the number of processors, which takes into account hyper-threading. the number of processors, which takes into account hyper-threading.
Thus, a quad-core build host with hyper-threading most likely shows Thus, a quad-core build host with hyper-threading most likely shows
eight processors, which is the value you would then assign to eight processors, which is the value you would then assign to
``BB_NUMBER_THREADS``. :term:`BB_NUMBER_THREADS`.
A possibly simpler solution is that some Linux distributions (e.g. A possibly simpler solution is that some Linux distributions (e.g.
Debian and Ubuntu) provide the ``ncpus`` command. Debian and Ubuntu) provide the ``ncpus`` command.
@@ -65,13 +65,13 @@ data itself is of various types:
The ``layer.conf`` files are used to construct key variables such as The ``layer.conf`` files are used to construct key variables such as
:term:`BBPATH` and :term:`BBFILES`. :term:`BBPATH` and :term:`BBFILES`.
``BBPATH`` is used to search for configuration and class files under the :term:`BBPATH` is used to search for configuration and class files under the
``conf`` and ``classes`` directories, respectively. ``BBFILES`` is used ``conf`` and ``classes`` directories, respectively. :term:`BBFILES` is used
to locate both recipe and recipe append files (``.bb`` and to locate both recipe and recipe append files (``.bb`` and
``.bbappend``). If there is no ``bblayers.conf`` file, it is assumed the ``.bbappend``). If there is no ``bblayers.conf`` file, it is assumed the
user has set the ``BBPATH`` and ``BBFILES`` directly in the environment. user has set the :term:`BBPATH` and :term:`BBFILES` directly in the environment.
Next, the ``bitbake.conf`` file is located using the ``BBPATH`` variable Next, the ``bitbake.conf`` file is located using the :term:`BBPATH` variable
that was just constructed. The ``bitbake.conf`` file may also include that was just constructed. The ``bitbake.conf`` file may also include
other configuration files using the ``include`` or ``require`` other configuration files using the ``include`` or ``require``
directives. directives.
@@ -104,7 +104,7 @@ BitBake first searches the current working directory for an optional
contain a :term:`BBLAYERS` variable that is a contain a :term:`BBLAYERS` variable that is a
space-delimited list of 'layer' directories. Recall that if BitBake space-delimited list of 'layer' directories. Recall that if BitBake
cannot find a ``bblayers.conf`` file, then it is assumed the user has cannot find a ``bblayers.conf`` file, then it is assumed the user has
set the ``BBPATH`` and ``BBFILES`` variables directly in the set the :term:`BBPATH` and :term:`BBFILES` variables directly in the
environment. environment.
For each directory (layer) in this list, a ``conf/layer.conf`` file is For each directory (layer) in this list, a ``conf/layer.conf`` file is
@@ -114,7 +114,7 @@ files automatically set up :term:`BBPATH` and other
variables correctly for a given build directory. variables correctly for a given build directory.
BitBake then expects to find the ``conf/bitbake.conf`` file somewhere in BitBake then expects to find the ``conf/bitbake.conf`` file somewhere in
the user-specified ``BBPATH``. That configuration file generally has the user-specified :term:`BBPATH`. That configuration file generally has
include directives to pull in any other metadata such as files specific include directives to pull in any other metadata such as files specific
to the architecture, the machine, the local environment, and so forth. to the architecture, the machine, the local environment, and so forth.
@@ -135,7 +135,7 @@ The ``base.bbclass`` file is always included. Other classes that are
specified in the configuration using the specified in the configuration using the
:term:`INHERIT` variable are also included. BitBake :term:`INHERIT` variable are also included. BitBake
searches for class files in a ``classes`` subdirectory under the paths searches for class files in a ``classes`` subdirectory under the paths
in ``BBPATH`` in the same way as configuration files. in :term:`BBPATH` in the same way as configuration files.
A good way to get an idea of the configuration files and the class files A good way to get an idea of the configuration files and the class files
used in your execution environment is to run the following BitBake used in your execution environment is to run the following BitBake
@@ -184,13 +184,13 @@ Locating and Parsing Recipes
During the configuration phase, BitBake will have set During the configuration phase, BitBake will have set
:term:`BBFILES`. BitBake now uses it to construct a :term:`BBFILES`. BitBake now uses it to construct a
list of recipes to parse, along with any append files (``.bbappend``) to list of recipes to parse, along with any append files (``.bbappend``) to
apply. ``BBFILES`` is a space-separated list of available files and apply. :term:`BBFILES` is a space-separated list of available files and
supports wildcards. An example would be:: supports wildcards. An example would be::
BBFILES = "/path/to/bbfiles/*.bb /path/to/appends/*.bbappend" BBFILES = "/path/to/bbfiles/*.bb /path/to/appends/*.bbappend"
BitBake parses each BitBake parses each
recipe and append file located with ``BBFILES`` and stores the values of recipe and append file located with :term:`BBFILES` and stores the values of
various variables into the datastore. various variables into the datastore.
.. note:: .. note::
@@ -201,7 +201,7 @@ For each file, a fresh copy of the base configuration is made, then the
recipe is parsed line by line. Any inherit statements cause BitBake to recipe is parsed line by line. Any inherit statements cause BitBake to
find and then parse class files (``.bbclass``) using find and then parse class files (``.bbclass``) using
:term:`BBPATH` as the search path. Finally, BitBake :term:`BBPATH` as the search path. Finally, BitBake
parses in order any append files found in ``BBFILES``. parses in order any append files found in :term:`BBFILES`.
One common convention is to use the recipe filename to define pieces of One common convention is to use the recipe filename to define pieces of
metadata. For example, in ``bitbake.conf`` the recipe name and version metadata. For example, in ``bitbake.conf`` the recipe name and version
@@ -212,7 +212,7 @@ are used to set the variables :term:`PN` and
PV = "${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE', False),d)[1] or '1.0'}" PV = "${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE', False),d)[1] or '1.0'}"
In this example, a recipe called "something_1.2.3.bb" would set In this example, a recipe called "something_1.2.3.bb" would set
``PN`` to "something" and ``PV`` to "1.2.3". :term:`PN` to "something" and :term:`PV` to "1.2.3".
By the time parsing is complete for a recipe, BitBake has a list of By the time parsing is complete for a recipe, BitBake has a list of
tasks that the recipe defines and a set of data consisting of keys and tasks that the recipe defines and a set of data consisting of keys and
@@ -260,21 +260,21 @@ Providers
Assuming BitBake has been instructed to execute a target and that all Assuming BitBake has been instructed to execute a target and that all
the recipe files have been parsed, BitBake starts to figure out how to the recipe files have been parsed, BitBake starts to figure out how to
build the target. BitBake looks through the ``PROVIDES`` list for each build the target. BitBake looks through the :term:`PROVIDES` list for each
of the recipes. A ``PROVIDES`` list is the list of names by which the of the recipes. A :term:`PROVIDES` list is the list of names by which the
recipe can be known. Each recipe's ``PROVIDES`` list is created recipe can be known. Each recipe's :term:`PROVIDES` list is created
implicitly through the recipe's :term:`PN` variable and implicitly through the recipe's :term:`PN` variable and
explicitly through the recipe's :term:`PROVIDES` explicitly through the recipe's :term:`PROVIDES`
variable, which is optional. variable, which is optional.
When a recipe uses ``PROVIDES``, that recipe's functionality can be When a recipe uses :term:`PROVIDES`, that recipe's functionality can be
found under an alternative name or names other than the implicit ``PN`` found under an alternative name or names other than the implicit :term:`PN`
name. As an example, suppose a recipe named ``keyboard_1.0.bb`` name. As an example, suppose a recipe named ``keyboard_1.0.bb``
contained the following:: contained the following::
PROVIDES += "fullkeyboard" PROVIDES += "fullkeyboard"
The ``PROVIDES`` The :term:`PROVIDES`
list for this recipe becomes "keyboard", which is implicit, and list for this recipe becomes "keyboard", which is implicit, and
"fullkeyboard", which is explicit. Consequently, the functionality found "fullkeyboard", which is explicit. Consequently, the functionality found
in ``keyboard_1.0.bb`` can be found under two different names. in ``keyboard_1.0.bb`` can be found under two different names.
@@ -284,12 +284,12 @@ in ``keyboard_1.0.bb`` can be found under two different names.
Preferences Preferences
=========== ===========
The ``PROVIDES`` list is only part of the solution for figuring out a The :term:`PROVIDES` list is only part of the solution for figuring out a
target's recipes. Because targets might have multiple providers, BitBake target's recipes. Because targets might have multiple providers, BitBake
needs to prioritize providers by determining provider preferences. needs to prioritize providers by determining provider preferences.
A common example in which a target has multiple providers is A common example in which a target has multiple providers is
"virtual/kernel", which is on the ``PROVIDES`` list for each kernel "virtual/kernel", which is on the :term:`PROVIDES` list for each kernel
recipe. Each machine often selects the best kernel provider by using a recipe. Each machine often selects the best kernel provider by using a
line similar to the following in the machine configuration file:: line similar to the following in the machine configuration file::
@@ -309,10 +309,10 @@ specify a particular version. You can influence the order by using the
:term:`DEFAULT_PREFERENCE` variable. :term:`DEFAULT_PREFERENCE` variable.
By default, files have a preference of "0". Setting By default, files have a preference of "0". Setting
``DEFAULT_PREFERENCE`` to "-1" makes the recipe unlikely to be used :term:`DEFAULT_PREFERENCE` to "-1" makes the recipe unlikely to be used
unless it is explicitly referenced. Setting ``DEFAULT_PREFERENCE`` to unless it is explicitly referenced. Setting :term:`DEFAULT_PREFERENCE` to
"1" makes it likely the recipe is used. ``PREFERRED_VERSION`` overrides "1" makes it likely the recipe is used. :term:`PREFERRED_VERSION` overrides
any ``DEFAULT_PREFERENCE`` setting. ``DEFAULT_PREFERENCE`` is often used any :term:`DEFAULT_PREFERENCE` setting. :term:`DEFAULT_PREFERENCE` is often used
to mark newer and more experimental recipe versions until they have to mark newer and more experimental recipe versions until they have
undergone sufficient testing to be considered stable. undergone sufficient testing to be considered stable.
@@ -394,7 +394,7 @@ ready to run, those tasks have all their dependencies met, and the
thread threshold has not been exceeded. thread threshold has not been exceeded.
It is worth noting that you can greatly speed up the build time by It is worth noting that you can greatly speed up the build time by
properly setting the ``BB_NUMBER_THREADS`` variable. properly setting the :term:`BB_NUMBER_THREADS` variable.
As each task completes, a timestamp is written to the directory As each task completes, a timestamp is written to the directory
specified by the :term:`STAMP` variable. On subsequent specified by the :term:`STAMP` variable. On subsequent
@@ -561,7 +561,7 @@ behavior is unchanged from previous versions. ``OE-Core`` uses the
BB_SIGNATURE_HANDLER ?= "OEBasicHash" BB_SIGNATURE_HANDLER ?= "OEBasicHash"
The "OEBasicHash" ``BB_SIGNATURE_HANDLER`` is the same as the "OEBasic" The "OEBasicHash" :term:`BB_SIGNATURE_HANDLER` is the same as the "OEBasic"
version but adds the task hash to the stamp files. This results in any version but adds the task hash to the stamp files. This results in any
metadata change that changes the task hash, automatically causing the metadata change that changes the task hash, automatically causing the
task to be run again. This removes the need to bump task to be run again. This removes the need to bump
@@ -581,7 +581,7 @@ the build. This information includes:
- ``BBHASHDEPS_``\ *filename:taskname*: The task dependencies for - ``BBHASHDEPS_``\ *filename:taskname*: The task dependencies for
each task. each task.
- ``BB_TASKHASH``: The hash of the currently running task. - :term:`BB_TASKHASH`: The hash of the currently running task.
It is worth noting that BitBake's "-S" option lets you debug BitBake's It is worth noting that BitBake's "-S" option lets you debug BitBake's
processing of signatures. The options passed to -S allow different processing of signatures. The options passed to -S allow different
bitbake/doc/bitbake-user-manual/bitbake-user-manual-fetching.rst
+10 -10
View File
@@ -51,7 +51,7 @@ This code unpacks the downloaded files to the specified by ``WORKDIR``.
examine the OpenEmbedded class file ``base.bbclass`` examine the OpenEmbedded class file ``base.bbclass``
. .
The ``SRC_URI`` and ``WORKDIR`` variables are not hardcoded into the The :term:`SRC_URI` and ``WORKDIR`` variables are not hardcoded into the
fetcher, since those fetcher methods can be (and are) called with fetcher, since those fetcher methods can be (and are) called with
different variable names. In OpenEmbedded for example, the shared state different variable names. In OpenEmbedded for example, the shared state
(sstate) code uses the fetch module to fetch the sstate files. (sstate) code uses the fetch module to fetch the sstate files.
@@ -64,14 +64,14 @@ URLs by looking for source files in a specific search order:
:term:`PREMIRRORS` variable. :term:`PREMIRRORS` variable.
- *Source URI:* If pre-mirrors fail, BitBake uses the original URL (e.g - *Source URI:* If pre-mirrors fail, BitBake uses the original URL (e.g
from ``SRC_URI``). from :term:`SRC_URI`).
- *Mirror Sites:* If fetch failures occur, BitBake next uses mirror - *Mirror Sites:* If fetch failures occur, BitBake next uses mirror
locations as defined by the :term:`MIRRORS` variable. locations as defined by the :term:`MIRRORS` variable.
For each URL passed to the fetcher, the fetcher calls the submodule that For each URL passed to the fetcher, the fetcher calls the submodule that
handles that particular URL type. This behavior can be the source of handles that particular URL type. This behavior can be the source of
some confusion when you are providing URLs for the ``SRC_URI`` variable. some confusion when you are providing URLs for the :term:`SRC_URI` variable.
Consider the following two URLs:: Consider the following two URLs::
http://git.yoctoproject.org/git/poky;protocol=git http://git.yoctoproject.org/git/poky;protocol=git
@@ -110,14 +110,14 @@ which is specified by the :term:`DL_DIR` variable.
File integrity is of key importance for reproducing builds. For File integrity is of key importance for reproducing builds. For
non-local archive downloads, the fetcher code can verify SHA-256 and MD5 non-local archive downloads, the fetcher code can verify SHA-256 and MD5
checksums to ensure the archives have been downloaded correctly. You can checksums to ensure the archives have been downloaded correctly. You can
specify these checksums by using the ``SRC_URI`` variable with the specify these checksums by using the :term:`SRC_URI` variable with the
appropriate varflags as follows:: appropriate varflags as follows::
SRC_URI[md5sum] = "value" SRC_URI[md5sum] = "value"
SRC_URI[sha256sum] = "value" SRC_URI[sha256sum] = "value"
You can also specify the checksums as You can also specify the checksums as
parameters on the ``SRC_URI`` as shown below:: parameters on the :term:`SRC_URI` as shown below::
SRC_URI = "http://example.com/foobar.tar.bz2;md5sum=4a8e0f237e961fd7785d19d07fdb994d" SRC_URI = "http://example.com/foobar.tar.bz2;md5sum=4a8e0f237e961fd7785d19d07fdb994d"
@@ -129,7 +129,7 @@ shows how you name the URIs::
SRC_URI[foo.md5sum] = 4a8e0f237e961fd7785d19d07fdb994d SRC_URI[foo.md5sum] = 4a8e0f237e961fd7785d19d07fdb994d
After a file has been downloaded and After a file has been downloaded and
has had its checksum checked, a ".done" stamp is placed in ``DL_DIR``. has had its checksum checked, a ".done" stamp is placed in :term:`DL_DIR`.
BitBake uses this stamp during subsequent builds to avoid downloading or BitBake uses this stamp during subsequent builds to avoid downloading or
comparing a checksum for the file again. comparing a checksum for the file again.
@@ -438,7 +438,7 @@ Here are some example URLs::
.. note:: .. note::
Specifying passwords directly in ``git://`` urls is not supported. Specifying passwords directly in ``git://`` urls is not supported.
There are several reasons: ``SRC_URI`` is often written out to logs and There are several reasons: :term:`SRC_URI` is often written out to logs and
other places, and that could easily leak passwords; it is also all too other places, and that could easily leak passwords; it is also all too
easy to share metadata without removing passwords. SSH keys, ``~/.netrc`` easy to share metadata without removing passwords. SSH keys, ``~/.netrc``
and ``~/.ssh/config`` files can be used as alternatives. and ``~/.ssh/config`` files can be used as alternatives.
@@ -487,7 +487,7 @@ To use this fetcher, make sure your recipe has proper
The fetcher uses the ``rcleartool`` or The fetcher uses the ``rcleartool`` or
``cleartool`` remote client, depending on which one is available. ``cleartool`` remote client, depending on which one is available.
Following are options for the ``SRC_URI`` statement: Following are options for the :term:`SRC_URI` statement:
- *vob*: The name, which must include the prepending "/" character, - *vob*: The name, which must include the prepending "/" character,
of the ClearCase VOB. This option is required. of the ClearCase VOB. This option is required.
@@ -549,7 +549,7 @@ password if you do not wish to keep those values in a recipe itself. If
you choose not to use ``P4CONFIG``, or to explicitly set variables that you choose not to use ``P4CONFIG``, or to explicitly set variables that
``P4CONFIG`` can contain, you can specify the ``P4PORT`` value, which is ``P4CONFIG`` can contain, you can specify the ``P4PORT`` value, which is
the server's URL and port number, and you can specify a username and the server's URL and port number, and you can specify a username and
password directly in your recipe within ``SRC_URI``. password directly in your recipe within :term:`SRC_URI`.
Here is an example that relies on ``P4CONFIG`` to specify the server URL Here is an example that relies on ``P4CONFIG`` to specify the server URL
and port, username, and password, and fetches the Head Revision:: and port, username, and password, and fetches the Head Revision::
@@ -680,4 +680,4 @@ submodules. However, you might find the code helpful and readable.
Auto Revisions Auto Revisions
============== ==============
We need to document ``AUTOREV`` and ``SRCREV_FORMAT`` here. We need to document ``AUTOREV`` and :term:`SRCREV_FORMAT` here.
bitbake/doc/bitbake-user-manual/bitbake-user-manual-hello.rst
+7 -7
View File
@@ -145,23 +145,23 @@ Following is the complete "Hello World" example.
The majority of this output is specific to environment variables that The majority of this output is specific to environment variables that
are not directly relevant to BitBake. However, the very first are not directly relevant to BitBake. However, the very first
message regarding the ``BBPATH`` variable and the message regarding the :term:`BBPATH` variable and the
``conf/bblayers.conf`` file is relevant. ``conf/bblayers.conf`` file is relevant.
When you run BitBake, it begins looking for metadata files. The When you run BitBake, it begins looking for metadata files. The
:term:`BBPATH` variable is what tells BitBake where :term:`BBPATH` variable is what tells BitBake where
to look for those files. ``BBPATH`` is not set and you need to set to look for those files. :term:`BBPATH` is not set and you need to set
it. Without ``BBPATH``, BitBake cannot find any configuration files it. Without :term:`BBPATH`, BitBake cannot find any configuration files
(``.conf``) or recipe files (``.bb``) at all. BitBake also cannot (``.conf``) or recipe files (``.bb``) at all. BitBake also cannot
find the ``bitbake.conf`` file. find the ``bitbake.conf`` file.
#. **Setting BBPATH:** For this example, you can set ``BBPATH`` in #. **Setting BBPATH:** For this example, you can set :term:`BBPATH` in
the same manner that you set ``PATH`` earlier in the appendix. You the same manner that you set ``PATH`` earlier in the appendix. You
should realize, though, that it is much more flexible to set the should realize, though, that it is much more flexible to set the
``BBPATH`` variable up in a configuration file for each project. :term:`BBPATH` variable up in a configuration file for each project.
From your shell, enter the following commands to set and export the From your shell, enter the following commands to set and export the
``BBPATH`` variable:: :term:`BBPATH` variable::
$ BBPATH="projectdirectory" $ BBPATH="projectdirectory"
$ export BBPATH $ export BBPATH
@@ -175,7 +175,7 @@ Following is the complete "Hello World" example.
("~") character as BitBake does not expand that character as the ("~") character as BitBake does not expand that character as the
shell would. shell would.
#. **Run BitBake:** Now that you have ``BBPATH`` defined, run the #. **Run BitBake:** Now that you have :term:`BBPATH` defined, run the
``bitbake`` command again:: ``bitbake`` command again::
$ bitbake $ bitbake
bitbake/doc/bitbake-user-manual/bitbake-user-manual-intro.rst
+2 -2
View File
@@ -537,7 +537,7 @@ current working directory:
To stop depending on common depends, use the "-I" depend option and To stop depending on common depends, use the "-I" depend option and
BitBake omits them from the graph. Leaving this information out can BitBake omits them from the graph. Leaving this information out can
produce more readable graphs. This way, you can remove from the graph produce more readable graphs. This way, you can remove from the graph
``DEPENDS`` from inherited classes such as ``base.bbclass``. :term:`DEPENDS` from inherited classes such as ``base.bbclass``.
Here are two examples that create dependency graphs. The second example Here are two examples that create dependency graphs. The second example
omits depends common in OpenEmbedded from the graph:: omits depends common in OpenEmbedded from the graph::
@@ -564,7 +564,7 @@ for two separate targets:
.. image:: figures/bb_multiconfig_files.png .. image:: figures/bb_multiconfig_files.png
:align: center :align: center
The reason for this required file hierarchy is because the ``BBPATH`` The reason for this required file hierarchy is because the :term:`BBPATH`
variable is not constructed until the layers are parsed. Consequently, variable is not constructed until the layers are parsed. Consequently,
using the configuration file as a pre-configuration file is not possible using the configuration file as a pre-configuration file is not possible
unless it is located in the current working directory. unless it is located in the current working directory.
bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
+31 -31
View File
@@ -225,7 +225,7 @@ immediately, rather than when the variable is actually used::
C := "${C}append" C := "${C}append"
In this example, ``A`` contains "test 123", even though the final value In this example, ``A`` contains "test 123", even though the final value
of ``T`` is "456". The variable ``B`` will end up containing "456 of :term:`T` is "456". The variable :term:`B` will end up containing "456
cvalappend". This is because references to undefined variables are cvalappend". This is because references to undefined variables are
preserved as is during (immediate)expansion. This is in contrast to GNU preserved as is during (immediate)expansion. This is in contrast to GNU
Make, where undefined variables expand to nothing. The variable ``C`` Make, where undefined variables expand to nothing. The variable ``C``
@@ -248,7 +248,7 @@ examples::
C = "cval" C = "cval"
C =+ "test" C =+ "test"
The variable ``B`` contains "bval additionaldata" and ``C`` contains "test The variable :term:`B` contains "bval additionaldata" and ``C`` contains "test
cval". cval".
.. _appending-and-prepending-without-spaces: .. _appending-and-prepending-without-spaces:
@@ -267,7 +267,7 @@ examples::
C = "cval" C = "cval"
C =. "test" C =. "test"
The variable ``B`` contains "bvaladditionaldata" and ``C`` contains The variable :term:`B` contains "bvaladditionaldata" and ``C`` contains
"testcval". "testcval".
Appending and Prepending (Override Style Syntax) Appending and Prepending (Override Style Syntax)
@@ -287,7 +287,7 @@ rather than being immediately applied. Here are some examples::
D = "dval" D = "dval"
D_append = "additional data" D_append = "additional data"
The variable ``B`` The variable :term:`B`
becomes "bval additional data" and ``C`` becomes "additional data cval". becomes "bval additional data" and ``C`` becomes "additional data cval".
The variable ``D`` becomes "dvaladditional data". The variable ``D`` becomes "dvaladditional data".
@@ -496,14 +496,14 @@ Conditional Syntax (Overrides)
BitBake uses :term:`OVERRIDES` to control what BitBake uses :term:`OVERRIDES` to control what
variables are overridden after BitBake parses recipes and configuration variables are overridden after BitBake parses recipes and configuration
files. This section describes how you can use ``OVERRIDES`` as files. This section describes how you can use :term:`OVERRIDES` as
conditional metadata, talks about key expansion in relationship to conditional metadata, talks about key expansion in relationship to
``OVERRIDES``, and provides some examples to help with understanding. :term:`OVERRIDES`, and provides some examples to help with understanding.
Conditional Metadata Conditional Metadata
-------------------- --------------------
You can use ``OVERRIDES`` to conditionally select a specific version of You can use :term:`OVERRIDES` to conditionally select a specific version of
a variable and to conditionally append or prepend the value of a a variable and to conditionally append or prepend the value of a
variable. variable.
@@ -513,10 +513,10 @@ variable.
underscores are not permitted in override names as they are used to underscores are not permitted in override names as they are used to
separate overrides from each other and from the variable name. separate overrides from each other and from the variable name.
- *Selecting a Variable:* The ``OVERRIDES`` variable is a - *Selecting a Variable:* The :term:`OVERRIDES` variable is a
colon-character-separated list that contains items for which you want colon-character-separated list that contains items for which you want
to satisfy conditions. Thus, if you have a variable that is to satisfy conditions. Thus, if you have a variable that is
conditional on "arm", and "arm" is in ``OVERRIDES``, then the conditional on "arm", and "arm" is in :term:`OVERRIDES`, then the
"arm"-specific version of the variable is used rather than the "arm"-specific version of the variable is used rather than the
non-conditional version. Here is an example:: non-conditional version. Here is an example::
@@ -525,7 +525,7 @@ variable.
TEST_os = "osspecific" TEST_os = "osspecific"
TEST_nooverride = "othercondvalue" TEST_nooverride = "othercondvalue"
In this example, the ``OVERRIDES`` In this example, the :term:`OVERRIDES`
variable lists three overrides: "architecture", "os", and "machine". variable lists three overrides: "architecture", "os", and "machine".
The variable ``TEST`` by itself has a default value of "default". You The variable ``TEST`` by itself has a default value of "default". You
select the os-specific version of the ``TEST`` variable by appending select the os-specific version of the ``TEST`` variable by appending
@@ -547,13 +547,13 @@ variable.
- *Appending and Prepending:* BitBake also supports append and prepend - *Appending and Prepending:* BitBake also supports append and prepend
operations to variable values based on whether a specific item is operations to variable values based on whether a specific item is
listed in ``OVERRIDES``. Here is an example:: listed in :term:`OVERRIDES`. Here is an example::
DEPENDS = "glibc ncurses" DEPENDS = "glibc ncurses"
OVERRIDES = "machine:local" OVERRIDES = "machine:local"
DEPENDS_append_machine = "libmad" DEPENDS_append_machine = "libmad"
In this example, ``DEPENDS`` becomes "glibc ncurses libmad". In this example, :term:`DEPENDS` becomes "glibc ncurses libmad".
Again, using an OpenEmbedded metadata-based kernel recipe file as an Again, using an OpenEmbedded metadata-based kernel recipe file as an
example, the following lines will conditionally append to the example, the following lines will conditionally append to the
@@ -627,7 +627,7 @@ not been applied yet, ``A_foo`` is set to "X" due to the append and
``A`` simply equals "Z". ``A`` simply equals "Z".
Applying overrides, however, changes things. Since "foo" is listed in Applying overrides, however, changes things. Since "foo" is listed in
``OVERRIDES``, the conditional variable ``A`` is replaced with the "foo" :term:`OVERRIDES`, the conditional variable ``A`` is replaced with the "foo"
version, which is equal to "X". So effectively, ``A_foo`` replaces version, which is equal to "X". So effectively, ``A_foo`` replaces
``A``. ``A``.
@@ -686,7 +686,7 @@ share the task.
This section presents the mechanisms BitBake provides to allow you to This section presents the mechanisms BitBake provides to allow you to
share functionality between recipes. Specifically, the mechanisms share functionality between recipes. Specifically, the mechanisms
include ``include``, ``inherit``, ``INHERIT``, and ``require`` include ``include``, ``inherit``, :term:`INHERIT`, and ``require``
directives. directives.
Locating Include and Class Files Locating Include and Class Files
@@ -702,7 +702,7 @@ current directory for ``include`` and ``require`` directives.
In order for include and class files to be found by BitBake, they need In order for include and class files to be found by BitBake, they need
to be located in a "classes" subdirectory that can be found in to be located in a "classes" subdirectory that can be found in
``BBPATH``. :term:`BBPATH`.
``inherit`` Directive ``inherit`` Directive
--------------------- ---------------------
@@ -725,7 +725,7 @@ functionality for using Autotools that could be shared across recipes::
inherit autotools inherit autotools
In this case, BitBake would search for the directory In this case, BitBake would search for the directory
``classes/autotools.bbclass`` in ``BBPATH``. ``classes/autotools.bbclass`` in :term:`BBPATH`.
.. note:: .. note::
@@ -780,7 +780,7 @@ BitBake understands the ``include`` directive. This directive causes
BitBake to parse whatever file you specify, and to insert that file at BitBake to parse whatever file you specify, and to insert that file at
that location. The directive is much like its equivalent in Make except that location. The directive is much like its equivalent in Make except
that if the path specified on the include line is a relative path, that if the path specified on the include line is a relative path,
BitBake locates the first file it can find within ``BBPATH``. BitBake locates the first file it can find within :term:`BBPATH`.
The include directive is a more generic method of including The include directive is a more generic method of including
functionality as compared to the :ref:`inherit <bitbake-user-manual/bitbake-user-manual-metadata:\`\`inherit\`\` directive>` functionality as compared to the :ref:`inherit <bitbake-user-manual/bitbake-user-manual-metadata:\`\`inherit\`\` directive>`
@@ -822,7 +822,7 @@ does not suit a ``.bbclass`` file.
Similar to how BitBake handles :ref:`include <bitbake-user-manual/bitbake-user-manual-metadata:\`\`include\`\` directive>`, if Similar to how BitBake handles :ref:`include <bitbake-user-manual/bitbake-user-manual-metadata:\`\`include\`\` directive>`, if
the path specified on the require line is a relative path, BitBake the path specified on the require line is a relative path, BitBake
locates the first file it can find within ``BBPATH``. locates the first file it can find within :term:`BBPATH`.
As an example, suppose you have two versions of a recipe (e.g. As an example, suppose you have two versions of a recipe (e.g.
``foo_1.2.2.bb`` and ``foo_2.0.0.bb``) where each version contains some ``foo_1.2.2.bb`` and ``foo_2.0.0.bb``) where each version contains some
@@ -851,7 +851,7 @@ As an example, suppose you needed to inherit a class file called
This configuration directive causes the named class to be inherited at This configuration directive causes the named class to be inherited at
the point of the directive during parsing. As with the ``inherit`` the point of the directive during parsing. As with the ``inherit``
directive, the ``.bbclass`` file must be located in a "classes" directive, the ``.bbclass`` file must be located in a "classes"
subdirectory in one of the directories specified in ``BBPATH``. subdirectory in one of the directories specified in :term:`BBPATH`.
.. note:: .. note::
@@ -1015,7 +1015,7 @@ is an example::
SOMECONDITION = "1" SOMECONDITION = "1"
DEPENDS = "${@get_depends(d)}" DEPENDS = "${@get_depends(d)}"
This would result in ``DEPENDS`` containing ``dependencywithcond``. This would result in :term:`DEPENDS` containing ``dependencywithcond``.
Here are some things to know about Python functions: Here are some things to know about Python functions:
@@ -1382,7 +1382,7 @@ Sometimes, it is useful to be able to obtain information from the
original execution environment. BitBake saves a copy of the original original execution environment. BitBake saves a copy of the original
environment into a special variable named :term:`BB_ORIGENV`. environment into a special variable named :term:`BB_ORIGENV`.
The ``BB_ORIGENV`` variable returns a datastore object that can be The :term:`BB_ORIGENV` variable returns a datastore object that can be
queried using the standard datastore operators such as queried using the standard datastore operators such as
``getVar(, False)``. The datastore object is useful, for example, to ``getVar(, False)``. The datastore object is useful, for example, to
find the original ``DISPLAY`` variable. Here is an example:: find the original ``DISPLAY`` variable. Here is an example::
@@ -1467,7 +1467,7 @@ functionality of the task:
can result in unpredictable behavior. can result in unpredictable behavior.
- Setting the varflag to a value greater than the value used in - Setting the varflag to a value greater than the value used in
the ``BB_NUMBER_THREADS`` variable causes ``number_threads`` to the :term:`BB_NUMBER_THREADS` variable causes ``number_threads`` to
have no effect. have no effect.
- ``[postfuncs]``: List of functions to call after the completion of - ``[postfuncs]``: List of functions to call after the completion of
@@ -1537,7 +1537,7 @@ intent is to make it easy to do things like email notification on build
failures. failures.
Following is an example event handler that prints the name of the event Following is an example event handler that prints the name of the event
and the content of the ``FILE`` variable:: and the content of the :term:`FILE` variable::
addhandler myclass_eventhandler addhandler myclass_eventhandler
python myclass_eventhandler() { python myclass_eventhandler() {
@@ -1576,7 +1576,7 @@ might have an interest in viewing:
- ``bb.event.ConfigParsed()``: Fired when the base configuration; which - ``bb.event.ConfigParsed()``: Fired when the base configuration; which
consists of ``bitbake.conf``, ``base.bbclass`` and any global consists of ``bitbake.conf``, ``base.bbclass`` and any global
``INHERIT`` statements; has been parsed. You can see multiple such :term:`INHERIT` statements; has been parsed. You can see multiple such
events when each of the workers parse the base configuration or if events when each of the workers parse the base configuration or if
the server changes configuration and reparses. Any given datastore the server changes configuration and reparses. Any given datastore
only has one such event executed against it, however. If only has one such event executed against it, however. If
@@ -1733,13 +1733,13 @@ Build Dependencies
BitBake uses the :term:`DEPENDS` variable to manage BitBake uses the :term:`DEPENDS` variable to manage
build time dependencies. The ``[deptask]`` varflag for tasks signifies build time dependencies. The ``[deptask]`` varflag for tasks signifies
the task of each item listed in ``DEPENDS`` that must complete before the task of each item listed in :term:`DEPENDS` that must complete before
that task can be executed. Here is an example:: that task can be executed. Here is an example::
do_configure[deptask] = "do_populate_sysroot" do_configure[deptask] = "do_populate_sysroot"
In this example, the ``do_populate_sysroot`` task In this example, the ``do_populate_sysroot`` task
of each item in ``DEPENDS`` must complete before ``do_configure`` can of each item in :term:`DEPENDS` must complete before ``do_configure`` can
execute. execute.
Runtime Dependencies Runtime Dependencies
@@ -1748,8 +1748,8 @@ Runtime Dependencies
BitBake uses the :term:`PACKAGES`, :term:`RDEPENDS`, and :term:`RRECOMMENDS` BitBake uses the :term:`PACKAGES`, :term:`RDEPENDS`, and :term:`RRECOMMENDS`
variables to manage runtime dependencies. variables to manage runtime dependencies.
The ``PACKAGES`` variable lists runtime packages. Each of those packages The :term:`PACKAGES` variable lists runtime packages. Each of those packages
can have ``RDEPENDS`` and ``RRECOMMENDS`` runtime dependencies. The can have :term:`RDEPENDS` and :term:`RRECOMMENDS` runtime dependencies. The
``[rdeptask]`` flag for tasks is used to signify the task of each item ``[rdeptask]`` flag for tasks is used to signify the task of each item
runtime dependency which must have completed before that task can be runtime dependency which must have completed before that task can be
executed. :: executed. ::
@@ -1757,9 +1757,9 @@ executed. ::
do_package_qa[rdeptask] = "do_packagedata" do_package_qa[rdeptask] = "do_packagedata"
In the previous In the previous
example, the ``do_packagedata`` task of each item in ``RDEPENDS`` must example, the ``do_packagedata`` task of each item in :term:`RDEPENDS` must
have completed before ``do_package_qa`` can execute. have completed before ``do_package_qa`` can execute.
Although ``RDEPENDS`` contains entries from the Although :term:`RDEPENDS` contains entries from the
runtime dependency namespace, BitBake knows how to map them back runtime dependency namespace, BitBake knows how to map them back
to the build-time dependency namespace, in which the tasks are defined. to the build-time dependency namespace, in which the tasks are defined.
@@ -1802,7 +1802,7 @@ Inter-Task Dependencies
BitBake uses the ``[depends]`` flag in a more generic form to manage BitBake uses the ``[depends]`` flag in a more generic form to manage
inter-task dependencies. This more generic form allows for inter-task dependencies. This more generic form allows for
inter-dependency checks for specific tasks rather than checks for the inter-dependency checks for specific tasks rather than checks for the
data in ``DEPENDS``. Here is an example:: data in :term:`DEPENDS`. Here is an example::
do_patch[depends] = "quilt-native:do_populate_sysroot" do_patch[depends] = "quilt-native:do_populate_sysroot"
bitbake/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst
+74 -74
View File
@@ -31,7 +31,7 @@ overview of their function and contents.
attempt to build. Instead, BitBake assumes these recipes have already attempt to build. Instead, BitBake assumes these recipes have already
been built. been built.
In OpenEmbedded-Core, ``ASSUME_PROVIDED`` mostly specifies native In OpenEmbedded-Core, :term:`ASSUME_PROVIDED` mostly specifies native
tools that should not be built. An example is ``git-native``, which 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 when specified allows for the Git binary from the host to be used
rather than building ``git-native``. rather than building ``git-native``.
@@ -84,14 +84,14 @@ overview of their function and contents.
- Attempts to access networks not in the host list cause a failure. - Attempts to access networks not in the host list cause a failure.
Using ``BB_ALLOWED_NETWORKS`` in conjunction with Using :term:`BB_ALLOWED_NETWORKS` in conjunction with
:term:`PREMIRRORS` is very useful. Adding the :term:`PREMIRRORS` is very useful. Adding the
host you want to use to ``PREMIRRORS`` results in the source code host you want to use to :term:`PREMIRRORS` results in the source code
being fetched from an allowed location and avoids raising an error being fetched from an allowed location and avoids raising an error
when a host that is not allowed is in a when a host that is not allowed is in a
:term:`SRC_URI` statement. This is because the :term:`SRC_URI` statement. This is because the
fetcher does not attempt to use the host listed in ``SRC_URI`` after fetcher does not attempt to use the host listed in :term:`SRC_URI` after
a successful fetch from the ``PREMIRRORS`` occurs. a successful fetch from the :term:`PREMIRRORS` occurs.
:term:`BB_CONSOLELOG` :term:`BB_CONSOLELOG`
Specifies the path to a log file into which BitBake's user interface Specifies the path to a log file into which BitBake's user interface
@@ -178,7 +178,7 @@ overview of their function and contents.
issues a warning when the disk space in the ``${SSTATE_DIR}`` issues a warning when the disk space in the ``${SSTATE_DIR}``
directory drops below 1 Gbyte or the number of free inodes drops directory drops below 1 Gbyte or the number of free inodes drops
below 100 Kbytes. Subsequent warnings are issued during intervals as below 100 Kbytes. Subsequent warnings are issued during intervals as
defined by the ``BB_DISKMON_WARNINTERVAL`` variable. defined by the :term:`BB_DISKMON_WARNINTERVAL` variable.
The second example stops the build after all currently executing The second example stops the build after all currently executing
tasks complete when the minimum disk space in the ``${TMPDIR}`` tasks complete when the minimum disk space in the ``${TMPDIR}``
@@ -192,14 +192,14 @@ overview of their function and contents.
:term:`BB_DISKMON_WARNINTERVAL` :term:`BB_DISKMON_WARNINTERVAL`
Defines the disk space and free inode warning intervals. Defines the disk space and free inode warning intervals.
If you are going to use the ``BB_DISKMON_WARNINTERVAL`` variable, you If you are going to use the :term:`BB_DISKMON_WARNINTERVAL` variable, you
must also use the :term:`BB_DISKMON_DIRS` must also use the :term:`BB_DISKMON_DIRS`
variable and define its action as "WARN". During the build, variable and define its action as "WARN". During the build,
subsequent warnings are issued each time disk space or number of free subsequent warnings are issued each time disk space or number of free
inodes further reduces by the respective interval. inodes further reduces by the respective interval.
If you do not provide a ``BB_DISKMON_WARNINTERVAL`` variable and you If you do not provide a :term:`BB_DISKMON_WARNINTERVAL` variable and you
do use ``BB_DISKMON_DIRS`` with the "WARN" action, the disk do use :term:`BB_DISKMON_DIRS` with the "WARN" action, the disk
monitoring interval defaults to the following: monitoring interval defaults to the following:
BB_DISKMON_WARNINTERVAL = "50M,5K" BB_DISKMON_WARNINTERVAL = "50M,5K"
@@ -264,7 +264,7 @@ overview of their function and contents.
:term:`BB_FILENAME` :term:`BB_FILENAME`
Contains the filename of the recipe that owns the currently running Contains the filename of the recipe that owns the currently running
task. For example, if the ``do_fetch`` task that resides in the task. For example, if the ``do_fetch`` task that resides in the
``my-recipe.bb`` is executing, the ``BB_FILENAME`` variable contains ``my-recipe.bb`` is executing, the :term:`BB_FILENAME` variable contains
"/foo/path/my-recipe.bb". "/foo/path/my-recipe.bb".
:term:`BB_GENERATE_MIRROR_TARBALLS` :term:`BB_GENERATE_MIRROR_TARBALLS`
@@ -334,7 +334,7 @@ overview of their function and contents.
:term:`BB_LOGFMT` :term:`BB_LOGFMT`
Specifies the name of the log files saved into Specifies the name of the log files saved into
``${``\ :term:`T`\ ``}``. By default, the ``BB_LOGFMT`` ``${``\ :term:`T`\ ``}``. By default, the :term:`BB_LOGFMT`
variable is undefined and the log file names get created using the variable is undefined and the log file names get created using the
following form:: following form::
@@ -389,7 +389,7 @@ overview of their function and contents.
:term:`BB_RUNFMT` :term:`BB_RUNFMT`
Specifies the name of the executable script files (i.e. run files) Specifies the name of the executable script files (i.e. run files)
saved into ``${``\ :term:`T`\ ``}``. By default, the saved into ``${``\ :term:`T`\ ``}``. By default, the
``BB_RUNFMT`` variable is undefined and the run file names get :term:`BB_RUNFMT` variable is undefined and the run file names get
created using the following form:: created using the following form::
run.{task}.{pid} run.{task}.{pid}
@@ -455,7 +455,7 @@ overview of their function and contents.
:term:`BB_SRCREV_POLICY` :term:`BB_SRCREV_POLICY`
Defines the behavior of the fetcher when it interacts with source Defines the behavior of the fetcher when it interacts with source
control systems and dynamic source revisions. The control systems and dynamic source revisions. The
``BB_SRCREV_POLICY`` variable is useful when working without a :term:`BB_SRCREV_POLICY` variable is useful when working without a
network. network.
The variable can be set using one of two policies: The variable can be set using one of two policies:
@@ -499,7 +499,7 @@ overview of their function and contents.
Allows adjustment of a task's Input/Output priority. During Allows adjustment of a task's Input/Output priority. During
Autobuilder testing, random failures can occur for tasks due to I/O Autobuilder testing, random failures can occur for tasks due to I/O
starvation. These failures occur during various QEMU runtime starvation. These failures occur during various QEMU runtime
timeouts. You can use the ``BB_TASK_IONICE_LEVEL`` variable to adjust timeouts. You can use the :term:`BB_TASK_IONICE_LEVEL` variable to adjust
the I/O priority of these tasks. the I/O priority of these tasks.
.. note:: .. note::
@@ -573,13 +573,13 @@ overview of their function and contents.
.. note:: .. note::
Internally, the ``BBCLASSEXTEND`` mechanism generates recipe Internally, the :term:`BBCLASSEXTEND` mechanism generates recipe
variants by rewriting variable values and applying overrides such variants by rewriting variable values and applying overrides such
as ``_class-native``. For example, to generate a native version of as ``_class-native``. For example, to generate a native version of
a recipe, a :term:`DEPENDS` on "foo" is a recipe, a :term:`DEPENDS` on "foo" is
rewritten to a ``DEPENDS`` on "foo-native". rewritten to a :term:`DEPENDS` on "foo-native".
Even when using ``BBCLASSEXTEND``, the recipe is only parsed once. Even when using :term:`BBCLASSEXTEND`, the recipe is only parsed once.
Parsing once adds some limitations. For example, it is not Parsing once adds some limitations. For example, it is not
possible to include a different file depending on the variant, possible to include a different file depending on the variant,
since ``include`` statements are processed when the recipe is since ``include`` statements are processed when the recipe is
@@ -615,14 +615,14 @@ overview of their function and contents.
- effectively letting you control the precedence for the multiple - effectively letting you control the precedence for the multiple
layers. The precedence established through this variable stands layers. The precedence established through this variable stands
regardless of a recipe's version (:term:`PV` variable). regardless of a recipe's version (:term:`PV` variable).
For example, a layer that has a recipe with a higher ``PV`` value but For example, a layer that has a recipe with a higher :term:`PV` value but
for which the ``BBFILE_PRIORITY`` is set to have a lower precedence for which the :term:`BBFILE_PRIORITY` is set to have a lower precedence
still has a lower precedence. still has a lower precedence.
A larger value for the ``BBFILE_PRIORITY`` variable results in a A larger value for the :term:`BBFILE_PRIORITY` variable results in a
higher precedence. For example, the value 6 has a higher precedence higher precedence. For example, the value 6 has a higher precedence
than the value 5. If not specified, the ``BBFILE_PRIORITY`` variable than the value 5. If not specified, the :term:`BBFILE_PRIORITY` variable
is set based on layer dependencies (see the ``LAYERDEPENDS`` variable is set based on layer dependencies (see the :term:`LAYERDEPENDS` variable
for more information. The default priority, if unspecified for a for more information. The default priority, if unspecified for a
layer with no dependencies, is the lowest defined priority + 1 (or 1 layer with no dependencies, is the lowest defined priority + 1 (or 1
if no priorities are defined). if no priorities are defined).
@@ -645,7 +645,7 @@ overview of their function and contents.
Activates content depending on presence of identified layers. You Activates content depending on presence of identified layers. You
identify the layers by the collections that the layers define. identify the layers by the collections that the layers define.
Use the ``BBFILES_DYNAMIC`` variable to avoid ``.bbappend`` files whose Use the :term:`BBFILES_DYNAMIC` variable to avoid ``.bbappend`` files whose
corresponding ``.bb`` file is in a layer that attempts to modify other corresponding ``.bb`` file is in a layer that attempts to modify other
layers through ``.bbappend`` but does not want to introduce a hard layers through ``.bbappend`` but does not want to introduce a hard
dependency on those other layers. dependency on those other layers.
@@ -654,7 +654,7 @@ overview of their function and contents.
``.bb`` files in case a layer is not present. Use this avoid hard ``.bb`` files in case a layer is not present. Use this avoid hard
dependency on those other layers. dependency on those other layers.
Use the following form for ``BBFILES_DYNAMIC``:: Use the following form for :term:`BBFILES_DYNAMIC`::
collection_name:filename_pattern collection_name:filename_pattern
@@ -691,7 +691,7 @@ overview of their function and contents.
:term:`BBINCLUDELOGS_LINES` :term:`BBINCLUDELOGS_LINES`
If :term:`BBINCLUDELOGS` is set, specifies If :term:`BBINCLUDELOGS` is set, specifies
the maximum number of lines from the task log file to print when the maximum number of lines from the task log file to print when
reporting a failed task. If you do not set ``BBINCLUDELOGS_LINES``, reporting a failed task. If you do not set :term:`BBINCLUDELOGS_LINES`,
the entire log is printed. the entire log is printed.
:term:`BBLAYERS` :term:`BBLAYERS`
@@ -717,7 +717,7 @@ overview of their function and contents.
:term:`BBMASK` :term:`BBMASK`
Prevents BitBake from processing recipes and recipe append files. Prevents BitBake from processing recipes and recipe append files.
You can use the ``BBMASK`` variable to "hide" these ``.bb`` and You can use the :term:`BBMASK` variable to "hide" these ``.bb`` and
``.bbappend`` files. BitBake ignores any recipe or recipe append ``.bbappend`` files. BitBake ignores any recipe or recipe append
files that match any of the expressions. It is as if BitBake does not 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 see them at all. Consequently, matching files are not parsed or
@@ -754,7 +754,7 @@ overview of their function and contents.
Enables BitBake to perform multiple configuration builds and lists Enables BitBake to perform multiple configuration builds and lists
each separate configuration (multiconfig). You can use this variable each separate configuration (multiconfig). You can use this variable
to cause BitBake to build multiple targets where each target has a to cause BitBake to build multiple targets where each target has a
separate configuration. Define ``BBMULTICONFIG`` in your separate configuration. Define :term:`BBMULTICONFIG` in your
``conf/local.conf`` configuration file. ``conf/local.conf`` configuration file.
As an example, the following line specifies three multiconfigs, each As an example, the following line specifies three multiconfigs, each
@@ -766,7 +766,7 @@ overview of their function and contents.
build directory within a directory named ``conf/multiconfig`` (e.g. build directory within a directory named ``conf/multiconfig`` (e.g.
build_directory\ ``/conf/multiconfig/configA.conf``). build_directory\ ``/conf/multiconfig/configA.conf``).
For information on how to use ``BBMULTICONFIG`` in an environment For information on how to use :term:`BBMULTICONFIG` in an environment
that supports building targets with multiple configurations, see the that supports building targets with multiple configurations, see the
":ref:`bitbake-user-manual/bitbake-user-manual-intro:executing a multiple configuration build`" ":ref:`bitbake-user-manual/bitbake-user-manual-intro:executing a multiple configuration build`"
section. section.
@@ -777,7 +777,7 @@ overview of their function and contents.
variable. variable.
If you run BitBake from a directory outside of the build directory, 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. you must be sure to set :term:`BBPATH` to point to the build directory.
Set the variable as you would any environment variable and then run Set the variable as you would any environment variable and then run
BitBake:: BitBake::
@@ -824,7 +824,7 @@ overview of their function and contents.
The most common usage of this is variable is to set it to "-1" within 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 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 variable in this way causes the stable version of the recipe to build
by default in the absence of ``PREFERRED_VERSION`` being used to by default in the absence of :term:`PREFERRED_VERSION` being used to
build the development version. build the development version.
.. note:: .. note::
@@ -837,7 +837,7 @@ overview of their function and contents.
Lists a recipe's build-time dependencies (i.e. other recipe files). Lists a recipe's build-time dependencies (i.e. other recipe files).
Consider this simple example for two recipes named "a" and "b" that Consider this simple example for two recipes named "a" and "b" that
produce similarly named packages. In this example, the ``DEPENDS`` produce similarly named packages. In this example, the :term:`DEPENDS`
statement appears in the "a" recipe:: statement appears in the "a" recipe::
DEPENDS = "b" DEPENDS = "b"
@@ -855,7 +855,7 @@ overview of their function and contents.
:term:`DL_DIR` :term:`DL_DIR`
The central download directory used by the build process to store The central download directory used by the build process to store
downloads. By default, ``DL_DIR`` gets files suitable for mirroring for downloads. By default, :term:`DL_DIR` gets files suitable for mirroring for
everything except Git repositories. If you want tarballs of Git everything except Git repositories. If you want tarballs of Git
repositories, use the :term:`BB_GENERATE_MIRROR_TARBALLS` variable. repositories, use the :term:`BB_GENERATE_MIRROR_TARBALLS` variable.
@@ -870,14 +870,14 @@ overview of their function and contents.
.. note:: .. note::
Recipes added to ``EXCLUDE_FROM_WORLD`` may still be built during a world Recipes added to :term:`EXCLUDE_FROM_WORLD` may still be built during a world
build in order to satisfy dependencies of other recipes. Adding a build in order to satisfy dependencies of other recipes. Adding a
recipe to ``EXCLUDE_FROM_WORLD`` only ensures that the recipe is not recipe to :term:`EXCLUDE_FROM_WORLD` only ensures that the recipe is not
explicitly added to the list of build targets in a world build. explicitly added to the list of build targets in a world build.
:term:`FAKEROOT` :term:`FAKEROOT`
Contains the command to use when running a shell script in a fakeroot Contains the command to use when running a shell script in a fakeroot
environment. The ``FAKEROOT`` variable is obsolete and has been environment. The :term:`FAKEROOT` variable is obsolete and has been
replaced by the other ``FAKEROOT*`` variables. See these entries in replaced by the other ``FAKEROOT*`` variables. See these entries in
the glossary for more information. the glossary for more information.
@@ -940,9 +940,9 @@ overview of their function and contents.
Causes the named class or classes to be inherited globally. Anonymous Causes the named class or classes to be inherited globally. Anonymous
functions in the class or classes are not executed for the base functions in the class or classes are not executed for the base
configuration and in each individual recipe. The OpenEmbedded build configuration and in each individual recipe. The OpenEmbedded build
system ignores changes to ``INHERIT`` in individual recipes. system ignores changes to :term:`INHERIT` in individual recipes.
For more information on ``INHERIT``, see the For more information on :term:`INHERIT`, see the
":ref:`bitbake-user-manual/bitbake-user-manual-metadata:\`\`inherit\`\` configuration directive`" ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:\`\`inherit\`\` configuration directive`"
section. section.
@@ -990,7 +990,7 @@ overview of their function and contents.
the build system searches for source code, it first tries the local the build system searches for source code, it first tries the local
download directory. If that location fails, the build system tries download directory. If that location fails, the build system tries
locations defined by :term:`PREMIRRORS`, the locations defined by :term:`PREMIRRORS`, the
upstream source, and then locations specified by ``MIRRORS`` in that upstream source, and then locations specified by :term:`MIRRORS` in that
order. order.
:term:`MULTI_PROVIDER_WHITELIST` :term:`MULTI_PROVIDER_WHITELIST`
@@ -1007,12 +1007,12 @@ overview of their function and contents.
``virtual/kernel``, and so forth). ``virtual/kernel``, and so forth).
:term:`OVERRIDES` :term:`OVERRIDES`
BitBake uses ``OVERRIDES`` to control what variables are overridden BitBake uses :term:`OVERRIDES` to control what variables are overridden
after BitBake parses recipes and configuration files. after BitBake parses recipes and configuration files.
Following is a simple example that uses an overrides list based on Following is a simple example that uses an overrides list based on
machine architectures: OVERRIDES = "arm:x86:mips:powerpc" You can machine architectures: OVERRIDES = "arm:x86:mips:powerpc" You can
find information on how to use ``OVERRIDES`` in the find information on how to use :term:`OVERRIDES` in the
":ref:`bitbake-user-manual/bitbake-user-manual-metadata:conditional syntax ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:conditional syntax
(overrides)`" section. (overrides)`" section.
@@ -1026,11 +1026,11 @@ overview of their function and contents.
:term:`PACKAGES_DYNAMIC` :term:`PACKAGES_DYNAMIC`
A promise that your recipe satisfies runtime dependencies for A promise that your recipe satisfies runtime dependencies for
optional modules that are found in other recipes. optional modules that are found in other recipes.
``PACKAGES_DYNAMIC`` does not actually satisfy the dependencies, it :term:`PACKAGES_DYNAMIC` does not actually satisfy the dependencies, it
only states that they should be satisfied. For example, if a hard, only states that they should be satisfied. For example, if a hard,
runtime dependency (:term:`RDEPENDS`) of another runtime dependency (:term:`RDEPENDS`) of another
package is satisfied during the build through the package is satisfied during the build through the
``PACKAGES_DYNAMIC`` variable, but a package with the module name is :term:`PACKAGES_DYNAMIC` variable, but a package with the module name is
never actually produced, then the other package will be broken. never actually produced, then the other package will be broken.
:term:`PE` :term:`PE`
@@ -1069,8 +1069,8 @@ overview of their function and contents.
:term:`PREFERRED_PROVIDERS` :term:`PREFERRED_PROVIDERS`
Determines which recipe should be given preference for cases where Determines which recipe should be given preference for cases where
multiple recipes provide the same item. Functionally, multiple recipes provide the same item. Functionally,
``PREFERRED_PROVIDERS`` is identical to :term:`PREFERRED_PROVIDERS` is identical to
:term:`PREFERRED_PROVIDER`. However, the ``PREFERRED_PROVIDERS`` variable :term:`PREFERRED_PROVIDER`. However, the :term:`PREFERRED_PROVIDERS` variable
lets you define preferences for multiple situations using the following lets you define preferences for multiple situations using the following
form:: form::
@@ -1088,7 +1088,7 @@ overview of their function and contents.
select, and you should set :term:`PV` accordingly for select, and you should set :term:`PV` accordingly for
precedence. precedence.
The ``PREFERRED_VERSION`` variable supports limited wildcard use The :term:`PREFERRED_VERSION` variable supports limited wildcard use
through the "``%``" character. You can use the character to match any through the "``%``" character. You can use the character to match any
number of characters, which can be useful when specifying versions number of characters, which can be useful when specifying versions
that contain long revision numbers that potentially change. Here are that contain long revision numbers that potentially change. Here are
@@ -1111,7 +1111,7 @@ overview of their function and contents.
Specifies additional paths from which BitBake gets source code. When Specifies additional paths from which BitBake gets source code. When
the build system searches for source code, it first tries the local the build system searches for source code, it first tries the local
download directory. If that location fails, the build system tries download directory. If that location fails, the build system tries
locations defined by ``PREMIRRORS``, the upstream source, and then locations defined by :term:`PREMIRRORS`, the upstream source, and then
locations specified by :term:`MIRRORS` in that order. locations specified by :term:`MIRRORS` in that order.
Typically, you would add a specific server for the build system to Typically, you would add a specific server for the build system to
@@ -1131,25 +1131,25 @@ overview of their function and contents.
:term:`PROVIDES` :term:`PROVIDES`
A list of aliases by which a particular recipe can be known. By A list of aliases by which a particular recipe can be known. By
default, a recipe's own ``PN`` is implicitly already in its default, a recipe's own :term:`PN` is implicitly already in its
``PROVIDES`` list. If a recipe uses ``PROVIDES``, the additional :term:`PROVIDES` list. If a recipe uses :term:`PROVIDES`, the additional
aliases are synonyms for the recipe and can be useful satisfying aliases are synonyms for the recipe and can be useful satisfying
dependencies of other recipes during the build as specified by dependencies of other recipes during the build as specified by
``DEPENDS``. :term:`DEPENDS`.
Consider the following example ``PROVIDES`` statement from a recipe Consider the following example :term:`PROVIDES` statement from a recipe
file ``libav_0.8.11.bb``:: file ``libav_0.8.11.bb``::
PROVIDES += "libpostproc" PROVIDES += "libpostproc"
The ``PROVIDES`` statement results in the "libav" recipe also being known The :term:`PROVIDES` statement results in the "libav" recipe also being known
as "libpostproc". as "libpostproc".
In addition to providing recipes under alternate names, the In addition to providing recipes under alternate names, the
``PROVIDES`` mechanism is also used to implement virtual targets. A :term:`PROVIDES` mechanism is also used to implement virtual targets. A
virtual target is a name that corresponds to some particular virtual target is a name that corresponds to some particular
functionality (e.g. a Linux kernel). Recipes that provide the functionality (e.g. a Linux kernel). Recipes that provide the
functionality in question list the virtual target in ``PROVIDES``. functionality in question list the virtual target in :term:`PROVIDES`.
Recipes that depend on the functionality in question can include the Recipes that depend on the functionality in question can include the
virtual target in :term:`DEPENDS` to leave the virtual target in :term:`DEPENDS` to leave the
choice of provider open. choice of provider open.
@@ -1161,12 +1161,12 @@ overview of their function and contents.
:term:`PRSERV_HOST` :term:`PRSERV_HOST`
The network based :term:`PR` service host and port. The network based :term:`PR` service host and port.
Following is an example of how the ``PRSERV_HOST`` variable is set:: Following is an example of how the :term:`PRSERV_HOST` variable is set::
PRSERV_HOST = "localhost:0" PRSERV_HOST = "localhost:0"
You must set the variable if you want to automatically start a local PR 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. You can set :term:`PRSERV_HOST` to other values to use a remote PR
service. service.
:term:`PV` :term:`PV`
@@ -1178,22 +1178,22 @@ overview of their function and contents.
a package in this list cannot be found during the build, you will get a package in this list cannot be found during the build, you will get
a build error. a build error.
Because the ``RDEPENDS`` variable applies to packages being built, Because the :term:`RDEPENDS` variable applies to packages being built,
you should always use the variable in a form with an attached package you should always use the variable in a form with an attached package
name. For example, suppose you are building a development package name. For example, suppose you are building a development package
that depends on the ``perl`` package. In this case, you would use the that depends on the ``perl`` package. In this case, you would use the
following ``RDEPENDS`` statement:: following :term:`RDEPENDS` statement::
RDEPENDS_${PN}-dev += "perl" RDEPENDS_${PN}-dev += "perl"
In the example, the development package depends on the ``perl`` package. In the example, the development package depends on the ``perl`` package.
Thus, the ``RDEPENDS`` variable has the ``${PN}-dev`` package name as part Thus, the :term:`RDEPENDS` variable has the ``${PN}-dev`` package name as part
of the variable. of the variable.
BitBake supports specifying versioned dependencies. Although the BitBake supports specifying versioned dependencies. Although the
syntax varies depending on the packaging format, BitBake hides these syntax varies depending on the packaging format, BitBake hides these
differences from you. Here is the general syntax to specify versions differences from you. Here is the general syntax to specify versions
with the ``RDEPENDS`` variable:: with the :term:`RDEPENDS` variable::
RDEPENDS_${PN} = "package (operator version)" RDEPENDS_${PN} = "package (operator version)"
@@ -1219,19 +1219,19 @@ overview of their function and contents.
:term:`REQUIRED_VERSION` :term:`REQUIRED_VERSION`
If there are multiple versions of a recipe available, this variable If there are multiple versions of a recipe available, this variable
determines which version should be given preference. ``REQUIRED_VERSION`` determines which version should be given preference. :term:`REQUIRED_VERSION`
works in exactly the same manner as :term:`PREFERRED_VERSION`, except works in exactly the same manner as :term:`PREFERRED_VERSION`, except
that if the specified version is not available then an error message that if the specified version is not available then an error message
is shown and the build fails immediately. is shown and the build fails immediately.
If both ``REQUIRED_VERSION`` and ``PREFERRED_VERSION`` are set for If both :term:`REQUIRED_VERSION` and :term:`PREFERRED_VERSION` are set for
the same recipe, the ``REQUIRED_VERSION`` value applies. the same recipe, the :term:`REQUIRED_VERSION` value applies.
:term:`RPROVIDES` :term:`RPROVIDES`
A list of package name aliases that a package also provides. These A list of package name aliases that a package also provides. These
aliases are useful for satisfying runtime dependencies of other aliases are useful for satisfying runtime dependencies of other
packages both during the build and on the target (as specified by packages both during the build and on the target (as specified by
``RDEPENDS``). :term:`RDEPENDS`).
As with all package-controlling variables, you must always use the As with all package-controlling variables, you must always use the
variable in conjunction with a package name override. Here is an variable in conjunction with a package name override. Here is an
@@ -1244,12 +1244,12 @@ overview of their function and contents.
built. The package being built does not depend on this list of built. The package being built does not depend on this list of
packages in order to successfully build, but needs them for the packages in order to successfully build, but needs them for the
extended usability. To specify runtime dependencies for packages, see extended usability. To specify runtime dependencies for packages, see
the ``RDEPENDS`` variable. the :term:`RDEPENDS` variable.
BitBake supports specifying versioned recommends. Although the syntax BitBake supports specifying versioned recommends. Although the syntax
varies depending on the packaging format, BitBake hides these varies depending on the packaging format, BitBake hides these
differences from you. Here is the general syntax to specify versions differences from you. Here is the general syntax to specify versions
with the ``RRECOMMENDS`` variable:: with the :term:`RRECOMMENDS` variable::
RRECOMMENDS_${PN} = "package (operator version)" RRECOMMENDS_${PN} = "package (operator version)"
@@ -1273,10 +1273,10 @@ overview of their function and contents.
The list of source files - local or remote. This variable tells 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 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 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 from the Internet, the recipe or append file uses a :term:`SRC_URI` entry
that specifies that tarball. On the other hand, if the recipe or 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 append file needs to fetch a tarball and include a custom file, the
recipe or append file needs an ``SRC_URI`` variable that specifies recipe or append file needs an :term:`SRC_URI` variable that specifies
all those sources. all those sources.
The following list explains the available URI protocols: The following list explains the available URI protocols:
@@ -1329,8 +1329,8 @@ overview of their function and contents.
subdirectory within the archive. subdirectory within the archive.
- ``name`` : Specifies a name to be used for association with - ``name`` : Specifies a name to be used for association with
``SRC_URI`` checksums when you have more than one file specified :term:`SRC_URI` checksums when you have more than one file specified
in ``SRC_URI``. in :term:`SRC_URI`.
- ``downloadfilename`` : Specifies the filename used when storing - ``downloadfilename`` : Specifies the filename used when storing
the downloaded file. the downloaded file.
@@ -1345,7 +1345,7 @@ overview of their function and contents.
variable applies only when using Subversion, Git, Mercurial and variable applies only when using Subversion, Git, Mercurial and
Bazaar. If you want to build a fixed revision and you want to avoid 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 performing a query on the remote repository every time BitBake parses
your recipe, you should specify a ``SRCREV`` that is a full revision your recipe, you should specify a :term:`SRCREV` that is a full revision
identifier and not just a tag. identifier and not just a tag.
:term:`SRCREV_FORMAT` :term:`SRCREV_FORMAT`
@@ -1354,10 +1354,10 @@ overview of their function and contents.
:term:`SRC_URI`. :term:`SRC_URI`.
The system needs help constructing these values under these The system needs help constructing these values under these
circumstances. Each component in the ``SRC_URI`` is assigned a name circumstances. Each component in the :term:`SRC_URI` is assigned a name
and these are referenced in the ``SRCREV_FORMAT`` variable. Consider and these are referenced in the :term:`SRCREV_FORMAT` variable. Consider
an example with URLs named "machine" and "meta". In this case, an example with URLs named "machine" and "meta". In this case,
``SRCREV_FORMAT`` could look like "machine_meta" and those names :term:`SRCREV_FORMAT` could look like "machine_meta" and those names
would have the SCM versions substituted into each position. Only one would have the SCM versions substituted into each position. Only one
``AUTOINC`` placeholder is added and if needed. And, this placeholder ``AUTOINC`` placeholder is added and if needed. And, this placeholder
is placed at the start of the returned string. is placed at the start of the returned string.
@@ -1369,7 +1369,7 @@ overview of their function and contents.
:term:`STAMPCLEAN` :term:`STAMPCLEAN`
Specifies the base path used to create recipe stamp files. Unlike the Specifies the base path used to create recipe stamp files. Unlike the
:term:`STAMP` variable, ``STAMPCLEAN`` can contain :term:`STAMP` variable, :term:`STAMPCLEAN` can contain
wildcards to match the range of files a clean operation should wildcards to match the range of files a clean operation should
remove. BitBake uses a clean operation to remove any other stamps it remove. BitBake uses a clean operation to remove any other stamps it
should be removing when creating a new stamp. should be removing when creating a new stamp.