From 57300955beb200c81762880f44f1a499451b7432 Mon Sep 17 00:00:00 2001 From: Nicolas Dechesne Date: Thu, 30 Jul 2020 16:18:27 +0200 Subject: sphinx: fixup for links Since we converted the list of variables into a Sphinx glossary, the automatic conversion from Pandoc does not produce proper links. We fix them up using a Python regexp. Similarly some http links were not converted correctly, and can also be fixed up with a regexp. This patch was generated by running the following regexp: line = re.sub("` <(https?://.*)>`__", "\\1", line) line = re.sub("`+(\w+)`* <#var-bb-\\1>`__", ":term:`\\1`", line) Signed-off-by: Nicolas Dechesne --- .../bitbake-user-manual-execution.rst | 74 +++++++-------- .../bitbake-user-manual-fetching.rst | 44 ++++----- .../bitbake-user-manual-hello.rst | 24 ++--- .../bitbake-user-manual-intro.rst | 2 +- .../bitbake-user-manual-metadata.rst | 74 +++++++-------- .../bitbake-user-manual-ref-variables.rst | 102 ++++++++++----------- 6 files changed, 160 insertions(+), 160 deletions(-) diff --git a/doc/bitbake-user-manual/bitbake-user-manual-execution.rst b/doc/bitbake-user-manual/bitbake-user-manual-execution.rst index 9488ea9ba..d97fea42a 100644 --- a/doc/bitbake-user-manual/bitbake-user-manual-execution.rst +++ b/doc/bitbake-user-manual/bitbake-user-manual-execution.rst @@ -20,7 +20,7 @@ Command <#bitbake-user-manual-command>`__" section. Prior to executing BitBake, you should take advantage of available parallel thread execution on your build host by setting the - ```BB_NUMBER_THREADS`` <#var-bb-BB_NUMBER_THREADS>`__ variable in + :term:`BB_NUMBER_THREADS` variable in your project's ``local.conf`` configuration file. A common method to determine this value for your build host is to run @@ -52,7 +52,7 @@ data itself is of various types: together. The ``layer.conf`` files are used to construct key variables such as -```BBPATH`` <#var-bb-BBPATH>`__ and ```BBFILES`` <#var-bb-BBFILES>`__. +:term:`BBPATH` and :term:`BBFILES`. ``BBPATH`` is used to search for configuration and class files under the ``conf`` and ``classes`` directories, respectively. ``BBFILES`` is used to locate both recipe and recipe append files (``.bb`` and @@ -67,15 +67,15 @@ directives. Prior to parsing configuration files, BitBake looks at certain variables, including: -- ```BB_ENV_WHITELIST`` <#var-bb-BB_ENV_WHITELIST>`__ +- :term:`BB_ENV_WHITELIST` -- ```BB_ENV_EXTRAWHITE`` <#var-bb-BB_ENV_EXTRAWHITE>`__ +- :term:`BB_ENV_EXTRAWHITE` -- ```BB_PRESERVE_ENV`` <#var-bb-BB_PRESERVE_ENV>`__ +- :term:`BB_PRESERVE_ENV` -- ```BB_ORIGENV`` <#var-bb-BB_ORIGENV>`__ +- :term:`BB_ORIGENV` -- ```BITBAKE_UI`` <#var-bb-BITBAKE_UI>`__ +- :term:`BITBAKE_UI` The first four variables in this list relate to how BitBake treats shell environment variables during task execution. By default, BitBake cleans @@ -93,16 +93,16 @@ recipes and tasks that are executed. BitBake first searches the current working directory for an optional ``conf/bblayers.conf`` configuration file. This file is expected to -contain a ```BBLAYERS`` <#var-bb-BBLAYERS>`__ variable that is a +contain a :term:`BBLAYERS` variable that is a space-delimited list of 'layer' directories. Recall that if BitBake cannot find a ``bblayers.conf`` file, then it is assumed the user has set the ``BBPATH`` and ``BBFILES`` variables directly in the environment. For each directory (layer) in this list, a ``conf/layer.conf`` file is -located and parsed with the ```LAYERDIR`` <#var-bb-LAYERDIR>`__ variable +located and parsed with the :term:`LAYERDIR` variable being set to the directory where the layer was found. The idea is these -files automatically set up ```BBPATH`` <#var-bb-BBPATH>`__ and other +files automatically set up :term:`BBPATH` and other variables correctly for a given build directory. BitBake then expects to find the ``conf/bitbake.conf`` file somewhere in @@ -125,7 +125,7 @@ responsible for getting that class is encountered. The ``base.bbclass`` file is always included. Other classes that are specified in the configuration using the -```INHERIT`` <#var-bb-INHERIT>`__ variable are also included. BitBake +:term:`INHERIT` variable are also included. BitBake searches for class files in a ``classes`` subdirectory under the paths in ``BBPATH`` in the same way as configuration files. @@ -157,7 +157,7 @@ Locating and Parsing Recipes ============================ During the configuration phase, BitBake will have set -```BBFILES`` <#var-bb-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 apply. ``BBFILES`` is a space-separated list of available files and supports wildcards. An example would be: BBFILES = @@ -174,13 +174,13 @@ various variables into the datastore. 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 find and then parse class files (``.bbclass``) using -```BBPATH`` <#var-bb-BBPATH>`__ as the search path. Finally, BitBake +:term:`BBPATH` as the search path. Finally, BitBake parses in order any append files found in ``BBFILES``. One common convention is to use the recipe filename to define pieces of metadata. For example, in ``bitbake.conf`` the recipe name and version -are used to set the variables ```PN`` <#var-bb-PN>`__ and -```PV`` <#var-bb-PV>`__: PN = +are used to set the variables :term:`PN` and +:term:`PV`: PN = "${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE', False),d)[0] or 'defaultpkgname'}" PV = "${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE', False),d)[1] or @@ -201,7 +201,7 @@ and then reload it. Where possible, subsequent BitBake commands reuse this cache of recipe information. The validity of this cache is determined by first computing a checksum of the base configuration data (see -```BB_HASHCONFIG_WHITELIST`` <#var-bb-BB_HASHCONFIG_WHITELIST>`__) and +:term:`BB_HASHCONFIG_WHITELIST`) and then checking if the checksum matches. If that checksum matches what is in the cache and the recipe and class files have not changed, BitBake is able to use the cache. BitBake then reloads the cached information about @@ -233,8 +233,8 @@ the recipe files have been parsed, BitBake starts to figure out how to build the target. BitBake looks through the ``PROVIDES`` list for each of the recipes. A ``PROVIDES`` list is the list of names by which the recipe can be known. Each recipe's ``PROVIDES`` list is created -implicitly through the recipe's ```PN`` <#var-bb-PN>`__ variable and -explicitly through the recipe's ```PROVIDES`` <#var-bb-PROVIDES>`__ +implicitly through the recipe's :term:`PN` variable and +explicitly through the recipe's :term:`PROVIDES` variable, which is optional. When a recipe uses ``PROVIDES``, that recipe's functionality can be @@ -259,7 +259,7 @@ A common example in which a target has multiple providers is recipe. Each machine often selects the best kernel provider by using a line similar to the following in the machine configuration file: PREFERRED_PROVIDER_virtual/kernel = "linux-yocto" The default -```PREFERRED_PROVIDER`` <#var-bb-PREFERRED_PROVIDER>`__ is the provider +:term:`PREFERRED_PROVIDER` is the provider with the same name as the target. BitBake iterates through each target it needs to build and resolves them and their dependencies using this process. @@ -268,9 +268,9 @@ Understanding how providers are chosen is made complicated by the fact that multiple versions might exist for a given provider. BitBake defaults to the highest version of a provider. Version comparisons are made using the same method as Debian. You can use the -```PREFERRED_VERSION`` <#var-bb-PREFERRED_VERSION>`__ variable to +:term:`PREFERRED_VERSION` variable to specify a particular version. You can influence the order by using the -```DEFAULT_PREFERENCE`` <#var-bb-DEFAULT_PREFERENCE>`__ variable. +:term:`DEFAULT_PREFERENCE` variable. By default, files have a preference of "0". Setting ``DEFAULT_PREFERENCE`` to "-1" makes the recipe unlikely to be used @@ -283,15 +283,15 @@ undergone sufficient testing to be considered stable. When there are multiple “versions” of a given recipe, BitBake defaults to selecting the most recent version, unless otherwise specified. If the recipe in question has a -```DEFAULT_PREFERENCE`` <#var-bb-DEFAULT_PREFERENCE>`__ set lower than +:term:`DEFAULT_PREFERENCE` set lower than the other recipes (default is 0), then it will not be selected. This allows the person or persons maintaining the repository of recipe files to specify their preference for the default selected version. Additionally, the user can specify their preferred version. If the first recipe is named ``a_1.1.bb``, then the -```PN`` <#var-bb-PN>`__ variable will be set to “a”, and the -```PV`` <#var-bb-PV>`__ variable will be set to 1.1. +:term:`PN` variable will be set to “a”, and the +:term:`PV` variable will be set to 1.1. Thus, if a recipe named ``a_1.2.bb`` exists, BitBake will choose 1.2 by default. However, if you define the following variable in a ``.conf`` @@ -326,8 +326,8 @@ Dependencies are defined through several variables. You can find information about variables BitBake uses in the `Variables Glossary <#ref-bb-variables-glos>`__ near the end of this manual. At a basic level, it is sufficient to know that BitBake uses the -```DEPENDS`` <#var-bb-DEPENDS>`__ and -```RDEPENDS`` <#var-bb-RDEPENDS>`__ variables when calculating +:term:`DEPENDS` and +:term:`RDEPENDS` variables when calculating dependencies. For more information on how BitBake handles dependencies, see the @@ -345,7 +345,7 @@ section has more information on how BitBake chooses which task to execute next. The build now starts with BitBake forking off threads up to the limit -set in the ```BB_NUMBER_THREADS`` <#var-bb-BB_NUMBER_THREADS>`__ +set in the :term:`BB_NUMBER_THREADS` variable. BitBake continues to fork threads as long as there are tasks ready to run, those tasks have all their dependencies met, and the thread threshold has not been exceeded. @@ -354,7 +354,7 @@ It is worth noting that you can greatly speed up the build time by properly setting the ``BB_NUMBER_THREADS`` variable. As each task completes, a timestamp is written to the directory -specified by the ```STAMP`` <#var-bb-STAMP>`__ variable. On subsequent +specified by the :term:`STAMP` variable. On subsequent runs, BitBake looks in the build directory within ``tmp/stamps`` and does not rerun tasks that are already completed unless a timestamp is found to be invalid. Currently, invalid timestamps are only considered @@ -386,7 +386,7 @@ Executing Tasks Tasks can be either a shell task or a Python task. For shell tasks, BitBake writes a shell script to -``${``\ ```T`` <#var-bb-T>`__\ ``}/run.do_taskname.pid`` and then +``${``\ :term:`T`\ ``}/run.do_taskname.pid`` and then executes the script. The generated shell script contains all the exported variables, and the shell functions with all variables expanded. Output from the shell script goes to the file @@ -404,9 +404,9 @@ scheduler. It is possible to configure the scheduler and define custom implementations for specific use cases. For more information, see these variables that control the behavior: -- ```BB_SCHEDULER`` <#var-bb-BB_SCHEDULER>`__ +- :term:`BB_SCHEDULER` -- ```BB_SCHEDULERS`` <#var-bb-BB_SCHEDULERS>`__ +- :term:`BB_SCHEDULERS` It is possible to have functions run before and after a task's main function. This is done using the ``[prefuncs]`` and ``[postfuncs]`` @@ -432,7 +432,7 @@ changes because it should not affect the output for target packages. The simplistic approach for excluding the working directory is to set it to some fixed value and create the checksum for the "run" script. BitBake goes one step better and uses the -```BB_HASHBASE_WHITELIST`` <#var-bb-BB_HASHBASE_WHITELIST>`__ variable +:term:`BB_HASHBASE_WHITELIST` variable to define a list of variables that should never be included when generating the signatures. @@ -508,7 +508,7 @@ behavior is unchanged from previous versions. ``OE-Core`` uses the version but adds the task hash to the stamp files. This results in any metadata change that changes the task hash, automatically causing the task to be run again. This removes the need to bump -```PR`` <#var-bb-PR>`__ values, and changes to metadata automatically +:term:`PR` values, and changes to metadata automatically ripple across the build. It is also worth noting that the end result of these signature @@ -570,7 +570,7 @@ information is available, BitBake uses this information instead of running the main tasks. BitBake first calls the function defined by the -```BB_HASHCHECK_FUNCTION`` <#var-bb-BB_HASHCHECK_FUNCTION>`__ variable +:term:`BB_HASHCHECK_FUNCTION` variable with a list of tasks and corresponding hashes it wants to build. This function is designed to be fast and returns a list of the tasks for which it believes in can obtain artifacts. @@ -586,13 +586,13 @@ or failure. As previously mentioned, an artifact can cover more than one task. For example, it is pointless to obtain a compiler if you already have the compiled binary. To handle this, BitBake calls the -```BB_SETSCENE_DEPVALID`` <#var-bb-BB_SETSCENE_DEPVALID>`__ function for +:term:`BB_SETSCENE_DEPVALID` function for each successful setscene task to know whether or not it needs to obtain the dependencies of that task. Finally, after all the setscene tasks have executed, BitBake calls the function listed in -```BB_SETSCENE_VERIFY_FUNCTION2`` <#var-bb-BB_SETSCENE_VERIFY_FUNCTION2>`__ +:term:`BB_SETSCENE_VERIFY_FUNCTION2` with the list of tasks BitBake thinks has been "covered". The metadata can then ensure that this list is correct and can inform BitBake that it wants specific tasks to be run regardless of the setscene result. @@ -607,7 +607,7 @@ In addition to the standard command line option to control how verbose builds are when execute, bitbake also supports user defined configuration of the `Python logging `__ facilities -through the ```BB_LOGCONFIG`` <#var-bb-BB_LOGCONFIG>`__ variable. This +through the :term:`BB_LOGCONFIG` variable. This variable defines a json or yaml `logging configuration `__ that will be intelligently merged into the default configuration. The diff --git a/doc/bitbake-user-manual/bitbake-user-manual-fetching.rst b/doc/bitbake-user-manual/bitbake-user-manual-fetching.rst index 4285a73af..20451738a 100644 --- a/doc/bitbake-user-manual/bitbake-user-manual-fetching.rst +++ b/doc/bitbake-user-manual/bitbake-user-manual-fetching.rst @@ -26,7 +26,7 @@ The code to execute the first part of this process, a fetch, looks something like the following: src_uri = (d.getVar('SRC_URI') or "").split() fetcher = bb.fetch2.Fetch(src_uri, d) fetcher.download() This code sets up an instance of the fetch class. The instance uses a -space-separated list of URLs from the ```SRC_URI`` <#var-bb-SRC_URI>`__ +space-separated list of URLs from the :term:`SRC_URI` variable and then calls the ``download`` method to download the files. The instantiation of the fetch class is usually followed by: rootdir = @@ -51,13 +51,13 @@ URLs by looking for source files in a specific search order: - *Pre-mirror Sites:* BitBake first uses pre-mirrors to try and find source files. These locations are defined using the - ```PREMIRRORS`` <#var-bb-PREMIRRORS>`__ variable. + :term:`PREMIRRORS` variable. - *Source URI:* If pre-mirrors fail, BitBake uses the original URL (e.g from ``SRC_URI``). - *Mirror Sites:* If fetch failures occur, BitBake next uses mirror - locations as defined by the ```MIRRORS`` <#var-bb-MIRRORS>`__ + locations as defined by the :term:`MIRRORS` variable. For each URL passed to the fetcher, the fetcher calls the submodule that @@ -88,7 +88,7 @@ previous example does. Since network accesses are slow, BitBake maintains a cache of files downloaded from the network. Any source files that are not local (i.e. downloaded from the Internet) are placed into the download directory, -which is specified by the ```DL_DIR`` <#var-bb-DL_DIR>`__ variable. +which is specified by the :term:`DL_DIR` variable. File integrity is of key importance for reproducing builds. For non-local archive downloads, the fetcher code can verify SHA-256 and MD5 @@ -112,9 +112,9 @@ comparing a checksum for the file again. It is assumed that local storage is safe from data corruption. If this were not the case, there would be bigger issues to worry about. -If ```BB_STRICT_CHECKSUM`` <#var-bb-BB_STRICT_CHECKSUM>`__ is set, any +If :term:`BB_STRICT_CHECKSUM` is set, any download without a checksum triggers an error message. The -```BB_NO_NETWORK`` <#var-bb-BB_NO_NETWORK>`__ variable can be used to +:term:`BB_NO_NETWORK` variable can be used to make any attempted network access a fatal error, which is useful for checking that mirrors are complete as well as other things. @@ -170,9 +170,9 @@ Local file fetcher (``file://``) This submodule handles URLs that begin with ``file://``. The filename you specify within the URL can be either an absolute or relative path to a file. If the filename is relative, the contents of the -```FILESPATH`` <#var-bb-FILESPATH>`__ variable is used in the same way +:term:`FILESPATH` variable is used in the same way ``PATH`` is used to find executables. If the file cannot be found, it is -assumed that it is available in ```DL_DIR`` <#var-bb-DL_DIR>`__ by the +assumed that it is available in :term:`DL_DIR` by the time the ``download()`` method is called. If you specify a directory, the entire directory is unpacked. @@ -194,7 +194,7 @@ The executable and parameters used are specified by the fetcher supports a parameter "downloadfilename" that allows the name of the downloaded file to be specified. Specifying the name of the downloaded file is useful for avoiding collisions in -```DL_DIR`` <#var-bb-DL_DIR>`__ when dealing with multiple files that +:term:`DL_DIR` when dealing with multiple files that have the same name. Some example URLs are as follows: SRC_URI = @@ -243,7 +243,7 @@ system. You can configure it using a number of different variables: special value of "now" causes the checkout to be updated on every build. -- ```CVSDIR`` <#var-bb-CVSDIR>`__\ *:* Specifies where a temporary +- :term:`CVSDIR`\ *:* Specifies where a temporary checkout is saved. The location is often ``DL_DIR/cvs``. - *``CVS_PROXY_HOST``:* The name to use as a "proxy=" parameter to the @@ -269,14 +269,14 @@ The supported parameters are as follows: default, the TAG is empty. - *"date":* Specifies a date. If no "date" is specified, the - ```SRCDATE`` <#var-bb-SRCDATE>`__ of the configuration is used to + :term:`SRCDATE` of the configuration is used to checkout a specific date. The special value of "now" causes the checkout to be updated on every build. - *"localdir":* Used to rename the module. Effectively, you are renaming the output directory to which the module is unpacked. You are forcing the module into a special directory relative to - ```CVSDIR`` <#var-bb-CVSDIR>`__. + :term:`CVSDIR`. - *"rsh"* Used in conjunction with the "method" parameter. @@ -304,7 +304,7 @@ Subversion (SVN) Fetcher (``svn://``) This fetcher submodule fetches code from the Subversion source control system. The executable used is specified by ``FETCHCMD_svn``, which defaults to "svn". The fetcher's temporary working directory is set by -```SVNDIR`` <#var-bb-SVNDIR>`__, which is usually ``DL_DIR/svn``. +:term:`SVNDIR`, which is usually ``DL_DIR/svn``. The supported parameters are as follows: @@ -345,7 +345,7 @@ Git Fetcher (``git://``) This fetcher submodule fetches code from the Git source control system. The fetcher works by creating a bare clone of the remote into -```GITDIR`` <#var-bb-GITDIR>`__, which is usually ``DL_DIR/git2``. This +:term:`GITDIR`, which is usually ``DL_DIR/git2``. This bare clone is then cloned into the work directory during the unpack stage when a specific tree is checked out. This is done using alternates and by reference to minimize the amount of duplicate data on the disk @@ -416,7 +416,7 @@ Git Submodule Fetcher (``gitsm://``) This fetcher submodule inherits from the `Git fetcher <#git-fetcher>`__ and extends that fetcher's behavior by fetching a repository's -submodules. ```SRC_URI`` <#var-bb-SRC_URI>`__ is passed to the Git +submodules. :term:`SRC_URI` is passed to the Git fetcher as described in the "`Git Fetcher (``git://``) <#git-fetcher>`__" section. @@ -441,8 +441,8 @@ This fetcher submodule fetches code from a repository. To use this fetcher, make sure your recipe has proper -```SRC_URI`` <#var-bb-SRC_URI>`__, ```SRCREV`` <#var-bb-SRCREV>`__, and -```PV`` <#var-bb-PV>`__ settings. Here is an example: SRC_URI = +:term:`SRC_URI`, :term:`SRCREV`, and +:term:`PV` settings. Here is an example: SRC_URI = "ccrc://cc.example.org/ccrc;vob=/example_vob;module=/example_module" SRCREV = "EXAMPLE_CLEARCASE_TAG" PV = "${@d.getVar("SRCREV", False).replace("/", "+")}" The fetcher uses the ``rcleartool`` or @@ -510,15 +510,15 @@ This fetcher submodule fetches code from the `Perforce `__ source control system. The executable used is specified by ``FETCHCMD_p4``, which defaults to "p4". The fetcher's temporary working directory is set by -```P4DIR`` <#var-bb-P4DIR>`__, which defaults to "DL_DIR/p4". +:term:`P4DIR`, which defaults to "DL_DIR/p4". The fetcher does not make use of a perforce client, instead it relies on ``p4 files`` to retrieve a list of files and ``p4 print`` to transfer the content of those files locally. To use this fetcher, make sure your recipe has proper -```SRC_URI`` <#var-bb-SRC_URI>`__, ```SRCREV`` <#var-bb-SRCREV>`__, and -```PV`` <#var-bb-PV>`__ values. The p4 executable is able to use the +:term:`SRC_URI`, :term:`SRCREV`, and +:term:`PV` values. The p4 executable is able to use the config file defined by your system's ``P4CONFIG`` environment variable in order to define the Perforce server URL and port, username, and password if you do not wish to keep those values in a recipe itself. If @@ -584,8 +584,8 @@ Repo Fetcher (``repo://``) This fetcher submodule fetches code from ``google-repo`` source control system. The fetcher works by initiating and syncing sources of the -repository into ```REPODIR`` <#var-bb-REPODIR>`__, which is usually -```DL_DIR`` <#var-bb-DL_DIR>`__\ ``/repo``. +repository into :term:`REPODIR`, which is usually +:term:`DL_DIR`\ ``/repo``. This fetcher supports the following parameters: diff --git a/doc/bitbake-user-manual/bitbake-user-manual-hello.rst b/doc/bitbake-user-manual/bitbake-user-manual-hello.rst index 174c797ae..32d5b7bbc 100644 --- a/doc/bitbake-user-manual/bitbake-user-manual-hello.rst +++ b/doc/bitbake-user-manual/bitbake-user-manual-hello.rst @@ -73,7 +73,7 @@ While every attempt is made to explain what is happening during the example, the descriptions cannot cover everything. You can find further information throughout this manual. Also, you can actively participate in the -` `__ +http://lists.openembedded.org/mailman/listinfo/bitbake-devel discussion mailing list about the BitBake build tool. .. note:: @@ -120,7 +120,7 @@ Following is the complete "Hello World" example. ``conf/bblayers.conf`` file is relevant. When you run BitBake, it begins looking for metadata files. The - ```BBPATH`` <#var-bb-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 it. Without ``BBPATH``, BitBake cannot find any configuration files (``.conf``) or recipe files (``.bb``) at all. BitBake also cannot @@ -168,17 +168,17 @@ Following is the complete "Hello World" example. recipe files. For this example, you need to create the file in your project directory and define some key BitBake variables. For more information on the ``bitbake.conf`` file, see - ` `__. + http://git.openembedded.org/bitbake/tree/conf/bitbake.conf. Use the following commands to create the ``conf`` directory in the project directory: $ mkdir conf From within the ``conf`` directory, use some editor to create the ``bitbake.conf`` so that it contains - the following: `PN <#var-bb-PN>`__ = + the following: :term:`PN` = "${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE', False),d)[0] - or 'defaultpkgname'}" TMPDIR = "${`TOPDIR <#var-bb-TOPDIR>`__}/tmp" - `CACHE <#var-bb-CACHE>`__ = "${TMPDIR}/cache" - `STAMP <#var-bb-STAMP>`__ = "${TMPDIR}/${PN}/stamps" - `T <#var-bb-T>`__ = "${TMPDIR}/${PN}/work" `B <#var-bb-B>`__ = + or 'defaultpkgname'}" TMPDIR = "${:term:`TOPDIR`}/tmp" + :term:`CACHE` = "${TMPDIR}/cache" + :term:`STAMP` = "${TMPDIR}/${PN}/stamps" + :term:`T` = "${TMPDIR}/${PN}/work" :term:`B` = "${TMPDIR}/${PN}" .. note:: @@ -287,9 +287,9 @@ Following is the complete "Hello World" example. and the ``conf`` directory: $ cd $HOME $ mkdir mylayer $ cd mylayer $ mkdir conf Move to the ``conf`` directory and create a ``layer.conf`` file that has the following: BBPATH .= - ":${`LAYERDIR <#var-bb-LAYERDIR>`__}" `BBFILES <#var-bb-BBFILES>`__ + ":${:term:`LAYERDIR`}" :term:`BBFILES` += "${LAYERDIR}/*.bb" - `BBFILE_COLLECTIONS <#var-bb-BBFILE_COLLECTIONS>`__ += "mylayer" + :term:`BBFILE_COLLECTIONS` += "mylayer" `BBFILE_PATTERN_mylayer <#var-bb-BBFILE_PATTERN>`__ := "^${LAYERDIR_RE}/" For information on these variables, click the links to go to the definitions in the glossary. @@ -297,8 +297,8 @@ Following is the complete "Hello World" example. You need to create the recipe file next. Inside your layer at the top-level, use an editor and create a recipe file named ``printhello.bb`` that has the following: - `DESCRIPTION <#var-bb-DESCRIPTION>`__ = "Prints Hello World" - `PN <#var-bb-PN>`__ = 'printhello' `PV <#var-bb-PV>`__ = '1' python + :term:`DESCRIPTION` = "Prints Hello World" + :term:`PN` = 'printhello' :term:`PV` = '1' python do_build() { bb.plain("********************"); bb.plain("\* \*"); bb.plain("\* Hello, World! \*"); bb.plain("\* \*"); bb.plain("********************"); } The recipe file simply provides diff --git a/doc/bitbake-user-manual/bitbake-user-manual-intro.rst b/doc/bitbake-user-manual/bitbake-user-manual-intro.rst index 3c24e4e2c..f040d8134 100644 --- a/doc/bitbake-user-manual/bitbake-user-manual-intro.rst +++ b/doc/bitbake-user-manual/bitbake-user-manual-intro.rst @@ -513,7 +513,7 @@ the builds. Aside from separate configuration files for each target, you must also enable BitBake to perform multiple configuration builds. Enabling is accomplished by setting the -```BBMULTICONFIG`` <#var-bb-BBMULTICONFIG>`__ variable in the +:term:`BBMULTICONFIG` variable in the ``local.conf`` configuration file. As an example, suppose you had configuration files for ``target1`` and ``target2`` defined in the build directory. The following statement in the ``local.conf`` file both diff --git a/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst b/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst index 790065ef6..cea8d5ba2 100644 --- a/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst +++ b/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst @@ -397,7 +397,7 @@ Among the variables commonly exported to the environment are ``CC`` and Conditional Syntax (Overrides) ============================== -BitBake uses ```OVERRIDES`` <#var-bb-OVERRIDES>`__ to control what +BitBake uses :term:`OVERRIDES` to control what variables are overridden after BitBake parses recipes and configuration files. This section describes how you can use ``OVERRIDES`` as conditional metadata, talks about key expansion in relationship to @@ -463,7 +463,7 @@ variable. Internally, this is implemented by prepending the task (e.g. "task-compile:") to the value of - ```OVERRIDES`` <#var-bb-OVERRIDES>`__ for the local datastore of the + :term:`OVERRIDES` for the local datastore of the ``do_compile`` task. You can also use this syntax with other combinations (e.g. @@ -549,7 +549,7 @@ directives. Locating Include and Class Files -------------------------------- -BitBake uses the ```BBPATH`` <#var-bb-BBPATH>`__ variable to locate +BitBake uses the :term:`BBPATH` variable to locate needed include and class files. Additionally, BitBake searches the current directory for ``include`` and ``require`` directives. @@ -680,7 +680,7 @@ directive from within each recipe: require foo.inc ----------------------------------- When creating a configuration file (``.conf``), you can use the -```INHERIT`` <#var-bb-INHERIT>`__ configuration directive to inherit a +:term:`INHERIT` configuration directive to inherit a class. BitBake only supports this directive when used within a configuration file. @@ -837,7 +837,7 @@ functions and regular Python functions defined with "def": Python functions, but not on regular Python functions. - BitBake-style Python functions generate a separate - ``${``\ ```T`` <#var-bb-T>`__\ ``}/run.``\ function-name\ ``.``\ pid + ``${``\ :term:`T`\ ``}/run.``\ function-name\ ``.``\ pid script that is executed to run the function, and also generate a log file in ``${T}/log.``\ function-name\ ``.``\ pid if they are executed as tasks. @@ -1090,8 +1090,8 @@ environment, you must take these two steps: 1. Tell BitBake to load what you want from the environment into the datastore. You can do so through the - ```BB_ENV_WHITELIST`` <#var-bb-BB_ENV_WHITELIST>`__ and - ```BB_ENV_EXTRAWHITE`` <#var-bb-BB_ENV_EXTRAWHITE>`__ variables. For + :term:`BB_ENV_WHITELIST` and + :term:`BB_ENV_EXTRAWHITE` variables. For example, assume you want to prevent the build system from accessing your ``$HOME/.ccache`` directory. The following command "whitelists" the environment variable ``CCACHE_DIR`` causing BitBake to allow that @@ -1117,7 +1117,7 @@ environment, you must take these two steps: Sometimes, it is useful to be able to obtain information from the original execution environment. BitBake saves a copy of the original environment into a special variable named -```BB_ORIGENV`` <#var-bb-BB_ORIGENV>`__. +:term:`BB_ORIGENV`. The ``BB_ORIGENV`` variable returns a datastore object that can be queried using the standard datastore operators such as @@ -1149,12 +1149,12 @@ functionality of the task: recreated to empty them. - *``[depends]``:* Controls inter-task dependencies. See the - ```DEPENDS`` <#var-bb-DEPENDS>`__ variable and the "`Inter-Task + :term:`DEPENDS` variable and the "`Inter-Task Dependencies <#inter-task-dependencies>`__" section for more information. - *``[deptask]``:* Controls task build-time dependencies. See the - ```DEPENDS`` <#var-bb-DEPENDS>`__ variable and the "`Build + :term:`DEPENDS` variable and the "`Build Dependencies <#build-dependencies>`__" section for more information. - *``[dirs]``:* Directories that should be created before the task @@ -1189,7 +1189,7 @@ functionality of the task: your build host has a large number of cores but certain tasks need to be rate-limited due to various kinds of resource constraints (e.g. to avoid network throttling). ``number_threads`` works similarly to the - ```BB_NUMBER_THREADS`` <#var-bb-BB_NUMBER_THREADS>`__ variable but is + :term:`BB_NUMBER_THREADS` variable but is task-specific. Set the value globally. For example, the following makes sure the @@ -1211,14 +1211,14 @@ functionality of the task: - *``[prefuncs]``:* List of functions to call before the task executes. - *``[rdepends]``:* Controls inter-task runtime dependencies. See the - ```RDEPENDS`` <#var-bb-RDEPENDS>`__ variable, the - ```RRECOMMENDS`` <#var-bb-RRECOMMENDS>`__ variable, and the + :term:`RDEPENDS` variable, the + :term:`RRECOMMENDS` variable, and the "`Inter-Task Dependencies <#inter-task-dependencies>`__" section for more information. - *``[rdeptask]``:* Controls task runtime dependencies. See the - ```RDEPENDS`` <#var-bb-RDEPENDS>`__ variable, the - ```RRECOMMENDS`` <#var-bb-RRECOMMENDS>`__ variable, and the "`Runtime + :term:`RDEPENDS` variable, the + :term:`RRECOMMENDS` variable, and the "`Runtime Dependencies <#runtime-dependencies>`__" section for more information. @@ -1227,8 +1227,8 @@ functionality of the task: dependencies. - *``[recrdeptask]``:* Controls task recursive runtime dependencies. - See the ```RDEPENDS`` <#var-bb-RDEPENDS>`__ variable, the - ```RRECOMMENDS`` <#var-bb-RRECOMMENDS>`__ variable, and the + See the :term:`RDEPENDS` variable, the + :term:`RRECOMMENDS` variable, and the "`Recursive Dependencies <#recursive-dependencies>`__" section for more information. @@ -1390,8 +1390,8 @@ Variants - Class Extension Mechanism BitBake supports two features that facilitate creating from a single recipe file multiple incarnations of that recipe file where all incarnations are buildable. These features are enabled through the -```BBCLASSEXTEND`` <#var-bb-BBCLASSEXTEND>`__ and -```BBVERSIONS`` <#var-bb-BBVERSIONS>`__ variables. +:term:`BBCLASSEXTEND` and +:term:`BBVERSIONS` variables. .. note:: @@ -1420,7 +1420,7 @@ incarnations are buildable. These features are enabled through the - *``BBVERSIONS``:* This variable allows a single recipe to build multiple versions of a project from a single recipe file. You can also specify conditional metadata (using the - ```OVERRIDES`` <#var-bb-OVERRIDES>`__ mechanism) for a single + :term:`OVERRIDES` mechanism) for a single version, or an optionally named range of versions. Here is an example: BBVERSIONS = "1.0 2.0 git" SRC_URI_git = "git://someurl/somepath.git" BBVERSIONS = "1.0.[0-6]:1.0.0+ \\ @@ -1432,7 +1432,7 @@ incarnations are buildable. These features are enabled through the name is not only placed into overrides, but it is also made available for the metadata to use in the variable that defines the base recipe versions for use in ``file://`` search paths - (```FILESPATH`` <#var-bb-FILESPATH>`__). + (:term:`FILESPATH`). Dependencies ============ @@ -1491,7 +1491,7 @@ task depends on the completion of the ``do_printdate`` task. Build Dependencies ------------------ -BitBake uses the ```DEPENDS`` <#var-bb-DEPENDS>`__ variable to manage +BitBake uses the :term:`DEPENDS` variable to manage build time dependencies. The ``[deptask]`` varflag for tasks signifies the task of each item listed in ``DEPENDS`` that must complete before that task can be executed. Here is an example: do_configure[deptask] = @@ -1502,9 +1502,9 @@ execute. Runtime Dependencies -------------------- -BitBake uses the ```PACKAGES`` <#var-bb-PACKAGES>`__, -```RDEPENDS`` <#var-bb-RDEPENDS>`__, and -```RRECOMMENDS`` <#var-bb-RRECOMMENDS>`__ variables to manage runtime +BitBake uses the :term:`PACKAGES`, +:term:`RDEPENDS`, and +:term:`RRECOMMENDS` variables to manage runtime dependencies. The ``PACKAGES`` variable lists runtime packages. Each of those packages @@ -1670,7 +1670,7 @@ determine if a task needs to be run. This section describes the process. To help understand how BitBake does this, the section assumes an OpenEmbedded metadata-based example. -These checksums are stored in ```STAMP`` <#var-bb-STAMP>`__. You can +These checksums are stored in :term:`STAMP`. You can examine the checksums using the following BitBake command: $ bitbake-dumpsigs This command returns the signature data in a readable format that allows you to examine the inputs used when the OpenEmbedded @@ -1683,31 +1683,31 @@ Any changes to this variable would invalidate the stamp and cause the The following list describes related variables: -- ```BB_HASHCHECK_FUNCTION`` <#var-bb-BB_HASHCHECK_FUNCTION>`__: +- :term:`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. -- ```BB_SETSCENE_DEPVALID`` <#var-bb-BB_SETSCENE_DEPVALID>`__: +- :term:`BB_SETSCENE_DEPVALID`: Specifies a function BitBake calls that determines whether BitBake requires a setscene dependency to be met. -- ```BB_SETSCENE_VERIFY_FUNCTION2`` <#var-bb-BB_SETSCENE_VERIFY_FUNCTION2>`__: +- :term:`BB_SETSCENE_VERIFY_FUNCTION2`: Specifies a function to call that verifies the list of planned task execution before the main task execution happens. -- ```BB_STAMP_POLICY`` <#var-bb-BB_STAMP_POLICY>`__: Defines the mode +- :term:`BB_STAMP_POLICY`: Defines the mode for comparing timestamps of stamp files. -- ```BB_STAMP_WHITELIST`` <#var-bb-BB_STAMP_WHITELIST>`__: Lists stamp +- :term:`BB_STAMP_WHITELIST`: Lists stamp files that are looked at when the stamp policy is "whitelist". -- ```BB_TASKHASH`` <#var-bb-BB_TASKHASH>`__: Within an executing task, +- :term:`BB_TASKHASH`: Within an executing task, this variable holds the hash of the task as returned by the currently enabled signature generator. -- ```STAMP`` <#var-bb-STAMP>`__: The base path to create stamp files. +- :term:`STAMP`: The base path to create stamp files. -- ```STAMPCLEAN`` <#var-bb-STAMPCLEAN>`__: Again, the base path to +- :term:`STAMPCLEAN`: Again, the base path to create stamp files but can use wildcards for matching a range of files for clean operations. @@ -1718,10 +1718,10 @@ Support for wildcard use in variables varies depending on the context in which it is used. For example, some variables and file names allow limited use of wildcards through the "``%``" and "``*``" characters. Other variables or names support Python's -```glob`` `__ syntax, -```fnmatch`` `__ +```glob`https://docs.python.org/3/library/glob.html syntax, +```fnmatch`https://docs.python.org/3/library/fnmatch.html#module-fnmatch syntax, or -```Regular Expression (re)`` `__ +```Regular Expression (re)`https://docs.python.org/3/library/re.html#re syntax. For variables that have wildcard suport, the documentation describes 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 efc496039..f81c01c06 100644 --- a/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst +++ b/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst @@ -26,7 +26,7 @@ overview of their function and contents. .. glossary:: ASSUME_PROVIDED - Lists recipe names (```PN`` <#var-bb-PN>`__ values) BitBake does not + Lists recipe names (:term:`PN` values) BitBake does not attempt to build. Instead, BitBake assumes these recipes have already been built. @@ -45,7 +45,7 @@ overview of their function and contents. considerations surrounding this variable: - This host list is only used if - ```BB_NO_NETWORK`` <#var-bb-BB_NO_NETWORK>`__ is either not set or + :term:`BB_NO_NETWORK` is either not set or set to "0". - Limited support for the "``*``" wildcard character for matching @@ -69,11 +69,11 @@ overview of their function and contents. - 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 + :term:`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 + :term:`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. @@ -113,7 +113,7 @@ overview of their function and contents. 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>`__ + by the :term:`BB_DISKMON_WARNINTERVAL` variable, which must be defined. 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, @@ -128,7 +128,7 @@ overview of their function and contents. 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>`__ + :term:`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 @@ -151,7 +151,7 @@ overview of their function and contents. 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>`__ + must also use the :term:`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. @@ -182,10 +182,10 @@ overview of their function and contents. 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>`__. + list is used: :term:`BBPATH`, + :term:`BB_PRESERVE_ENV`, + :term:`BB_ENV_WHITELIST`, and + :term:`BB_ENV_EXTRAWHITE`. .. note:: @@ -196,7 +196,7 @@ overview of their function and contents. 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>`__. + :term:`BB_ENV_WHITELIST`. .. note:: @@ -205,9 +205,9 @@ overview of their function and contents. 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>`__. + :term:`PREMIRRORS` for files. BitBake will not + search the main :term:`SRC_URI` or + :term:`MIRRORS`. BB_FILENAME Contains the filename of the recipe that owns the currently running @@ -256,7 +256,7 @@ overview of their function and contents. 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 + to be placed in the :term:`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 @@ -308,7 +308,7 @@ overview of their function and contents. BB_LOGFMT Specifies the name of the log files saved into - ``${``\ ```T`` <#var-bb-T>`__\ ``}``. By default, the ``BB_LOGFMT`` + ``${``\ :term:`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 @@ -318,7 +318,7 @@ overview of their function and contents. 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 + :term:`BB_TASK_NICE_LEVEL` for additional information. BB_NO_NETWORK @@ -360,7 +360,7 @@ overview of their function and contents. BB_RUNFMT Specifies the name of the executable script files (i.e. run files) - saved into ``${``\ ```T`` <#var-bb-T>`__\ ``}``. By default, the + saved into ``${``\ :term:`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 @@ -390,7 +390,7 @@ overview of their function and contents. derived from the ``RunQueueScheduler`` class. For information how to select a scheduler, see the - ```BB_SCHEDULER`` <#var-bb-BB_SCHEDULER>`__ variable. + :term:`BB_SCHEDULER` variable. BB_SETSCENE_DEPVALID Specifies a function BitBake calls that determines whether BitBake @@ -456,7 +456,7 @@ overview of their function and contents. - *whitelist* - Identical to "full" mode except timestamp comparisons are made for recipes listed in the - ```BB_STAMP_WHITELIST`` <#var-bb-BB_STAMP_WHITELIST>`__ variable. + :term:`BB_STAMP_WHITELIST` variable. .. note:: @@ -466,7 +466,7 @@ overview of their function and contents. 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. + see the :term:`BB_STAMP_POLICY` variable. BB_STRICT_CHECKSUM Sets a more strict checksum mechanism for non-local URLs. Setting @@ -555,7 +555,7 @@ overview of their function and contents. 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 + a recipe, a :term:`DEPENDS` on "foo" is rewritten to a ``DEPENDS`` on "foo-native". Even when using ``BBCLASSEXTEND``, the recipe is only parsed once. @@ -580,7 +580,7 @@ overview of their function and contents. BBFILE_PATTERN Variable that expands to match files from - ```BBFILES`` <#var-bb-BBFILES>`__ in a particular layer. This + :term:`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``). @@ -593,7 +593,7 @@ overview of their function and contents. 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). + regardless of a recipe's version (:term:`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. @@ -617,7 +617,7 @@ overview of their function and contents. software. When specifying recipe files, you can pattern match using Python's - ```glob`` `__ syntax. + ```glob`https://docs.python.org/3/library/glob.html syntax. For details on the syntax, see the documentation by following the previous link. @@ -630,7 +630,7 @@ overview of their function and contents. failed task. BBINCLUDELOGS_LINES - If ```BBINCLUDELOGS`` <#var-bb-BBINCLUDELOGS>`__ is set, specifies + If :term:`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. @@ -662,7 +662,7 @@ overview of their function and contents. 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 ` `__. + 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 @@ -718,7 +718,7 @@ overview of their function and contents. 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 + using the :term:`OVERRIDES` mechanism for a single version or for an optionally named range of versions. For more information on ``BBVERSIONS``, see the "`Variants - Class @@ -780,7 +780,7 @@ overview of their function and contents. "a" is configuring itself. For information on runtime dependencies, see the - ```RDEPENDS`` <#var-bb-RDEPENDS>`__ variable. + :term:`RDEPENDS` variable. DESCRIPTION A long description for the recipe. @@ -790,7 +790,7 @@ overview of their function and contents. 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>`__ + :term:`BB_GENERATE_MIRROR_TARBALLS` variable. EXCLUDE_FROM_WORLD @@ -820,7 +820,7 @@ overview of their function and contents. FAKEROOTBASEENV Lists environment variables to set when executing the command defined - by ```FAKEROOTCMD`` <#var-bb-FAKEROOTCMD>`__ that starts the + by :term:`FAKEROOTCMD` that starts the bitbake-worker process in the fakeroot environment. FAKEROOTCMD @@ -835,13 +835,13 @@ overview of their function and contents. 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. + :term:`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. + :term:`FAKEROOTENV` variable. FETCHCMD Defines the command the BitBake fetcher module executes when running @@ -888,7 +888,7 @@ overview of their function and contents. 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 + :term:`LAYERVERSION`\ ``_anotherlayer`` in this case). BitBake produces an error if any dependency is missing or the version numbers do not match exactly (if specified). @@ -905,14 +905,14 @@ overview of their function and contents. 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 + expression (:term:`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 + :term:`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 @@ -926,7 +926,7 @@ overview of their function and contents. 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 + locations defined by :term:`PREMIRRORS`, the upstream source, and then locations specified by ``MIRRORS`` in that order. @@ -964,7 +964,7 @@ overview of their function and contents. 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 + runtime dependency (:term:`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. @@ -995,7 +995,7 @@ overview of their function and contents. 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 + :term:`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" @@ -1004,7 +1004,7 @@ overview of their function and contents. 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 + :term:`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 @@ -1014,8 +1014,8 @@ overview of their function and contents. 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 + suffix the variable with the :term:`PN` you want to + select, and you should set :term:`PV` accordingly for precedence. The ``PREFERRED_VERSION`` variable supports limited wildcard use @@ -1038,7 +1038,7 @@ overview of their function and contents. 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 + locations specified by :term:`MIRRORS` in that order. Typically, you would add a specific server for the build system to @@ -1072,7 +1072,7 @@ overview of their function and contents. 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 + virtual target in :term:`DEPENDS` to leave the choice of provider open. Conventionally, virtual targets have names on the form @@ -1080,7 +1080,7 @@ overview of their function and contents. of the name and has no syntactical significance. PRSERV_HOST - The network based ```PR`` <#var-bb-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: PRSERV_HOST = "localhost:0" You must set the variable if you want to @@ -1114,7 +1114,7 @@ overview of their function and contents. greater of the package ``foo``: RDEPENDS_${PN} = "foo (>= 1.2)" For information on build-time dependencies, see the - ```DEPENDS`` <#var-bb-DEPENDS>`__ variable. + :term:`DEPENDS` variable. REPODIR The directory in which a local copy of a ``google-repo`` directory is @@ -1163,7 +1163,7 @@ overview of their function and contents. - *``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. + the :term:`FILESPATH` variable. - *``bzr://`` -* Fetches files from a Bazaar revision control repository. @@ -1227,9 +1227,9 @@ overview of their function and contents. identifier and not just a tag. SRCREV_FORMAT - Helps construct valid ```SRCREV`` <#var-bb-SRCREV>`__ values when + Helps construct valid :term:`SRCREV` values when multiple source controlled URLs are used in - ```SRC_URI`` <#var-bb-SRC_URI>`__. + :term:`SRC_URI`. The system needs help constructing these values under these circumstances. Each component in the ``SRC_URI`` is assigned a name @@ -1247,7 +1247,7 @@ overview of their function and contents. STAMPCLEAN Specifies the base path used to create recipe stamp files. Unlike the - ```STAMP`` <#var-bb-STAMP>`__ variable, ``STAMPCLEAN`` can contain + :term:`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. -- cgit 1.2.3-korg