diff options
Diffstat (limited to 'bitbake/doc')
| -rw-r--r-- | bitbake/doc/Makefile | 35 | ||||
| -rw-r--r-- | bitbake/doc/README | 8 | ||||
| -rw-r--r-- | bitbake/doc/_templates/footer.html | 9 | ||||
| -rw-r--r-- | bitbake/doc/bitbake-user-manual/bitbake-user-manual-execution.rst | 182 | ||||
| -rw-r--r-- | bitbake/doc/bitbake-user-manual/bitbake-user-manual-fetching.rst | 309 | ||||
| -rw-r--r-- | bitbake/doc/bitbake-user-manual/bitbake-user-manual-hello.rst | 195 | ||||
| -rw-r--r-- | bitbake/doc/bitbake-user-manual/bitbake-user-manual-intro.rst | 64 | ||||
| -rw-r--r-- | bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst | 591 | ||||
| -rw-r--r-- | bitbake/doc/bitbake-user-manual/bitbake-user-manual-ref-variables-context.rst | 91 | ||||
| -rw-r--r-- | bitbake/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst | 793 | ||||
| -rw-r--r-- | bitbake/doc/conf.py | 1 | ||||
| -rw-r--r-- | bitbake/doc/index.rst | 1 | ||||
| -rw-r--r-- | bitbake/doc/releases.rst | 92 |
13 files changed, 1548 insertions, 823 deletions
diff --git a/bitbake/doc/Makefile b/bitbake/doc/Makefile new file mode 100644 index 0000000000..996f01b7d5 --- /dev/null +++ b/bitbake/doc/Makefile @@ -0,0 +1,35 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= -W --keep-going -j auto +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +BUILDDIR = _build +DESTDIR = final + +ifeq ($(shell if which $(SPHINXBUILD) >/dev/null 2>&1; then echo 1; else echo 0; fi),0) +$(error "The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed") +endif + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile clean publish + +publish: Makefile html singlehtml + rm -rf $(BUILDDIR)/$(DESTDIR)/ + mkdir -p $(BUILDDIR)/$(DESTDIR)/ + cp -r $(BUILDDIR)/html/* $(BUILDDIR)/$(DESTDIR)/ + cp $(BUILDDIR)/singlehtml/index.html $(BUILDDIR)/$(DESTDIR)/singleindex.html + sed -i -e 's@index.html#@singleindex.html#@g' $(BUILDDIR)/$(DESTDIR)/singleindex.html + +clean: + @rm -rf $(BUILDDIR) + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/bitbake/doc/README b/bitbake/doc/README index 62595820bd..d4f56afa37 100644 --- a/bitbake/doc/README +++ b/bitbake/doc/README @@ -8,12 +8,12 @@ Manual Organization Folders exist for individual manuals as follows: -* bitbake-user-manual - The BitBake User Manual +* bitbake-user-manual --- The BitBake User Manual Each folder is self-contained regarding content and figures. If you want to find HTML versions of the BitBake manuals on the web, -go to http://www.openembedded.org/wiki/Documentation. +go to https://www.openembedded.org/wiki/Documentation. Sphinx ====== @@ -47,8 +47,8 @@ To install all required packages run: To build the documentation locally, run: - $ cd documentation - $ make -f Makefile.sphinx html + $ cd doc + $ make html The resulting HTML index page will be _build/html/index.html, and you can browse your own copy of the locally generated documentation with diff --git a/bitbake/doc/_templates/footer.html b/bitbake/doc/_templates/footer.html new file mode 100644 index 0000000000..1398f20d7e --- /dev/null +++ b/bitbake/doc/_templates/footer.html @@ -0,0 +1,9 @@ +<footer> + <hr/> + <div role="contentinfo"> + <p>© Copyright {{ copyright }} + <br>Last updated on {{ last_updated }} from the <a href="https://git.openembedded.org/bitbake/">bitbake</a> git repository. + </p> + </div> +</footer> + diff --git a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-execution.rst b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-execution.rst index d74e768f69..d58fbb32ea 100644 --- a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-execution.rst +++ b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-execution.rst @@ -16,7 +16,7 @@ data, or simply return information about the execution environment. This chapter describes BitBake's execution process from start to finish when you use it to create an image. The execution process is launched -using the following command form: :: +using the following command form:: $ bitbake target @@ -32,7 +32,7 @@ the BitBake command and its options, see ":ref:`The BitBake Command your project's ``local.conf`` configuration file. A common method to determine this value for your build host is to run - the following: :: + the following:: $ grep processor /proc/cpuinfo @@ -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. Thus, a quad-core build host with hyper-threading most likely shows 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. 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 :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 +:term:`BBPATH` is used to search for configuration and class files under the +``conf`` and ``classes`` directories, respectively. :term:`BBFILES` is used to locate both recipe and recipe append files (``.bb`` and ``.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 other configuration files using the ``include`` or ``require`` directives. @@ -79,8 +79,8 @@ directives. Prior to parsing configuration files, BitBake looks at certain variables, including: -- :term:`BB_ENV_WHITELIST` -- :term:`BB_ENV_EXTRAWHITE` +- :term:`BB_ENV_PASSTHROUGH` +- :term:`BB_ENV_PASSTHROUGH_ADDITIONS` - :term:`BB_PRESERVE_ENV` - :term:`BB_ORIGENV` - :term:`BITBAKE_UI` @@ -104,7 +104,7 @@ BitBake first searches the current working directory for an optional 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 +set the :term:`BBPATH` and :term:`BBFILES` variables directly in the environment. 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. 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 to the architecture, the machine, the local environment, and so forth. @@ -135,11 +135,11 @@ The ``base.bbclass`` file is always included. Other classes that are specified in the configuration using the :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. +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 used in your execution environment is to run the following BitBake -command: :: +command:: $ bitbake -e > mybb.log @@ -155,7 +155,7 @@ execution environment. pair of curly braces in a shell function, the closing curly brace must not be located at the start of the line without leading spaces. - Here is an example that causes BitBake to produce a parsing error: :: + Here is an example that causes BitBake to produce a parsing error:: fakeroot create_shar() { cat << "EOF" > ${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.sh @@ -184,13 +184,13 @@ Locating and Parsing Recipes During the configuration phase, BitBake will have set :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: :: +apply. :term:`BBFILES` is a space-separated list of available files and +supports wildcards. An example would be:: BBFILES = "/path/to/bbfiles/*.bb /path/to/appends/*.bbappend" 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. .. note:: @@ -201,18 +201,18 @@ 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 :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 metadata. For example, in ``bitbake.conf`` the recipe name and version are used to set the variables :term:`PN` and -:term:`PV`: :: +: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 '1.0'}" + PN = "${@bb.parse.vars_from_file(d.getVar('FILE', False),d)[0] or 'defaultpkgname'}" + PV = "${@bb.parse.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 -``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 tasks that the recipe defines and a set of data consisting of keys and @@ -228,7 +228,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 -:term:`BB_HASHCONFIG_WHITELIST`) and +:term:`BB_HASHCONFIG_IGNORE_VARS`) 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 @@ -238,13 +238,14 @@ Recipe file collections exist to allow the user to have multiple repositories of ``.bb`` files that contain the same exact package. For example, one could easily use them to make one's own local copy of an upstream repository, but with custom modifications that one does not -want upstream. Here is an example: :: +want upstream. Here is an example:: BBFILES = "/stuff/openembedded/*/*.bb /stuff/openembedded.modified/*/*.bb" BBFILE_COLLECTIONS = "upstream local" BBFILE_PATTERN_upstream = "^/stuff/openembedded/" BBFILE_PATTERN_local = "^/stuff/openembedded.modified/" - BBFILE_PRIORITY_upstream = "5" BBFILE_PRIORITY_local = "10" + BBFILE_PRIORITY_upstream = "5" + BBFILE_PRIORITY_local = "10" .. note:: @@ -259,21 +260,21 @@ Providers 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 -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 +build the target. BitBake looks through the :term:`PROVIDES` list for each +of the recipes. A :term:`PROVIDES` list is the list of names by which the +recipe can be known. Each recipe's :term:`PROVIDES` list is created 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 -found under an alternative name or names other than the implicit ``PN`` +When a recipe uses :term:`PROVIDES`, that recipe's functionality can be +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`` -contained the following: :: +contained the following:: PROVIDES += "fullkeyboard" -The ``PROVIDES`` +The :term:`PROVIDES` list for this recipe becomes "keyboard", which is implicit, and "fullkeyboard", which is explicit. Consequently, the functionality found in ``keyboard_1.0.bb`` can be found under two different names. @@ -283,14 +284,14 @@ in ``keyboard_1.0.bb`` can be found under two different names. 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 needs to prioritize providers by determining provider preferences. 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 -line similar to the following in the machine configuration file: :: +line similar to the following in the machine configuration file:: PREFERRED_PROVIDER_virtual/kernel = "linux-yocto" @@ -308,10 +309,10 @@ specify a particular version. You can influence the order by using the :term:`DEFAULT_PREFERENCE` variable. By default, files have a preference of "0". Setting -``DEFAULT_PREFERENCE`` to "-1" makes the recipe unlikely to be used -unless it is explicitly referenced. Setting ``DEFAULT_PREFERENCE`` to -"1" makes it likely the recipe is used. ``PREFERRED_VERSION`` overrides -any ``DEFAULT_PREFERENCE`` setting. ``DEFAULT_PREFERENCE`` is often used +:term:`DEFAULT_PREFERENCE` to "-1" makes the recipe unlikely to be used +unless it is explicitly referenced. Setting :term:`DEFAULT_PREFERENCE` to +"1" makes it likely the recipe is used. :term:`PREFERRED_VERSION` overrides +any :term:`DEFAULT_PREFERENCE` setting. :term:`DEFAULT_PREFERENCE` is often used to mark newer and more experimental recipe versions until they have undergone sufficient testing to be considered stable. @@ -330,7 +331,7 @@ If the first recipe is named ``a_1.1.bb``, then the 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`` -file that BitBake parses, you can change that preference: :: +file that BitBake parses, you can change that preference:: PREFERRED_VERSION_a = "1.1" @@ -393,7 +394,7 @@ ready to run, those tasks have all their dependencies met, and the thread threshold has not been exceeded. 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 specified by the :term:`STAMP` variable. On subsequent @@ -434,7 +435,7 @@ BitBake writes a shell script to 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 -``${T}/log.do_taskname.pid``. Looking at the expanded shell functions in +``${``\ :term:`T`\ ``}/log.do_taskname.pid``. Looking at the expanded shell functions in the run file and the output in the log files is a useful debugging technique. @@ -476,7 +477,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 -:term:`BB_HASHBASE_WHITELIST` variable +:term:`BB_BASEHASH_IGNORE_VARS` variable to define a list of variables that should never be included when generating the signatures. @@ -497,7 +498,7 @@ to the task. Like the working directory case, situations exist where dependencies should be ignored. For these cases, you can instruct the build process -to ignore a dependency by using a line like the following: :: +to ignore a dependency by using a line like the following:: PACKAGE_ARCHS[vardepsexclude] = "MACHINE" @@ -507,7 +508,7 @@ even if it does reference it. Equally, there are cases where we need to add dependencies BitBake is not able to find. You can accomplish this by using a line like the -following: :: +following:: PACKAGE_ARCHS[vardeps] = "MACHINE" @@ -522,7 +523,7 @@ it cannot figure out dependencies. Thus far, this section has limited discussion to the direct inputs into a task. Information based on direct inputs is referred to as the "basehash" in the code. However, there is still the question of a task's -indirect inputs - the things that were already built and present in the +indirect inputs --- the things that were already built and present in the build directory. The checksum (or signature) for a particular task needs to add the hashes of all the tasks on which the particular task depends. Choosing which dependencies to add is a policy decision. However, the @@ -533,11 +534,11 @@ At the code level, there are a variety of ways both the basehash and the dependent task hashes can be influenced. Within the BitBake configuration file, we can give BitBake some extra information to help it construct the basehash. The following statement effectively results -in a list of global variable dependency excludes - variables never +in a list of global variable dependency excludes --- variables never included in any checksum. This example uses variables from OpenEmbedded -to help illustrate the concept: :: +to help illustrate the concept:: - BB_HASHBASE_WHITELIST ?= "TMPDIR FILE PATH PWD BB_TASKHASH BBPATH DL_DIR \ + BB_BASEHASH_IGNORE_VARS ?= "TMPDIR FILE PATH PWD BB_TASKHASH BBPATH DL_DIR \ SSTATE_DIR THISDIR FILESEXTRAPATHS FILE_DIRNAME HOME LOGNAME SHELL \ USER FILESPATH STAGING_DIR_HOST STAGING_DIR_TARGET COREBASE PRSERV_HOST \ PRSERV_DUMPDIR PRSERV_DUMPFILE PRSERV_LOCKDOWN PARALLEL_MAKE \ @@ -551,23 +552,22 @@ through dependency chains are more complex and are generally accomplished with a Python function. The code in ``meta/lib/oe/sstatesig.py`` shows two examples of this and also illustrates how you can insert your own policy into the system if so -desired. This file defines the two basic signature generators -OpenEmbedded-Core uses: "OEBasic" and "OEBasicHash". By default, there +desired. This file defines the basic signature generator +OpenEmbedded-Core uses: "OEBasicHash". By default, there is a dummy "noop" signature handler enabled in BitBake. This means that behavior is unchanged from previous versions. ``OE-Core`` uses the "OEBasicHash" signature handler by default through this setting in the -``bitbake.conf`` file: :: +``bitbake.conf`` file:: BB_SIGNATURE_HANDLER ?= "OEBasicHash" -The "OEBasicHash" ``BB_SIGNATURE_HANDLER`` is the same as the "OEBasic" -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 -:term:`PR` values, and changes to metadata automatically -ripple across the build. +The main feature of the "OEBasicHash" :term:`BB_SIGNATURE_HANDLER` is that +it adds the task hash to the stamp files. Thanks to this, any metadata +change will change the task hash, automatically causing the task to be run +again. This removes the need to bump :term:`PR` values, and changes to +metadata automatically ripple across the build. -It is also worth noting that the end result of these signature +It is also worth noting that the end result of signature generators is to make some dependency and hash information available to the build. This information includes: @@ -577,10 +577,7 @@ the build. This information includes: - ``BB_BASEHASH_``\ *filename:taskname*: The base hashes for each dependent task. -- ``BBHASHDEPS_``\ *filename:taskname*: The task dependencies for - 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 processing of signatures. The options passed to -S allow different @@ -589,10 +586,11 @@ or possibly those defined in the metadata/signature handler itself. The simplest parameter to pass is "none", which causes a set of signature information to be written out into ``STAMPS_DIR`` corresponding to the targets specified. The other currently available parameter is -"printdiff", which causes BitBake to try to establish the closest +"printdiff", which causes BitBake to try to establish the most recent signature match it can (e.g. in the sstate cache) and then run -``bitbake-diffsigs`` over the matches to determine the stamps and delta -where these two stamp trees diverge. +compare the matched signatures to determine the stamps and delta +where these two stamp trees diverge. This can be used to determine why +tasks need to be re-run in situations where that is not expected. .. note:: @@ -647,13 +645,6 @@ compiled binary. To handle this, BitBake calls the 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 -: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. - You can find more information on setscene metadata in the :ref:`bitbake-user-manual/bitbake-user-manual-metadata:task checksums and setscene` section. @@ -666,7 +657,7 @@ builds are when execute, bitbake also supports user defined configuration of the `Python logging <https://docs.python.org/3/library/logging.html>`__ facilities through the :term:`BB_LOGCONFIG` variable. This -variable defines a json or yaml `logging +variable defines a JSON or YAML `logging configuration <https://docs.python.org/3/library/logging.config.html>`__ that will be intelligently merged into the default configuration. The logging configuration is merged using the following rules: @@ -700,9 +691,9 @@ logging configuration is merged using the following rules: adds a filter called ``BitBake.defaultFilter``, both filters will be applied to the logger -As an example, consider the following user logging configuration file -which logs all Hash Equivalence related messages of VERBOSE or higher to -a file called ``hashequiv.log`` :: +As a first example, you can create a ``hashequiv.json`` user logging +configuration file to log all Hash Equivalence related messages of ``VERBOSE`` +or higher priority to a file called ``hashequiv.log``:: { "version": 1, @@ -731,3 +722,40 @@ a file called ``hashequiv.log`` :: } } } + +Then set the :term:`BB_LOGCONFIG` variable in ``conf/local.conf``:: + + BB_LOGCONFIG = "hashequiv.json" + +Another example is this ``warn.json`` file to log all ``WARNING`` and +higher priority messages to a ``warn.log`` file:: + + { + "version": 1, + "formatters": { + "warnlogFormatter": { + "()": "bb.msg.BBLogFormatter", + "format": "%(levelname)s: %(message)s" + } + }, + + "handlers": { + "warnlog": { + "class": "logging.FileHandler", + "formatter": "warnlogFormatter", + "level": "WARNING", + "filename": "warn.log" + } + }, + + "loggers": { + "BitBake": { + "handlers": ["warnlog"] + } + }, + + "@disable_existing_loggers": false + } + +Note that BitBake's helper classes for structured logging are implemented in +``lib/bb/msg.py``. diff --git a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-fetching.rst b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-fetching.rst index 6760b10828..fb4f0a23d7 100644 --- a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-fetching.rst +++ b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-fetching.rst @@ -27,7 +27,7 @@ and unpacking the files is often optionally followed by patching. Patching, however, is not covered by this module. The code to execute the first part of this process, a fetch, looks -something like the following: :: +something like the following:: src_uri = (d.getVar('SRC_URI') or "").split() fetcher = bb.fetch2.Fetch(src_uri, d) @@ -37,7 +37,7 @@ This code sets up an instance of the fetch class. The instance uses a 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: :: +The instantiation of the fetch class is usually followed by:: rootdir = l.getVar('WORKDIR') fetcher.unpack(rootdir) @@ -51,7 +51,7 @@ This code unpacks the downloaded files to the specified by ``WORKDIR``. 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 different variable names. In OpenEmbedded for example, the shared state (sstate) code uses the fetch module to fetch the sstate files. @@ -64,38 +64,38 @@ URLs by looking for source files in a specific search order: :term:`PREMIRRORS` variable. - *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 locations as defined by the :term:`MIRRORS` variable. 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 -some confusion when you are providing URLs for the ``SRC_URI`` variable. -Consider the following two URLs: :: +some confusion when you are providing URLs for the :term:`SRC_URI` variable. +Consider the following two URLs:: - http://git.yoctoproject.org/git/poky;protocol=git + https://git.yoctoproject.org/git/poky;protocol=git git://git.yoctoproject.org/git/poky;protocol=http In the former case, the URL is passed to the ``wget`` fetcher, which does not understand "git". Therefore, the latter case is the correct form since the Git fetcher does know how to use HTTP as a transport. -Here are some examples that show commonly used mirror definitions: :: +Here are some examples that show commonly used mirror definitions:: PREMIRRORS ?= "\ - bzr://.*/.\* http://somemirror.org/sources/ \\n \ - cvs://.*/.\* http://somemirror.org/sources/ \\n \ - git://.*/.\* http://somemirror.org/sources/ \\n \ - hg://.*/.\* http://somemirror.org/sources/ \\n \ - osc://.*/.\* http://somemirror.org/sources/ \\n \ - p4://.*/.\* http://somemirror.org/sources/ \\n \ - svn://.*/.\* http://somemirror.org/sources/ \\n" + bzr://.*/.\* http://somemirror.org/sources/ \ + cvs://.*/.\* http://somemirror.org/sources/ \ + git://.*/.\* http://somemirror.org/sources/ \ + hg://.*/.\* http://somemirror.org/sources/ \ + osc://.*/.\* http://somemirror.org/sources/ \ + p4://.*/.\* http://somemirror.org/sources/ \ + svn://.*/.\* http://somemirror.org/sources/" MIRRORS =+ "\ - ftp://.*/.\* http://somemirror.org/sources/ \\n \ - http://.*/.\* http://somemirror.org/sources/ \\n \ - https://.*/.\* http://somemirror.org/sources/ \\n" + ftp://.*/.\* http://somemirror.org/sources/ \ + http://.*/.\* http://somemirror.org/sources/ \ + https://.*/.\* http://somemirror.org/sources/" It is useful to note that BitBake supports cross-URLs. It is possible to mirror a Git repository on an @@ -110,26 +110,26 @@ 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 checksums to ensure the archives have been downloaded correctly. You can -specify these checksums by using the ``SRC_URI`` variable with the -appropriate varflags as follows: :: +specify these checksums by using the :term:`SRC_URI` variable with the +appropriate varflags as follows:: SRC_URI[md5sum] = "value" SRC_URI[sha256sum] = "value" 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" If multiple URIs exist, you can specify the checksums either directly as in the previous example, or you can name the URLs. The following syntax -shows how you name the URIs: :: +shows how you name the URIs:: SRC_URI = "http://example.com/foobar.tar.bz2;name=foo" SRC_URI[foo.md5sum] = 4a8e0f237e961fd7785d19d07fdb994d 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 comparing a checksum for the file again. @@ -144,6 +144,10 @@ download without a checksum triggers an error message. The make any attempted network access a fatal error, which is useful for checking that mirrors are complete as well as other things. +If :term:`BB_CHECK_SSL_CERTS` is set to ``0`` then SSL certificate checking will +be disabled. This variable defaults to ``1`` so SSL certificates are normally +checked. + .. _bb-the-unpack: The Unpack @@ -163,8 +167,8 @@ govern the behavior of the unpack stage: - *dos:* Applies to ``.zip`` and ``.jar`` files and specifies whether to use DOS line ending conversion on text files. -- *basepath:* Instructs the unpack stage to strip the specified - directories from the source path when unpacking. +- *striplevel:* Strip specified number of leading components (levels) + from file names on extraction - *subdir:* Unpacks the specific URL to the specified subdirectory within the root directory. @@ -204,7 +208,7 @@ time the ``download()`` method is called. If you specify a directory, the entire directory is unpacked. Here are a couple of example URLs, the first relative and the second -absolute: :: +absolute:: SRC_URI = "file://relativefile.patch" SRC_URI = "file:///Users/ich/very_important_software" @@ -225,7 +229,12 @@ downloaded file is useful for avoiding collisions in :term:`DL_DIR` when dealing with multiple files that have the same name. -Some example URLs are as follows: :: +If a username and password are specified in the ``SRC_URI``, a Basic +Authorization header will be added to each request, including across redirects. +To instead limit the Authorization header to the first request, add +"redirectauth=0" to the list of parameters. + +Some example URLs are as follows:: SRC_URI = "http://oe.handhelds.org/not_there.aac" SRC_URI = "ftp://oe.handhelds.org/not_there_as_well.aac" @@ -235,15 +244,13 @@ Some example URLs are as follows: :: Because URL parameters are delimited by semi-colons, this can introduce ambiguity when parsing URLs that also contain semi-colons, - for example: - :: + for example:: SRC_URI = "http://abc123.org/git/?p=gcc/gcc.git;a=snapshot;h=a5dd47" Such URLs should should be modified by replacing semi-colons with '&' - characters: - :: + characters:: SRC_URI = "http://abc123.org/git/?p=gcc/gcc.git&a=snapshot&h=a5dd47" @@ -251,8 +258,7 @@ Some example URLs are as follows: :: In most cases this should work. Treating semi-colons and '&' in queries identically is recommended by the World Wide Web Consortium (W3C). Note that due to the nature of the URL, you may have to - specify the name of the downloaded file as well: - :: + specify the name of the downloaded file as well:: SRC_URI = "http://abc123.org/git/?p=gcc/gcc.git&a=snapshot&h=a5dd47;downloadfilename=myfile.bz2" @@ -321,7 +327,7 @@ The supported parameters are as follows: - *"port":* The port to which the CVS server connects. -Some example URLs are as follows: :: +Some example URLs are as follows:: SRC_URI = "cvs://CVSROOT;module=mymodule;tag=some-version;method=ext" SRC_URI = "cvs://CVSROOT;module=mymodule;date=20060126;localdir=usethat" @@ -363,7 +369,7 @@ The supported parameters are as follows: username is different than the username used in the main URL, which is passed to the subversion command. -Following are three examples using svn: :: +Following are three examples using svn:: SRC_URI = "svn://myrepos/proj1;module=vip;protocol=http;rev=667" SRC_URI = "svn://myrepos/proj1;module=opie;protocol=svn+ssh" @@ -390,6 +396,19 @@ This fetcher supports the following parameters: protocol is "file". You can also use "http", "https", "ssh" and "rsync". + .. note:: + + When ``protocol`` is "ssh", the URL expected in :term:`SRC_URI` differs + from the one that is typically passed to ``git clone`` command and provided + by the Git server to fetch from. For example, the URL returned by GitLab + server for ``mesa`` when cloning over SSH is + ``git@gitlab.freedesktop.org:mesa/mesa.git``, however the expected URL in + :term:`SRC_URI` is the following:: + + SRC_URI = "git://git@gitlab.freedesktop.org/mesa/mesa.git;branch=main;protocol=ssh;..." + + Note the ``:`` character changed for a ``/`` before the path to the project. + - *"nocheckout":* Tells the fetcher to not checkout source code when unpacking when set to "1". Set this option for the URL where there is a custom routine to checkout code. The default is "0". @@ -405,17 +424,17 @@ This fetcher supports the following parameters: - *"nobranch":* Tells the fetcher to not check the SHA validation for the branch when set to "1". The default is "0". Set this option for - the recipe that refers to the commit that is valid for a tag instead - of the branch. + the recipe that refers to the commit that is valid for any namespace + (branch, tag, ...) instead of the branch. - *"bareclone":* Tells the fetcher to clone a bare clone into the destination directory without checking out a working tree. Only the raw Git metadata is provided. This parameter implies the "nocheckout" parameter as well. -- *"branch":* The branch(es) of the Git tree to clone. If unset, this - is assumed to be "master". The number of branch parameters much match - the number of name parameters. +- *"branch":* The branch(es) of the Git tree to clone. Unless + "nobranch" is set to "1", this is a mandatory parameter. The number of + branch parameters must match the number of name parameters. - *"rev":* The revision to use for the checkout. The default is "master". @@ -436,10 +455,35 @@ This fetcher supports the following parameters: parameter implies no branch and only works when the transfer protocol is ``file://``. -Here are some example URLs: :: +Here are some example URLs:: + + SRC_URI = "git://github.com/fronteed/icheck.git;protocol=https;branch=${PV};tag=${PV}" + SRC_URI = "git://github.com/asciidoc/asciidoc-py;protocol=https;branch=main" + SRC_URI = "git://git@gitlab.freedesktop.org/mesa/mesa.git;branch=main;protocol=ssh;..." + +.. note:: - SRC_URI = "git://git.oe.handhelds.org/git/vip.git;tag=version-1" - SRC_URI = "git://git.oe.handhelds.org/git/vip.git;protocol=http" + When using ``git`` as the fetcher of the main source code of your software, + ``S`` should be set accordingly:: + + S = "${WORKDIR}/git" + +.. note:: + + Specifying passwords directly in ``git://`` urls is not supported. + 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 + easy to share metadata without removing passwords. SSH keys, ``~/.netrc`` + and ``~/.ssh/config`` files can be used as alternatives. + +Using tags with the git fetcher may cause surprising behaviour. Bitbake needs to +resolve the tag to a specific revision and to do that, it has to connect to and use +the upstream repository. This is because the revision the tags point at can change and +we've seen cases of this happening in well known public repositories. This can mean +many more network connections than expected and recipes may be reparsed at every build. +Source mirrors will also be bypassed as the upstream repository is the only source +of truth to resolve the revision accurately. For these reasons, whilst the fetcher +can support tags, we recommend being specific about revisions in recipes. .. _gitsm-fetcher: @@ -475,7 +519,7 @@ repository. To use this fetcher, make sure your recipe has proper :term:`SRC_URI`, :term:`SRCREV`, and -:term:`PV` settings. Here is an example: :: +:term:`PV` settings. Here is an example:: SRC_URI = "ccrc://cc.example.org/ccrc;vob=/example_vob;module=/example_module" SRCREV = "EXAMPLE_CLEARCASE_TAG" @@ -484,7 +528,7 @@ To use this fetcher, make sure your recipe has proper The fetcher uses the ``rcleartool`` or ``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, of the ClearCase VOB. This option is required. @@ -497,7 +541,7 @@ Following are options for the ``SRC_URI`` statement: The module and vob options are combined to create the load rule in the view config spec. As an example, consider the vob and module values from the SRC_URI statement at the start of this section. Combining those values - results in the following: :: + results in the following:: load /example_vob/example_module @@ -546,10 +590,10 @@ password if you do not wish to keep those values in a recipe itself. If you choose not to use ``P4CONFIG``, or to explicitly set variables that ``P4CONFIG`` can contain, you can specify the ``P4PORT`` value, which is the server's URL and port number, and you can specify a username and -password directly in your recipe within ``SRC_URI``. +password directly in your recipe within :term:`SRC_URI`. Here is an example that relies on ``P4CONFIG`` to specify the server URL -and port, username, and password, and fetches the Head Revision: :: +and port, username, and password, and fetches the Head Revision:: SRC_URI = "p4://example-depot/main/source/..." SRCREV = "${AUTOREV}" @@ -557,7 +601,7 @@ and port, username, and password, and fetches the Head Revision: :: S = "${WORKDIR}/p4" Here is an example that specifies the server URL and port, username, and -password, and fetches a Revision based on a Label: :: +password, and fetches a Revision based on a Label:: P4PORT = "tcp:p4server.example.net:1666" SRC_URI = "p4://user:passwd@example-depot/main/source/..." @@ -583,7 +627,7 @@ paths locally is desirable, the fetcher supports two parameters: paths locally for the specified location, even in combination with the ``module`` parameter. -Here is an example use of the the ``module`` parameter: :: +Here is an example use of the the ``module`` parameter:: SRC_URI = "p4://user:passwd@example-depot/main;module=source/..." @@ -591,7 +635,7 @@ In this case, the content of the top-level directory ``source/`` will be fetched to ``${P4DIR}``, including the directory itself. The top-level directory will be accesible at ``${P4DIR}/source/``. -Here is an example use of the the ``remotepath`` parameter: :: +Here is an example use of the the ``remotepath`` parameter:: SRC_URI = "p4://user:passwd@example-depot/main;module=source/...;remotepath=keep" @@ -619,11 +663,166 @@ This fetcher supports the following parameters: - *"manifest":* Name of the manifest file (default: ``default.xml``). -Here are some example URLs: :: +Here are some example URLs:: SRC_URI = "repo://REPOROOT;protocol=git;branch=some_branch;manifest=my_manifest.xml" SRC_URI = "repo://REPOROOT;protocol=file;branch=some_branch;manifest=my_manifest.xml" +.. _az-fetcher: + +Az Fetcher (``az://``) +-------------------------- + +This submodule fetches data from an +`Azure Storage account <https://docs.microsoft.com/en-us/azure/storage/>`__ , +it inherits its functionality from the HTTP wget fetcher, but modifies its +behavior to accomodate the usage of a +`Shared Access Signature (SAS) <https://docs.microsoft.com/en-us/azure/storage/common/storage-sas-overview>`__ +for non-public data. + +Such functionality is set by the variable: + +- :term:`AZ_SAS`: The Azure Storage Shared Access Signature provides secure + delegate access to resources, if this variable is set, the Az Fetcher will + use it when fetching artifacts from the cloud. + +You can specify the AZ_SAS variable as shown below:: + + AZ_SAS = "se=2021-01-01&sp=r&sv=2018-11-09&sr=c&skoid=<skoid>&sig=<signature>" + +Here is an example URL:: + + SRC_URI = "az://<azure-storage-account>.blob.core.windows.net/<foo_container>/<bar_file>" + +It can also be used when setting mirrors definitions using the :term:`PREMIRRORS` variable. + +.. _gcp-fetcher: + +GCP Fetcher (``gs://``) +-------------------------- + +This submodule fetches data from a +`Google Cloud Storage Bucket <https://cloud.google.com/storage/docs/buckets>`__. +It uses the `Google Cloud Storage Python Client <https://cloud.google.com/python/docs/reference/storage/latest>`__ +to check the status of objects in the bucket and download them. +The use of the Python client makes it substantially faster than using command +line tools such as gsutil. + +The fetcher requires the Google Cloud Storage Python Client to be installed, along +with the gsutil tool. + +The fetcher requires that the machine has valid credentials for accessing the +chosen bucket. Instructions for authentication can be found in the +`Google Cloud documentation <https://cloud.google.com/docs/authentication/provide-credentials-adc#local-dev>`__. + +If it used from the OpenEmbedded build system, the fetcher can be used for +fetching sstate artifacts from a GCS bucket by specifying the +``SSTATE_MIRRORS`` variable as shown below:: + + SSTATE_MIRRORS ?= "\ + file://.* gs://<bucket name>/PATH \ + " + +The fetcher can also be used in recipes:: + + SRC_URI = "gs://<bucket name>/<foo_container>/<bar_file>" + +However, the checksum of the file should be also be provided:: + + SRC_URI[sha256sum] = "<sha256 string>" + +.. _crate-fetcher: + +Crate Fetcher (``crate://``) +---------------------------- + +This submodule fetches code for +`Rust language "crates" <https://doc.rust-lang.org/reference/glossary.html?highlight=crate#crate>`__ +corresponding to Rust libraries and programs to compile. Such crates are typically shared +on https://crates.io/ but this fetcher supports other crate registries too. + +The format for the :term:`SRC_URI` setting must be:: + + SRC_URI = "crate://REGISTRY/NAME/VERSION" + +Here is an example URL:: + + SRC_URI = "crate://crates.io/glob/0.2.11" + +.. _npm-fetcher: + +NPM Fetcher (``npm://``) +------------------------ + +This submodule fetches source code from an +`NPM <https://en.wikipedia.org/wiki/Npm_(software)>`__ +Javascript package registry. + +The format for the :term:`SRC_URI` setting must be:: + + SRC_URI = "npm://some.registry.url;ParameterA=xxx;ParameterB=xxx;..." + +This fetcher supports the following parameters: + +- *"package":* The NPM package name. This is a mandatory parameter. + +- *"version":* The NPM package version. This is a mandatory parameter. + +- *"downloadfilename":* Specifies the filename used when storing the downloaded file. + +- *"destsuffix":* Specifies the directory to use to unpack the package (default: ``npm``). + +Note that NPM fetcher only fetches the package source itself. The dependencies +can be fetched through the `npmsw-fetcher`_. + +Here is an example URL with both fetchers:: + + SRC_URI = " \ + npm://registry.npmjs.org/;package=cute-files;version=${PV} \ + npmsw://${THISDIR}/${BPN}/npm-shrinkwrap.json \ + " + +See :yocto_docs:`Creating Node Package Manager (NPM) Packages +</dev-manual/packages.html#creating-node-package-manager-npm-packages>` +in the Yocto Project manual for details about using +:yocto_docs:`devtool <https://docs.yoctoproject.org/ref-manual/devtool-reference.html>` +to automatically create a recipe from an NPM URL. + +.. _npmsw-fetcher: + +NPM shrinkwrap Fetcher (``npmsw://``) +------------------------------------- + +This submodule fetches source code from an +`NPM shrinkwrap <https://docs.npmjs.com/cli/v8/commands/npm-shrinkwrap>`__ +description file, which lists the dependencies +of an NPM package while locking their versions. + +The format for the :term:`SRC_URI` setting must be:: + + SRC_URI = "npmsw://some.registry.url;ParameterA=xxx;ParameterB=xxx;..." + +This fetcher supports the following parameters: + +- *"dev":* Set this parameter to ``1`` to install "devDependencies". + +- *"destsuffix":* Specifies the directory to use to unpack the dependencies + (``${S}`` by default). + +Note that the shrinkwrap file can also be provided by the recipe for +the package which has such dependencies, for example:: + + SRC_URI = " \ + npm://registry.npmjs.org/;package=cute-files;version=${PV} \ + npmsw://${THISDIR}/${BPN}/npm-shrinkwrap.json \ + " + +Such a file can automatically be generated using +:yocto_docs:`devtool <https://docs.yoctoproject.org/ref-manual/devtool-reference.html>` +as described in the :yocto_docs:`Creating Node Package Manager (NPM) Packages +</dev-manual/packages.html#creating-node-package-manager-npm-packages>` +section of the Yocto Project. + Other Fetchers -------------- @@ -633,10 +832,10 @@ Fetch submodules also exist for the following: - Mercurial (``hg://``) -- npm (``npm://``) - - OSC (``osc://``) +- S3 (``s3://``) + - Secure FTP (``sftp://``) - Secure Shell (``ssh://``) @@ -649,4 +848,4 @@ submodules. However, you might find the code helpful and readable. Auto Revisions ============== -We need to document ``AUTOREV`` and ``SRCREV_FORMAT`` here. +We need to document ``AUTOREV`` and :term:`SRCREV_FORMAT` here. diff --git a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-hello.rst b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-hello.rst index e3fd321588..654196ca24 100644 --- a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-hello.rst +++ b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-hello.rst @@ -18,28 +18,32 @@ it. Obtaining BitBake ================= -See the :ref:`bitbake-user-manual/bitbake-user-manual-hello:obtaining bitbake` section for +See the :ref:`bitbake-user-manual/bitbake-user-manual-intro:obtaining bitbake` section for information on how to obtain BitBake. Once you have the source code on -your machine, the BitBake directory appears as follows: :: +your machine, the BitBake directory appears as follows:: $ ls -al - total 100 - drwxrwxr-x. 9 wmat wmat 4096 Jan 31 13:44 . - drwxrwxr-x. 3 wmat wmat 4096 Feb 4 10:45 .. - -rw-rw-r--. 1 wmat wmat 365 Nov 26 04:55 AUTHORS - drwxrwxr-x. 2 wmat wmat 4096 Nov 26 04:55 bin - drwxrwxr-x. 4 wmat wmat 4096 Jan 31 13:44 build - -rw-rw-r--. 1 wmat wmat 16501 Nov 26 04:55 ChangeLog - drwxrwxr-x. 2 wmat wmat 4096 Nov 26 04:55 classes - drwxrwxr-x. 2 wmat wmat 4096 Nov 26 04:55 conf - drwxrwxr-x. 3 wmat wmat 4096 Nov 26 04:55 contrib - -rw-rw-r--. 1 wmat wmat 17987 Nov 26 04:55 COPYING - drwxrwxr-x. 3 wmat wmat 4096 Nov 26 04:55 doc - -rw-rw-r--. 1 wmat wmat 69 Nov 26 04:55 .gitignore - -rw-rw-r--. 1 wmat wmat 849 Nov 26 04:55 HEADER - drwxrwxr-x. 5 wmat wmat 4096 Jan 31 13:44 lib - -rw-rw-r--. 1 wmat wmat 195 Nov 26 04:55 MANIFEST.in - -rw-rw-r--. 1 wmat wmat 2887 Nov 26 04:55 TODO + total 108 + drwxr-xr-x 9 fawkh 10000 4096 feb 24 12:10 . + drwx------ 36 fawkh 10000 4096 mar 2 17:00 .. + -rw-r--r-- 1 fawkh 10000 365 feb 24 12:10 AUTHORS + drwxr-xr-x 2 fawkh 10000 4096 feb 24 12:10 bin + -rw-r--r-- 1 fawkh 10000 16501 feb 24 12:10 ChangeLog + drwxr-xr-x 2 fawkh 10000 4096 feb 24 12:10 classes + drwxr-xr-x 2 fawkh 10000 4096 feb 24 12:10 conf + drwxr-xr-x 5 fawkh 10000 4096 feb 24 12:10 contrib + drwxr-xr-x 6 fawkh 10000 4096 feb 24 12:10 doc + drwxr-xr-x 8 fawkh 10000 4096 mar 2 16:26 .git + -rw-r--r-- 1 fawkh 10000 31 feb 24 12:10 .gitattributes + -rw-r--r-- 1 fawkh 10000 392 feb 24 12:10 .gitignore + drwxr-xr-x 13 fawkh 10000 4096 feb 24 12:11 lib + -rw-r--r-- 1 fawkh 10000 1224 feb 24 12:10 LICENSE + -rw-r--r-- 1 fawkh 10000 15394 feb 24 12:10 LICENSE.GPL-2.0-only + -rw-r--r-- 1 fawkh 10000 1286 feb 24 12:10 LICENSE.MIT + -rw-r--r-- 1 fawkh 10000 229 feb 24 12:10 MANIFEST.in + -rw-r--r-- 1 fawkh 10000 2413 feb 24 12:10 README + -rw-r--r-- 1 fawkh 10000 43 feb 24 12:10 toaster-requirements.txt + -rw-r--r-- 1 fawkh 10000 2887 feb 24 12:10 TODO At this point, you should have BitBake cloned to a directory that matches the previous listing except for dates and user names. @@ -49,10 +53,10 @@ Setting Up the BitBake Environment First, you need to be sure that you can run BitBake. Set your working directory to where your local BitBake files are and run the following -command: :: +command:: $ ./bin/bitbake --version - BitBake Build Tool Core version 1.23.0, bitbake version 1.23.0 + BitBake Build Tool Core version 2.3.1 The console output tells you what version you are running. @@ -61,14 +65,14 @@ The recommended method to run BitBake is from a directory of your choice. To be able to run BitBake from any directory, you need to add the executable binary to your binary to your shell's environment ``PATH`` variable. First, look at your current ``PATH`` variable by -entering the following: :: +entering the following:: $ echo $PATH Next, add the directory location for the BitBake binary to the ``PATH``. Here is an example that adds the ``/home/scott-lenovo/bitbake/bin`` directory to the front of the -``PATH`` variable: :: +``PATH`` variable:: $ export PATH=/home/scott-lenovo/bitbake/bin:$PATH @@ -99,7 +103,7 @@ discussion mailing list about the BitBake build tool. This example was inspired by and drew heavily from `Mailing List post - The BitBake equivalent of "Hello, World!" - <http://www.mail-archive.com/yocto@yoctoproject.org/msg09379.html>`_. + <https://www.mail-archive.com/yocto@yoctoproject.org/msg09379.html>`_. As stated earlier, the goal of this example is to eventually compile "Hello World". However, it is unknown what BitBake needs and what you @@ -116,7 +120,7 @@ Following is the complete "Hello World" example. #. **Create a Project Directory:** First, set up a directory for the "Hello World" project. Here is how you can do so in your home - directory: :: + directory:: $ mkdir ~/hello $ cd ~/hello @@ -127,41 +131,26 @@ Following is the complete "Hello World" example. directory is a good way to isolate your project. #. **Run BitBake:** At this point, you have nothing but a project - directory. Run the ``bitbake`` command and see what it does: :: + directory. Run the ``bitbake`` command and see what it does:: $ bitbake - The BBPATH variable is not set and bitbake did not - find a conf/bblayers.conf file in the expected location. + ERROR: The BBPATH variable is not set and bitbake did not find a conf/bblayers.conf file in the expected location. Maybe you accidentally invoked bitbake from the wrong directory? - DEBUG: Removed the following variables from the environment: - GNOME_DESKTOP_SESSION_ID, XDG_CURRENT_DESKTOP, - GNOME_KEYRING_CONTROL, DISPLAY, SSH_AGENT_PID, LANG, no_proxy, - XDG_SESSION_PATH, XAUTHORITY, SESSION_MANAGER, SHLVL, - MANDATORY_PATH, COMPIZ_CONFIG_PROFILE, WINDOWID, EDITOR, - GPG_AGENT_INFO, SSH_AUTH_SOCK, GDMSESSION, GNOME_KEYRING_PID, - XDG_SEAT_PATH, XDG_CONFIG_DIRS, LESSOPEN, DBUS_SESSION_BUS_ADDRESS, - _, XDG_SESSION_COOKIE, DESKTOP_SESSION, LESSCLOSE, DEFAULTS_PATH, - UBUNTU_MENUPROXY, OLDPWD, XDG_DATA_DIRS, COLORTERM, LS_COLORS - - The majority of this output is specific to environment variables that - are not directly relevant to BitBake. However, the very first - message regarding the ``BBPATH`` variable and the - ``conf/bblayers.conf`` file is relevant. When you run BitBake, it begins looking for metadata files. The :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 + to look for those files. :term:`BBPATH` is not set and you need to set + it. Without :term:`BBPATH`, BitBake cannot find any configuration files (``.conf``) or recipe files (``.bb``) at all. BitBake also cannot 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 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 - ``BBPATH`` variable: :: + :term:`BBPATH` variable:: $ BBPATH="projectdirectory" $ export BBPATH @@ -175,24 +164,18 @@ Following is the complete "Hello World" example. ("~") character as BitBake does not expand that character as the shell would. -#. **Run BitBake:** Now that you have ``BBPATH`` defined, run the - ``bitbake`` command again: :: +#. **Run BitBake:** Now that you have :term:`BBPATH` defined, run the + ``bitbake`` command again:: $ bitbake - ERROR: Traceback (most recent call last): - File "/home/scott-lenovo/bitbake/lib/bb/cookerdata.py", line 163, in wrapped - return func(fn, *args) - File "/home/scott-lenovo/bitbake/lib/bb/cookerdata.py", line 173, in parse_config_file - return bb.parse.handle(fn, data, include) - File "/home/scott-lenovo/bitbake/lib/bb/parse/__init__.py", line 99, in handle - return h['handle'](fn, data, include) - File "/home/scott-lenovo/bitbake/lib/bb/parse/parse_py/ConfHandler.py", line 120, in handle - abs_fn = resolve_file(fn, data) - File "/home/scott-lenovo/bitbake/lib/bb/parse/__init__.py", line 117, in resolve_file - raise IOError("file %s not found in %s" % (fn, bbpath)) - IOError: file conf/bitbake.conf not found in /home/scott-lenovo/hello - - ERROR: Unable to parse conf/bitbake.conf: file conf/bitbake.conf not found in /home/scott-lenovo/hello + ERROR: Unable to parse /home/scott-lenovo/bitbake/lib/bb/parse/__init__.py + Traceback (most recent call last): + File "/home/scott-lenovo/bitbake/lib/bb/parse/__init__.py", line 127, in resolve_file(fn='conf/bitbake.conf', d=<bb.data_smart.DataSmart object at 0x7f22919a3df0>): + if not newfn: + > raise IOError(errno.ENOENT, "file %s not found in %s" % (fn, bbpath)) + fn = newfn + FileNotFoundError: [Errno 2] file conf/bitbake.conf not found in <projectdirectory> + This sample output shows that BitBake could not find the ``conf/bitbake.conf`` file in the project directory. This file is @@ -205,18 +188,18 @@ 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. + https://git.openembedded.org/bitbake/tree/conf/bitbake.conf. Use the following commands to create the ``conf`` directory in the - project directory: :: + project directory:: $ mkdir conf From within the ``conf`` directory, use some editor to create the ``bitbake.conf`` so that it contains - the following: :: + the following:: - PN = "${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE', False),d)[0] or 'defaultpkgname'}" + PN = "${@bb.parse.vars_from_file(d.getVar('FILE', False),d)[0] or 'defaultpkgname'}" TMPDIR = "${TOPDIR}/tmp" CACHE = "${TMPDIR}/cache" @@ -226,12 +209,12 @@ Following is the complete "Hello World" example. .. note:: - Without a value for PN , the variables STAMP , T , and B , prevent more - than one recipe from working. You can fix this by either setting PN to + Without a value for :term:`PN`, the variables :term:`STAMP`, :term:`T`, and :term:`B`, prevent more + than one recipe from working. You can fix this by either setting :term:`PN` to have a value similar to what OpenEmbedded and BitBake use in the default - bitbake.conf file (see previous example). Or, by manually updating each - recipe to set PN . You will also need to include PN as part of the STAMP - , T , and B variable definitions in the local.conf file. + ``bitbake.conf`` file (see previous example). Or, by manually updating each + recipe to set :term:`PN`. You will also need to include :term:`PN` as part of the :term:`STAMP`, + :term:`T`, and :term:`B` variable definitions in the ``local.conf`` file. The ``TMPDIR`` variable establishes a directory that BitBake uses for build output and intermediate files other than the cached @@ -251,21 +234,17 @@ Following is the complete "Hello World" example. glossary. #. **Run BitBake:** After making sure that the ``conf/bitbake.conf`` file - exists, you can run the ``bitbake`` command again: :: + exists, you can run the ``bitbake`` command again:: $ bitbake - ERROR: Traceback (most recent call last): - File "/home/scott-lenovo/bitbake/lib/bb/cookerdata.py", line 163, in wrapped - return func(fn, *args) - File "/home/scott-lenovo/bitbake/lib/bb/cookerdata.py", line 177, in _inherit - bb.parse.BBHandler.inherit(bbclass, "configuration INHERITs", 0, data) - File "/home/scott-lenovo/bitbake/lib/bb/parse/parse_py/BBHandler.py", line 92, in inherit - include(fn, file, lineno, d, "inherit") - File "/home/scott-lenovo/bitbake/lib/bb/parse/parse_py/ConfHandler.py", line 100, in include - raise ParseError("Could not %(error_out)s file %(fn)s" % vars(), oldfn, lineno) - ParseError: ParseError in configuration INHERITs: Could not inherit file classes/base.bbclass - - ERROR: Unable to parse base: ParseError in configuration INHERITs: Could not inherit file classes/base.bbclass + ERROR: Unable to parse /home/scott-lenovo/bitbake/lib/bb/parse/parse_py/BBHandler.py + Traceback (most recent call last): + File "/home/scott-lenovo/bitbake/lib/bb/parse/parse_py/BBHandler.py", line 67, in inherit(files=['base'], fn='configuration INHERITs', lineno=0, d=<bb.data_smart.DataSmart object at 0x7fab6815edf0>): + if not os.path.exists(file): + > raise ParseError("Could not inherit file %s" % (file), fn, lineno) + + bb.parse.ParseError: ParseError in configuration INHERITs: Could not inherit file classes/base.bbclass + In the sample output, BitBake could not find the ``classes/base.bbclass`` file. You need @@ -278,20 +257,23 @@ Following is the complete "Hello World" example. in the ``classes`` directory of the project (i.e ``hello/classes`` in this example). - Create the ``classes`` directory as follows: :: + Create the ``classes`` directory as follows:: $ cd $HOME/hello $ mkdir classes Move to the ``classes`` directory and then create the - ``base.bbclass`` file by inserting this single line: addtask build + ``base.bbclass`` file by inserting this single line:: + + addtask build + The minimal task that BitBake runs is the ``do_build`` task. This is all the example needs in order to build the project. Of course, the ``base.bbclass`` can have much more depending on which build environments BitBake is supporting. #. **Run BitBake:** After making sure that the ``classes/base.bbclass`` - file exists, you can run the ``bitbake`` command again: :: + file exists, you can run the ``bitbake`` command again:: $ bitbake Nothing to do. Use 'bitbake world' to build everything, or run 'bitbake --help' for usage information. @@ -314,7 +296,7 @@ Following is the complete "Hello World" example. Minimally, you need a recipe file and a layer configuration file in your layer. The configuration file needs to be in the ``conf`` directory inside the layer. Use these commands to set up the layer - and the ``conf`` directory: :: + and the ``conf`` directory:: $ cd $HOME $ mkdir mylayer @@ -322,20 +304,29 @@ Following is the complete "Hello World" example. $ mkdir conf Move to the ``conf`` directory and create a ``layer.conf`` file that has the - following: :: + following:: BBPATH .= ":${LAYERDIR}" - BBFILES += "${LAYERDIR}/\*.bb" + BBFILES += "${LAYERDIR}/*.bb" BBFILE_COLLECTIONS += "mylayer" - `BBFILE_PATTERN_mylayer := "^${LAYERDIR_RE}/" + BBFILE_PATTERN_mylayer := "^${LAYERDIR_RE}/" + LAYERSERIES_CORENAMES = "hello_world_example" + LAYERSERIES_COMPAT_mylayer = "hello_world_example" For information on these variables, click on :term:`BBFILES`, - :term:`LAYERDIR`, :term:`BBFILE_COLLECTIONS` or :term:`BBFILE_PATTERN_mylayer <BBFILE_PATTERN>` - to go to the definitions in the glossary. + :term:`LAYERDIR`, :term:`BBFILE_COLLECTIONS`, :term:`BBFILE_PATTERN_mylayer <BBFILE_PATTERN>` + or :term:`LAYERSERIES_COMPAT` to go to the definitions in the glossary. + + .. note:: + + We are setting both ``LAYERSERIES_CORENAMES`` and :term:`LAYERSERIES_COMPAT` in this particular case, because we + are using bitbake without OpenEmbedded. + You should usually just use :term:`LAYERSERIES_COMPAT` to specify the OE-Core versions for which your layer + is compatible, and add the meta-openembedded layer to your project. 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: :: + ``printhello.bb`` that has the following:: DESCRIPTION = "Prints Hello World" PN = 'printhello' @@ -356,7 +347,7 @@ Following is the complete "Hello World" example. follow the links to the glossary. #. **Run BitBake With a Target:** Now that a BitBake target exists, run - the command and provide that target: :: + the command and provide that target:: $ cd $HOME/hello $ bitbake printhello @@ -376,7 +367,7 @@ Following is the complete "Hello World" example. ``hello/conf`` for this example). Set your working directory to the ``hello/conf`` directory and then - create the ``bblayers.conf`` file so that it contains the following: :: + create the ``bblayers.conf`` file so that it contains the following:: BBLAYERS ?= " \ /home/<you>/mylayer \ @@ -386,15 +377,17 @@ Following is the complete "Hello World" example. #. **Run BitBake With a Target:** Now that you have supplied the ``bblayers.conf`` file, run the ``bitbake`` command and provide the - target: :: + target:: $ bitbake printhello + Loading cache: 100% | + Loaded 0 entries from dependency cache. Parsing recipes: 100% |##################################################################################| - Time: 00:00:00 Parsing of 1 .bb files complete (0 cached, 1 parsed). 1 targets, 0 skipped, 0 masked, 0 errors. NOTE: Resolving any missing task queue dependencies - NOTE: Preparing RunQueue - NOTE: Executing RunQueue Tasks + Initialising tasks: 100% |###############################################################################| + NOTE: No setscene tasks + NOTE: Executing Tasks ******************** * * * Hello, World! * diff --git a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-intro.rst b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-intro.rst index 6f9d392935..35ffb88b02 100644 --- a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-intro.rst +++ b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-intro.rst @@ -27,7 +27,7 @@ Linux software stacks using a task-oriented approach. Conceptually, BitBake is similar to GNU Make in some regards but has significant differences: -- BitBake executes tasks according to provided metadata that builds up +- BitBake executes tasks according to the provided metadata that builds up the tasks. Metadata is stored in recipe (``.bb``) and related recipe "append" (``.bbappend``) files, configuration (``.conf``) and underlying include (``.inc``) files, and in class (``.bbclass``) @@ -60,11 +60,10 @@ member Chris Larson split the project into two distinct pieces: - OpenEmbedded, a metadata set utilized by BitBake Today, BitBake is the primary basis of the -`OpenEmbedded <http://www.openembedded.org/>`__ project, which is being -used to build and maintain Linux distributions such as the `Angstrom -Distribution <http://www.angstrom-distribution.org/>`__, and which is -also being used as the build tool for Linux projects such as the `Yocto -Project <http://www.yoctoproject.org>`__. +`OpenEmbedded <https://www.openembedded.org/>`__ project, which is being +used to build and maintain Linux distributions such as the `Poky +Reference Distribution <https://www.yoctoproject.org/software-item/poky/>`__, +developed under the umbrella of the `Yocto Project <https://www.yoctoproject.org>`__. Prior to BitBake, no other build tool adequately met the needs of an aspiring embedded Linux distribution. All of the build systems used by @@ -248,13 +247,13 @@ underlying, similarly-named recipe files. When you name an append file, you can use the "``%``" wildcard character to allow for matching recipe names. For example, suppose you have an -append file named as follows: :: +append file named as follows:: busybox_1.21.%.bbappend That append file would match any ``busybox_1.21.``\ x\ ``.bb`` version of the recipe. So, -the append file would match the following recipe names: :: +the append file would match the following recipe names:: busybox_1.21.1.bb busybox_1.21.2.bb @@ -290,7 +289,7 @@ You can obtain BitBake several different ways: are using. The metadata is generally backwards compatible but not forward compatible. - Here is an example that clones the BitBake repository: :: + Here is an example that clones the BitBake repository:: $ git clone git://git.openembedded.org/bitbake @@ -298,7 +297,7 @@ You can obtain BitBake several different ways: Git repository into a directory called ``bitbake``. Alternatively, you can designate a directory after the ``git clone`` command if you want to call the new directory something other than ``bitbake``. Here - is an example that names the directory ``bbdev``: :: + is an example that names the directory ``bbdev``:: $ git clone git://git.openembedded.org/bitbake bbdev @@ -317,9 +316,9 @@ You can obtain BitBake several different ways: method for getting BitBake. Cloning the repository makes it easier to update as patches are added to the stable branches. - The following example downloads a snapshot of BitBake version 1.17.0: :: + The following example downloads a snapshot of BitBake version 1.17.0:: - $ wget http://git.openembedded.org/bitbake/snapshot/bitbake-1.17.0.tar.gz + $ wget https://git.openembedded.org/bitbake/snapshot/bitbake-1.17.0.tar.gz $ tar zxpvf bitbake-1.17.0.tar.gz After extraction of the tarball using @@ -347,7 +346,7 @@ execution examples. Usage and syntax ---------------- -Following is the usage and syntax for BitBake: :: +Following is the usage and syntax for BitBake:: $ bitbake -h Usage: bitbake [options] [recipename/target recipe:do_task ...] @@ -417,8 +416,8 @@ Following is the usage and syntax for BitBake: :: -l DEBUG_DOMAINS, --log-domains=DEBUG_DOMAINS Show debug logging for the specified logging domains -P, --profile Profile the command and save reports. - -u UI, --ui=UI The user interface to use (knotty, ncurses or taskexp - - default knotty). + -u UI, --ui=UI The user interface to use (knotty, ncurses, taskexp or + teamcity - default knotty). --token=XMLRPCTOKEN Specify the connection token to be used when connecting to a remote server. --revisions-changed Set the exit code depending on whether upstream @@ -433,6 +432,9 @@ Following is the usage and syntax for BitBake: :: Environment variable BB_SERVER_TIMEOUT. --no-setscene Do not run any setscene tasks. sstate will be ignored and everything needed, built. + --skip-setscene Skip setscene tasks if they would be executed. Tasks + previously restored from sstate will be kept, unlike + --no-setscene --setscene-only Only run setscene tasks, don't run any real tasks. --remote-server=REMOTE_SERVER Connect to the specified server. @@ -469,11 +471,11 @@ default task, which is "build". BitBake obeys inter-task dependencies when doing so. The following command runs the build task, which is the default task, on -the ``foo_1.0.bb`` recipe file: :: +the ``foo_1.0.bb`` recipe file:: $ bitbake -b foo_1.0.bb -The following command runs the clean task on the ``foo.bb`` recipe file: :: +The following command runs the clean task on the ``foo.bb`` recipe file:: $ bitbake -b foo.bb -c clean @@ -497,13 +499,13 @@ functionality, or when there are multiple versions of a recipe. The ``bitbake`` command, when not using "--buildfile" or "-b" only accepts a "PROVIDES". You cannot provide anything else. By default, a recipe file generally "PROVIDES" its "packagename" as shown in the -following example: :: +following example:: $ bitbake foo This next example "PROVIDES" the package name and also uses the "-c" option to tell BitBake to just -execute the ``do_clean`` task: :: +execute the ``do_clean`` task:: $ bitbake -c clean foo @@ -514,7 +516,7 @@ The BitBake command line supports specifying different tasks for individual targets when you specify multiple targets. For example, suppose you had two targets (or recipes) ``myfirstrecipe`` and ``mysecondrecipe`` and you needed BitBake to run ``taskA`` for the first -recipe and ``taskB`` for the second recipe: :: +recipe and ``taskB`` for the second recipe:: $ bitbake myfirstrecipe:do_taskA mysecondrecipe:do_taskB @@ -534,13 +536,13 @@ current working directory: - ``pn-buildlist``: Shows a simple list of targets that are to be built. -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 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 -omits depends common in OpenEmbedded from the graph: :: +omits depends common in OpenEmbedded from the graph:: $ bitbake -g foo @@ -564,7 +566,7 @@ for two separate targets: .. image:: figures/bb_multiconfig_files.png :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, using the configuration file as a pre-configuration file is not possible unless it is located in the current working directory. @@ -582,17 +584,17 @@ accomplished by setting the configuration files for ``target1`` and ``target2`` defined in the build directory. The following statement in the ``local.conf`` file both enables BitBake to perform multiple configuration builds and specifies -the two extra multiconfigs: :: +the two extra multiconfigs:: BBMULTICONFIG = "target1 target2" Once the target configuration files are in place and BitBake has been enabled to perform multiple configuration builds, use the following -command form to start the builds: :: +command form to start the builds:: $ bitbake [mc:multiconfigname:]target [[[mc:multiconfigname:]target] ... ] -Here is an example for two extra multiconfigs: ``target1`` and ``target2``: :: +Here is an example for two extra multiconfigs: ``target1`` and ``target2``:: $ bitbake mc::target mc:target1:target mc:target2:target @@ -613,12 +615,12 @@ multiconfig. To enable dependencies in a multiple configuration build, you must declare the dependencies in the recipe using the following statement -form: :: +form:: task_or_package[mcdepends] = "mc:from_multiconfig:to_multiconfig:recipe_name:task_on_which_to_depend" To better show how to use this statement, consider an example with two -multiconfigs: ``target1`` and ``target2``: :: +multiconfigs: ``target1`` and ``target2``:: image_task[mcdepends] = "mc:target1:target2:image2:rootfs_task" @@ -629,7 +631,7 @@ completion of the rootfs_task used to build out image2, which is associated with the "target2" multiconfig. Once you set up this dependency, you can build the "target1" multiconfig -using a BitBake command as follows: :: +using a BitBake command as follows:: $ bitbake mc:target1:image1 @@ -639,7 +641,7 @@ the ``rootfs_task`` for the "target2" multiconfig build. Having a recipe depend on the root filesystem of another build might not seem that useful. Consider this change to the statement in the image1 -recipe: :: +recipe:: image_task[mcdepends] = "mc:target1:target2:image2:image_task" diff --git a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst index 7ea68ade72..58975f4c88 100644 --- a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst +++ b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst @@ -26,7 +26,7 @@ assignment. :: VARIABLE = "value" As expected, if you include leading or -trailing spaces as part of an assignment, the spaces are retained: :: +trailing spaces as part of an assignment, the spaces are retained:: VARIABLE = " value" VARIABLE = "value " @@ -40,7 +40,7 @@ blank space (i.e. these are not the same values). :: You can use single quotes instead of double quotes when setting a variable's value. Doing so allows you to use values that contain the -double quote character: :: +double quote character:: VARIABLE = 'I have a " in my value' @@ -77,7 +77,7 @@ occurs, you can use BitBake to check the actual value of the suspect variable. You can make these checks for both configuration and recipe level changes: -- For configuration changes, use the following: :: +- For configuration changes, use the following:: $ bitbake -e @@ -91,9 +91,10 @@ level changes: Variables that are exported to the environment are preceded by the string "export" in the command's output. -- For recipe changes, use the following: :: +- To find changes to a given variable in a specific recipe, use the + following:: - $ bitbake recipe -e \| grep VARIABLE=" + $ bitbake recipename -e | grep VARIABLENAME=\" This command checks to see if the variable actually makes it into a specific recipe. @@ -103,20 +104,20 @@ Line Joining Outside of :ref:`functions <bitbake-user-manual/bitbake-user-manual-metadata:functions>`, BitBake joins any line ending in -a backslash character ("\") with the following line before parsing -statements. The most common use for the "\" character is to split -variable assignments over multiple lines, as in the following example: :: +a backslash character ("\\") with the following line before parsing +statements. The most common use for the "\\" character is to split +variable assignments over multiple lines, as in the following example:: FOO = "bar \ baz \ qaz" -Both the "\" character and the newline +Both the "\\" character and the newline character that follow it are removed when joining lines. Thus, no newline characters end up in the value of ``FOO``. Consider this additional example where the two assignments both assign -"barbaz" to ``FOO``: :: +"barbaz" to ``FOO``:: FOO = "barbaz" FOO = "bar\ @@ -124,7 +125,7 @@ Consider this additional example where the two assignments both assign .. note:: - BitBake does not interpret escape sequences like "\n" in variable + BitBake does not interpret escape sequences like "\\n" in variable values. For these to have an effect, the value must be passed to some utility that interprets escape sequences, such as ``printf`` or ``echo -n``. @@ -149,7 +150,7 @@ The "=" operator does not immediately expand variable references in the right-hand side. Instead, expansion is deferred until the variable assigned to is actually used. The result depends on the current values of the referenced variables. The following example should clarify this -behavior: :: +behavior:: A = "${B} baz" B = "${C} bar" @@ -158,7 +159,7 @@ behavior: :: C = "qux" *At this point, ${A} equals "qux bar baz"* B = "norf" - *At this point, ${A} equals "norf baz"\* + *At this point, ${A} equals "norf baz"* Contrast this behavior with the :ref:`bitbake-user-manual/bitbake-user-manual-metadata:immediate variable @@ -177,7 +178,7 @@ Setting a default value (?=) You can use the "?=" operator to achieve a "softer" assignment for a variable. This type of assignment allows you to define a variable if it is undefined when the statement is parsed, but to leave the value alone -if the variable has a value. Here is an example: :: +if the variable has a value. Here is an example:: A ?= "aval" @@ -194,28 +195,51 @@ value. However, if ``A`` is not set, the variable is set to "aval". Setting a weak default value (??=) ---------------------------------- -It is possible to use a "weaker" assignment than in the previous section -by using the "??=" operator. This assignment behaves identical to "?=" -except that the assignment is made at the end of the parsing process -rather than immediately. Consequently, when multiple "??=" assignments -exist, the last one is used. Also, any "=" or "?=" assignment will -override the value set with "??=". Here is an example: :: +The weak default value of a variable is the value which that variable +will expand to if no value has been assigned to it via any of the other +assignment operators. The "??=" operator takes effect immediately, replacing +any previously defined weak default value. Here is an example:: - A ??= "somevalue" - A ??= "someothervalue" + W ??= "x" + A := "${W}" # Immediate variable expansion + W ??= "y" + B := "${W}" # Immediate variable expansion + W ??= "z" + C = "${W}" + W ?= "i" -If ``A`` is set before the above statements are -parsed, the variable retains its value. If ``A`` is not set, the -variable is set to "someothervalue". +After parsing we will have:: -Again, this assignment is a "lazy" or "weak" assignment because it does -not occur until the end of the parsing process. + A = "x" + B = "y" + C = "i" + W = "i" + +Appending and prepending non-override style will not substitute the weak +default value, which means that after parsing:: + + W ??= "x" + W += "y" + +we will have:: + + W = " y" + +On the other hand, override-style appends/prepends/removes are applied after +any active weak default value has been substituted:: + + W ??= "x" + W:append = "y" + +After parsing we will have:: + + W = "xy" Immediate variable expansion (:=) --------------------------------- The ":=" operator results in a variable's contents being expanded -immediately, rather than when the variable is actually used: :: +immediately, rather than when the variable is actually used:: T = "123" A := "test ${T}" @@ -225,7 +249,7 @@ immediately, rather than when the variable is actually used: :: C := "${C}append" 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 preserved as is during (immediate)expansion. This is in contrast to GNU Make, where undefined variables expand to nothing. The variable ``C`` @@ -241,14 +265,14 @@ the "+=" and "=+" operators. These operators insert a space between the current value and prepended or appended value. These operators take immediate effect during parsing. Here are some -examples: :: +examples:: B = "bval" B += "additionaldata" C = "cval" C =+ "test" -The variable ``B`` contains "bval additionaldata" and ``C`` contains "test +The variable :term:`B` contains "bval additionaldata" and ``C`` contains "test cval". .. _appending-and-prepending-without-spaces: @@ -260,14 +284,14 @@ If you want to append or prepend values without an inserted space, use the ".=" and "=." operators. These operators take immediate effect during parsing. Here are some -examples: :: +examples:: B = "bval" B .= "additionaldata" C = "cval" C =. "test" -The variable ``B`` contains "bvaladditionaldata" and ``C`` contains +The variable :term:`B` contains "bvaladditionaldata" and ``C`` contains "testcval". Appending and Prepending (Override Style Syntax) @@ -278,16 +302,16 @@ style syntax. When you use this syntax, no spaces are inserted. These operators differ from the ":=", ".=", "=.", "+=", and "=+" operators in that their effects are applied at variable expansion time -rather than being immediately applied. Here are some examples: :: +rather than being immediately applied. Here are some examples:: B = "bval" - B_append = " additional data" + B:append = " additional data" C = "cval" - C_prepend = "additional data " + C:prepend = "additional data " 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". The variable ``D`` becomes "dvaladditional data". @@ -295,6 +319,10 @@ The variable ``D`` becomes "dvaladditional data". You must control all spacing when you use the override syntax. +.. note:: + + The overrides are applied in this order, ":append", ":prepend", ":remove". + It is also possible to append and prepend to shell functions and BitBake-style Python functions. See the ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:shell functions`" and ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:bitbake-style python functions`" sections for examples. @@ -306,16 +334,17 @@ Removal (Override Style Syntax) You can remove values from lists using the removal override style syntax. Specifying a value for removal causes all occurrences of that -value to be removed from the variable. +value to be removed from the variable. Unlike ":append" and ":prepend", +there is no need to add a leading or trailing space to the value. When you use this syntax, BitBake expects one or more strings. -Surrounding spaces and spacing are preserved. Here is an example: :: +Surrounding spaces and spacing are preserved. Here is an example:: FOO = "123 456 789 123456 123 456 123 456" - FOO_remove = "123" - FOO_remove = "456" + FOO:remove = "123" + FOO:remove = "456" FOO2 = " abc def ghi abcdef abc def abc def def" - FOO2_remove = "\ + FOO2:remove = "\ def \ abc \ ghi \ @@ -324,40 +353,62 @@ Surrounding spaces and spacing are preserved. Here is an example: :: The variable ``FOO`` becomes " 789 123456 " and ``FOO2`` becomes " abcdef ". -Like "_append" and "_prepend", "_remove" is applied at variable +Like ":append" and ":prepend", ":remove" is applied at variable expansion time. +.. note:: + + The overrides are applied in this order, ":append", ":prepend", ":remove". + This implies it is not possible to re-append previously removed strings. + However, one can undo a ":remove" by using an intermediate variable whose + content is passed to the ":remove" so that modifying the intermediate + variable equals to keeping the string in:: + + FOOREMOVE = "123 456 789" + FOO:remove = "${FOOREMOVE}" + ... + FOOREMOVE = "123 789" + + This expands to ``FOO:remove = "123 789"``. + +.. note:: + + Override application order may not match variable parse history, i.e. + the output of ``bitbake -e`` may contain ":remove" before ":append", + but the result will be removed string, because ":remove" is handled + last. + Override Style Operation Advantages ----------------------------------- -An advantage of the override style operations "_append", "_prepend", and -"_remove" as compared to the "+=" and "=+" operators is that the +An advantage of the override style operations ":append", ":prepend", and +":remove" as compared to the "+=" and "=+" operators is that the override style operators provide guaranteed operations. For example, consider a class ``foo.bbclass`` that needs to add the value "val" to -the variable ``FOO``, and a recipe that uses ``foo.bbclass`` as follows: :: +the variable ``FOO``, and a recipe that uses ``foo.bbclass`` as follows:: inherit foo FOO = "initial" If ``foo.bbclass`` uses the "+=" operator, as follows, then the final value of ``FOO`` will be "initial", which is -not what is desired: :: +not what is desired:: FOO += "val" If, on the other hand, ``foo.bbclass`` -uses the "_append" operator, then the final value of ``FOO`` will be -"initial val", as intended: :: +uses the ":append" operator, then the final value of ``FOO`` will be +"initial val", as intended:: - FOO_append = " val" + FOO:append = " val" .. note:: - It is never necessary to use "+=" together with "_append". The following - sequence of assignments appends "barbaz" to FOO: :: + It is never necessary to use "+=" together with ":append". The following + sequence of assignments appends "barbaz" to FOO:: - FOO_append = "bar" - FOO_append = "baz" + FOO:append = "bar" + FOO:append = "baz" The only effect of changing the second assignment in the previous @@ -378,10 +429,10 @@ You can find more out about variable flags in general in the You can define, append, and prepend values to variable flags. All the standard syntax operations previously mentioned work for variable flags -except for override style syntax (i.e. "_prepend", "_append", and -"_remove"). +except for override style syntax (i.e. ":prepend", ":append", and +":remove"). -Here are some examples showing how to set variable flags: :: +Here are some examples showing how to set variable flags:: FOO[a] = "abc" FOO[b] = "123" @@ -393,15 +444,21 @@ respectively. The ``[a]`` flag becomes "abc 456". No need exists to pre-define variable flags. You can simply start using them. One extremely common application is to attach some brief -documentation to a BitBake variable as follows: :: +documentation to a BitBake variable as follows:: CACHE[doc] = "The directory holding the cache of the metadata." +.. note:: + + Variable flag names starting with an underscore (``_``) character + are allowed but are ignored by ``d.getVarFlags("VAR")`` + in Python code. Such flag names are used internally by BitBake. + Inline Python Variable Expansion -------------------------------- You can use inline Python variable expansion to set variables. Here is -an example: :: +an example:: DATE = "${@time.strftime('%Y%m%d',time.gmtime())}" @@ -410,21 +467,21 @@ This example results in the ``DATE`` variable being set to the current date. Probably the most common use of this feature is to extract the value of variables from BitBake's internal data dictionary, ``d``. The following lines select the values of a package name and its version number, -respectively: :: +respectively:: - PN = "${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE', False),d)[0] or 'defaultpkgname'}" - PV = "${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE', False),d)[1] or '1.0'}" + PN = "${@bb.parse.vars_from_file(d.getVar('FILE', False),d)[0] or 'defaultpkgname'}" + PV = "${@bb.parse.vars_from_file(d.getVar('FILE', False),d)[1] or '1.0'}" .. note:: Inline Python expressions work just like variable expansions insofar as the "=" and ":=" operators are concerned. Given the following assignment, foo() - is called each time FOO is expanded: :: + is called each time FOO is expanded:: FOO = "${@foo()}" Contrast this with the following immediate assignment, where foo() is only - called once, while the assignment is parsed: :: + called once, while the assignment is parsed:: FOO := "${@foo()}" @@ -437,7 +494,7 @@ Unsetting variables It is possible to completely remove a variable or a variable flag from BitBake's internal data dictionary by using the "unset" keyword. Here is -an example: :: +an example:: unset DATE unset do_fetch[noexec] @@ -452,7 +509,7 @@ When specifying pathnames for use with BitBake, do not use the tilde cause BitBake to not recognize the path since BitBake does not expand this character in the same way a shell would. -Instead, provide a fuller path as the following example illustrates: :: +Instead, provide a fuller path as the following example illustrates:: BBLAYERS ?= " \ /home/scott-lenovo/LayerA \ @@ -463,7 +520,7 @@ Exporting Variables to the Environment You can export variables to the environment of running tasks by using the ``export`` keyword. For example, in the following example, the -``do_foo`` task prints "value from the environment" when run: :: +``do_foo`` task prints "value from the environment" when run:: export ENV_VARIABLE ENV_VARIABLE = "value from the environment" @@ -481,7 +538,7 @@ It does not matter whether ``export ENV_VARIABLE`` appears before or after assignments to ``ENV_VARIABLE``. It is also possible to combine ``export`` with setting a value for the -variable. Here is an example: :: +variable. Here is an example:: export ENV_VARIABLE = "variable-value" @@ -496,78 +553,78 @@ Conditional Syntax (Overrides) 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 +files. This section describes how you can use :term:`OVERRIDES` as 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 -------------------- -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 variable. .. note:: - Overrides can only use lower-case characters. Additionally, - underscores are not permitted in override names as they are used to + Overrides can only use lower-case characters, digits and dashes. + In particular, colons are not permitted in override names as they are used to 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 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 - non-conditional version. Here is an example: :: + non-conditional version. Here is an example:: OVERRIDES = "architecture:os:machine" TEST = "default" - TEST_os = "osspecific" - TEST_nooverride = "othercondvalue" + TEST:os = "osspecific" + TEST:nooverride = "othercondvalue" - In this example, the ``OVERRIDES`` + In this example, the :term:`OVERRIDES` variable lists three overrides: "architecture", "os", and "machine". The variable ``TEST`` by itself has a default value of "default". You select the os-specific version of the ``TEST`` variable by appending - the "os" override to the variable (i.e. ``TEST_os``). + the "os" override to the variable (i.e. ``TEST:os``). To better understand this, consider a practical example that assumes an OpenEmbedded metadata-based Linux kernel recipe file. The following lines from the recipe file first set the kernel branch variable ``KBRANCH`` to a default value, then conditionally override - that value based on the architecture of the build: :: + that value based on the architecture of the build:: KBRANCH = "standard/base" - KBRANCH_qemuarm = "standard/arm-versatile-926ejs" - KBRANCH_qemumips = "standard/mti-malta32" - KBRANCH_qemuppc = "standard/qemuppc" - KBRANCH_qemux86 = "standard/common-pc/base" - KBRANCH_qemux86-64 = "standard/common-pc-64/base" - KBRANCH_qemumips64 = "standard/mti-malta64" + KBRANCH:qemuarm = "standard/arm-versatile-926ejs" + KBRANCH:qemumips = "standard/mti-malta32" + KBRANCH:qemuppc = "standard/qemuppc" + KBRANCH:qemux86 = "standard/common-pc/base" + KBRANCH:qemux86-64 = "standard/common-pc-64/base" + KBRANCH:qemumips64 = "standard/mti-malta64" - *Appending and Prepending:* BitBake also supports append and prepend 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" 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 example, the following lines will conditionally append to the - ``KERNEL_FEATURES`` variable based on the architecture: :: + ``KERNEL_FEATURES`` variable based on the architecture:: - KERNEL_FEATURES_append = " ${KERNEL_EXTRA_FEATURES}" - KERNEL_FEATURES_append_qemux86=" cfg/sound.scc cfg/paravirt_kvm.scc" - KERNEL_FEATURES_append_qemux86-64=" cfg/sound.scc cfg/paravirt_kvm.scc" + KERNEL_FEATURES:append = " ${KERNEL_EXTRA_FEATURES}" + KERNEL_FEATURES:append:qemux86=" cfg/sound.scc cfg/paravirt_kvm.scc" + KERNEL_FEATURES:append:qemux86-64=" cfg/sound.scc cfg/paravirt_kvm.scc" - *Setting a Variable for a Single Task:* BitBake supports setting a - variable just for the duration of a single task. Here is an example: :: + variable just for the duration of a single task. Here is an example:: - FOO_task-configure = "val 1" - FOO_task-compile = "val 2" + FOO:task-configure = "val 1" + FOO:task-compile = "val 2" In the previous example, ``FOO`` has the value "val 1" while the @@ -580,15 +637,25 @@ variable. ``do_compile`` task. You can also use this syntax with other combinations (e.g. - "``_prepend``") as shown in the following example: :: + "``:prepend``") as shown in the following example:: - EXTRA_OEMAKE_prepend_task-compile = "${PARALLEL_MAKE} " + EXTRA_OEMAKE:prepend:task-compile = "${PARALLEL_MAKE} " + +.. note:: + + Before BitBake 1.52 (Honister 3.4), the syntax for :term:`OVERRIDES` + used ``_`` instead of ``:``, so you will still find a lot of documentation + using ``_append``, ``_prepend``, and ``_remove``, for example. + + For details, see the + :yocto_docs:`Overrides Syntax Changes </migration-guides/migration-3.4.html#override-syntax-changes>` + section in the Yocto Project manual migration notes. Key Expansion ------------- Key expansion happens when the BitBake datastore is finalized. To better -understand this, consider the following example: :: +understand this, consider the following example:: A${B} = "X" B = "2" @@ -612,57 +679,57 @@ users. There is often confusion concerning the order in which overrides and various "append" operators take effect. Recall that an append or prepend -operation using "_append" and "_prepend" does not result in an immediate +operation using ":append" and ":prepend" does not result in an immediate assignment as would "+=", ".=", "=+", or "=.". Consider the following -example: :: +example:: OVERRIDES = "foo" A = "Z" - A_foo_append = "X" + A:foo:append = "X" For this case, ``A`` is unconditionally set to "Z" and "X" is unconditionally and -immediately appended to the variable ``A_foo``. Because overrides have -not been applied yet, ``A_foo`` is set to "X" due to the append and +immediately appended to the variable ``A:foo``. Because overrides have +not been applied yet, ``A:foo`` is set to "X" due to the append and ``A`` simply equals "Z". Applying overrides, however, changes things. Since "foo" is listed in -``OVERRIDES``, the conditional variable ``A`` is replaced with the "foo" -version, which is equal to "X". So effectively, ``A_foo`` replaces +:term:`OVERRIDES`, the conditional variable ``A`` is replaced with the "foo" +version, which is equal to "X". So effectively, ``A:foo`` replaces ``A``. -This next example changes the order of the override and the append: :: +This next example changes the order of the override and the append:: OVERRIDES = "foo" A = "Z" - A_append_foo = "X" + A:append:foo = "X" For this case, before -overrides are handled, ``A`` is set to "Z" and ``A_append_foo`` is set +overrides are handled, ``A`` is set to "Z" and ``A:append:foo`` is set to "X". Once the override for "foo" is applied, however, ``A`` gets appended with "X". Consequently, ``A`` becomes "ZX". Notice that spaces are not appended. This next example has the order of the appends and overrides reversed -back as in the first example: :: +back as in the first example:: OVERRIDES = "foo" A = "Y" - A_foo_append = "Z" - A_foo_append = "X" + A:foo:append = "Z" + A:foo:append = "X" For this case, before any overrides are resolved, ``A`` is set to "Y" using an immediate assignment. After this immediate -assignment, ``A_foo`` is set to "Z", and then further appended with "X" +assignment, ``A:foo`` is set to "Z", and then further appended with "X" leaving the variable set to "ZX". Finally, applying the override for "foo" results in the conditional variable ``A`` becoming "ZX" (i.e. -``A`` is replaced with ``A_foo``). +``A`` is replaced with ``A:foo``). -This final example mixes in some varying operators: :: +This final example mixes in some varying operators:: A = "1" - A_append = "2" - A_append = "3" + A:append = "2" + A:append = "3" A += "4" A .= "5" @@ -670,7 +737,7 @@ For this case, the type of append operators are affecting the order of assignments as BitBake passes through the code multiple times. Initially, ``A`` is set to "1 45" because of the three statements that use immediate operators. After -these assignments are made, BitBake applies the "_append" operations. +these assignments are made, BitBake applies the ":append" operations. Those operations result in ``A`` becoming "1 4523". Sharing Functionality @@ -686,7 +753,7 @@ share the task. This section presents the mechanisms BitBake provides to allow you to share functionality between recipes. Specifically, the mechanisms -include ``include``, ``inherit``, ``INHERIT``, and ``require`` +include ``include``, ``inherit``, :term:`INHERIT`, and ``require`` directives. Locating Include and Class Files @@ -702,7 +769,7 @@ current directory for ``include`` and ``require`` directives. In order for include and class files to be found by BitBake, they need to be located in a "classes" subdirectory that can be found in -``BBPATH``. +:term:`BBPATH`. ``inherit`` Directive --------------------- @@ -720,12 +787,12 @@ file and then have your recipe inherit that class file. As an example, your recipes could use the following directive to inherit an ``autotools.bbclass`` file. The class file would contain common -functionality for using Autotools that could be shared across recipes: :: +functionality for using Autotools that could be shared across recipes:: inherit autotools In this case, BitBake would search for the directory -``classes/autotools.bbclass`` in ``BBPATH``. +``classes/autotools.bbclass`` in :term:`BBPATH`. .. note:: @@ -734,7 +801,7 @@ In this case, BitBake would search for the directory If you want to use the directive to inherit multiple classes, separate them with spaces. The following example shows how to inherit both the -``buildhistory`` and ``rm_work`` classes: :: +``buildhistory`` and ``rm_work`` classes:: inherit buildhistory rm_work @@ -742,19 +809,19 @@ An advantage with the inherit directive as compared to both the :ref:`include <bitbake-user-manual/bitbake-user-manual-metadata:\`\`include\`\` directive>` and :ref:`require <bitbake-user-manual/bitbake-user-manual-metadata:\`\`require\`\` directive>` directives is that you can inherit class files conditionally. You can accomplish this by using a variable expression after the ``inherit`` -statement. Here is an example: :: +statement. Here is an example:: inherit ${VARNAME} If ``VARNAME`` is going to be set, it needs to be set before the ``inherit`` statement is parsed. One way to achieve a conditional inherit in this case is to use -overrides: :: +overrides:: VARIABLE = "" - VARIABLE_someoverride = "myclass" + VARIABLE:someoverride = "myclass" -Another method is by using anonymous Python. Here is an example: :: +Another method is by using anonymous Python. Here is an example:: python () { if condition == value: @@ -764,7 +831,7 @@ Another method is by using anonymous Python. Here is an example: :: } Alternatively, you could use an in-line Python expression in the -following form: :: +following form:: inherit ${@'classname' if condition else ''} inherit ${@functionname(params)} @@ -780,7 +847,7 @@ BitBake understands the ``include`` directive. This directive causes BitBake to parse whatever file you specify, and to insert that file at that location. The directive is much like its equivalent in Make except that if the path specified on the include line is a relative path, -BitBake locates the first file it can find within ``BBPATH``. +BitBake locates the first file it can find within :term:`BBPATH`. 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>` @@ -790,7 +857,7 @@ encapsulated functionality or configuration that does not suit a ``.bbclass`` file. As an example, suppose you needed a recipe to include some self-test -definitions: :: +definitions:: include test_defs.inc @@ -822,7 +889,7 @@ does not suit a ``.bbclass`` file. 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 -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. ``foo_1.2.2.bb`` and ``foo_2.0.0.bb``) where each version contains some @@ -831,7 +898,7 @@ include file named ``foo.inc`` that contains the common definitions needed to build "foo". You need to be sure ``foo.inc`` is located in the same directory as your two recipe files as well. Once these conditions are set up, you can share the functionality using a ``require`` -directive from within each recipe: :: +directive from within each recipe:: require foo.inc @@ -844,14 +911,14 @@ class. BitBake only supports this directive when used within a configuration file. As an example, suppose you needed to inherit a class file called -``abc.bbclass`` from a configuration file as follows: :: +``abc.bbclass`` from a configuration file as follows:: INHERIT += "abc" This configuration directive causes the named class to be inherited at the point of the directive during parsing. As with the ``inherit`` directive, the ``.bbclass`` file must be located in a "classes" -subdirectory in one of the directories specified in ``BBPATH``. +subdirectory in one of the directories specified in :term:`BBPATH`. .. note:: @@ -862,7 +929,7 @@ subdirectory in one of the directories specified in ``BBPATH``. If you want to use the directive to inherit multiple classes, you can provide them on the same line in the ``local.conf`` file. Use spaces to separate the classes. The following example shows how to inherit both -the ``autotools`` and ``pkgconfig`` classes: :: +the ``autotools`` and ``pkgconfig`` classes:: INHERIT += "autotools pkgconfig" @@ -893,9 +960,9 @@ Regardless of the type of function, you can only define them in class Shell Functions --------------- -Functions written in shell script and executed either directly as +Functions written in shell script are executed either directly as functions, tasks, or both. They can also be called by other shell -functions. Here is an example shell function definition: :: +functions. Here is an example shell function definition:: some_function () { echo "Hello World" @@ -907,19 +974,19 @@ rules. The scripts are executed by ``/bin/sh``, which may not be a bash shell but might be something such as ``dash``. You should not use Bash-specific script (bashisms). -Overrides and override-style operators like ``_append`` and ``_prepend`` +Overrides and override-style operators like ``:append`` and ``:prepend`` can also be applied to shell functions. Most commonly, this application would be used in a ``.bbappend`` file to modify functions in the main recipe. It can also be used to modify functions inherited from classes. -As an example, consider the following: :: +As an example, consider the following:: do_foo() { bbplain first fn } - fn_prepend() { + fn:prepend() { bbplain second } @@ -927,11 +994,11 @@ As an example, consider the following: :: bbplain third } - do_foo_append() { + do_foo:append() { bbplain fourth } -Running ``do_foo`` prints the following: :: +Running ``do_foo`` prints the following:: recipename do_foo: first recipename do_foo: second @@ -943,7 +1010,7 @@ Running ``do_foo`` prints the following: :: Overrides and override-style operators can be applied to any shell function, not just :ref:`tasks <bitbake-user-manual/bitbake-user-manual-metadata:tasks>`. -You can use the ``bitbake -e`` recipename command to view the final +You can use the ``bitbake -e recipename`` command to view the final assembled function after all overrides have been applied. BitBake-Style Python Functions @@ -952,7 +1019,7 @@ BitBake-Style Python Functions These functions are written in Python and executed by BitBake or other Python functions using ``bb.build.exec_func()``. -An example BitBake function is: :: +An example BitBake function is:: python some_python_function () { d.setVar("TEXT", "Hello World") @@ -975,9 +1042,9 @@ import these modules. Also in these types of functions, the datastore Similar to shell functions, you can also apply overrides and override-style operators to BitBake-style Python functions. -As an example, consider the following: :: +As an example, consider the following:: - python do_foo_prepend() { + python do_foo:prepend() { bb.plain("first") } @@ -985,17 +1052,17 @@ As an example, consider the following: :: bb.plain("second") } - python do_foo_append() { + python do_foo:append() { bb.plain("third") } -Running ``do_foo`` prints the following: :: +Running ``do_foo`` prints the following:: recipename do_foo: first recipename do_foo: second recipename do_foo: third -You can use the ``bitbake -e`` recipename command to view +You can use the ``bitbake -e recipename`` command to view the final assembled function after all overrides have been applied. Python Functions @@ -1004,7 +1071,7 @@ Python Functions These functions are written in Python and are executed by other Python code. Examples of Python functions are utility functions that you intend to call from in-line Python or from within other Python functions. Here -is an example: :: +is an example:: def get_depends(d): if d.getVar('SOMECONDITION'): @@ -1015,7 +1082,7 @@ is an example: :: SOMECONDITION = "1" 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: @@ -1056,7 +1123,7 @@ functions and regular Python functions defined with "def": - Regular Python functions are called with the usual Python syntax. BitBake-style Python functions are usually tasks and are called directly by BitBake, but can also be called manually from Python code - by using the ``bb.build.exec_func()`` function. Here is an example: :: + by using the ``bb.build.exec_func()`` function. Here is an example:: bb.build.exec_func("my_bitbake_style_function", d) @@ -1094,7 +1161,7 @@ Sometimes it is useful to set variables or perform other operations programmatically during parsing. To do this, you can define special Python functions, called anonymous Python functions, that run at the end of parsing. For example, the following conditionally sets a variable -based on the value of another variable: :: +based on the value of another variable:: python () { if d.getVar('SOMEVAR') == 'value': @@ -1107,7 +1174,7 @@ the name "__anonymous", rather than no name. Anonymous Python functions always run at the end of parsing, regardless of where they are defined. If a recipe contains many anonymous functions, they run in the same order as they are defined within the -recipe. As an example, consider the following snippet: :: +recipe. As an example, consider the following snippet:: python () { d.setVar('FOO', 'foo 2') @@ -1122,7 +1189,7 @@ recipe. As an example, consider the following snippet: :: BAR = "bar 1" The previous example is conceptually -equivalent to the following snippet: :: +equivalent to the following snippet:: FOO = "foo 1" BAR = "bar 1" @@ -1134,12 +1201,12 @@ equivalent to the following snippet: :: values set for the variables within the anonymous functions become available to tasks, which always run after parsing. -Overrides and override-style operators such as "``_append``" are applied +Overrides and override-style operators such as "``:append``" are applied before anonymous functions run. In the following example, ``FOO`` ends -up with the value "foo from anonymous": :: +up with the value "foo from anonymous":: FOO = "foo" - FOO_append = " from outside" + FOO:append = " from outside" python () { d.setVar("FOO", "foo from anonymous") @@ -1164,7 +1231,7 @@ To understand the benefits of this feature, consider the basic scenario where a class defines a task function and your recipe inherits the class. In this basic scenario, your recipe inherits the task function as defined in the class. If desired, your recipe can add to the start and -end of the function by using the "_prepend" or "_append" operations +end of the function by using the ":prepend" or ":append" operations respectively, or it can redefine the function completely. However, if it redefines the function, there is no means for it to call the class version of the function. ``EXPORT_FUNCTIONS`` provides a mechanism that @@ -1173,24 +1240,24 @@ version of the function. To make use of this technique, you need the following things in place: -- The class needs to define the function as follows: :: +- The class needs to define the function as follows:: classname_functionname For example, if you have a class file ``bar.bbclass`` and a function named ``do_foo``, the class must - define the function as follows: :: + define the function as follows:: bar_do_foo - The class needs to contain the ``EXPORT_FUNCTIONS`` statement as - follows: :: + follows:: EXPORT_FUNCTIONS functionname For example, continuing with the same example, the statement in the ``bar.bbclass`` would be as - follows: :: + follows:: EXPORT_FUNCTIONS do_foo @@ -1199,7 +1266,7 @@ To make use of this technique, you need the following things in place: class version of the function, it should call ``bar_do_foo``. Assuming ``do_foo`` was a shell function and ``EXPORT_FUNCTIONS`` was used as above, the recipe's function could conditionally call the - class version of the function as follows: :: + class version of the function as follows:: do_foo() { if [ somecondition ] ; then @@ -1233,7 +1300,7 @@ Tasks are either :ref:`shell functions <bitbake-user-manual/bitbake-user-manual- that have been promoted to tasks by using the ``addtask`` command. The ``addtask`` command can also optionally describe dependencies between the task and other tasks. Here is an example that shows how to define a -task and declare some dependencies: :: +task and declare some dependencies:: python do_printdate () { import time @@ -1264,12 +1331,12 @@ Additionally, the ``do_printdate`` task becomes dependent upon the rerun for experimentation purposes, you can make BitBake always consider the task "out-of-date" by using the :ref:`[nostamp] <bitbake-user-manual/bitbake-user-manual-metadata:Variable Flags>` - variable flag, as follows: :: + variable flag, as follows:: do_printdate[nostamp] = "1" You can also explicitly run the task and provide the - -f option as follows: :: + -f option as follows:: $ bitbake recipe -c printdate -f @@ -1278,7 +1345,7 @@ Additionally, the ``do_printdate`` task becomes dependent upon the name. You might wonder about the practical effects of using ``addtask`` -without specifying any dependencies as is done in the following example: :: +without specifying any dependencies as is done in the following example:: addtask printdate @@ -1286,7 +1353,7 @@ In this example, assuming dependencies have not been added through some other means, the only way to run the task is by explicitly selecting it with ``bitbake`` recipe ``-c printdate``. You can use the ``do_listtasks`` task to list all tasks defined in a recipe -as shown in the following example: :: +as shown in the following example:: $ bitbake recipe -c listtasks @@ -1296,12 +1363,23 @@ For more information on task dependencies, see the See the ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:variable flags`" section for information on variable flags you can use with tasks. +.. note:: + + While it's infrequent, it's possible to define multiple tasks as + dependencies when calling ``addtask``. For example, here's a snippet + from the OpenEmbedded class file ``package_tar.bbclass``:: + + addtask package_write_tar before do_build after do_packagedata do_package + + Note how the ``package_write_tar`` task has to wait until both of + ``do_packagedata`` and ``do_package`` complete. + Deleting a Task --------------- As well as being able to add tasks, you can delete them. Simply use the ``deltask`` command to delete a task. For example, to delete the example -task used in the previous sections, you would use: :: +task used in the previous sections, you would use:: deltask printdate @@ -1317,7 +1395,7 @@ to run before ``do_a``. If you want dependencies such as these to remain intact, use the ``[noexec]`` varflag to disable the task instead of using the -``deltask`` command to delete it: :: +``deltask`` command to delete it:: do_b[noexec] = "1" @@ -1331,8 +1409,8 @@ the build machine cannot influence the build. .. note:: By default, BitBake cleans the environment to include only those - things exported or listed in its whitelist to ensure that the build - environment is reproducible and consistent. You can prevent this + things exported or listed in its passthrough list to ensure that the + build environment is reproducible and consistent. You can prevent this "cleaning" by setting the :term:`BB_PRESERVE_ENV` variable. Consequently, if you do want something to get passed into the build task @@ -1340,14 +1418,14 @@ environment, you must take these two steps: #. Tell BitBake to load what you want from the environment into the datastore. You can do so through the - :term:`BB_ENV_WHITELIST` and - :term:`BB_ENV_EXTRAWHITE` variables. For + :term:`BB_ENV_PASSTHROUGH` and + :term:`BB_ENV_PASSTHROUGH_ADDITIONS` 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 - variable into the datastore: :: + your ``$HOME/.ccache`` directory. The following command adds the + the environment variable ``CCACHE_DIR`` to BitBake's passthrough + list to allow that variable into the datastore:: - export BB_ENV_EXTRAWHITE="$BB_ENV_EXTRAWHITE CCACHE_DIR" + export BB_ENV_PASSTHROUGH_ADDITIONS="$BB_ENV_PASSTHROUGH_ADDITIONS CCACHE_DIR" #. Tell BitBake to export what you have loaded into the datastore to the task environment of every running task. Loading something from the @@ -1355,7 +1433,7 @@ environment, you must take these two steps: available in the datastore. To export it to the task environment of every running task, use a command similar to the following in your local configuration file ``local.conf`` or your distribution - configuration file: :: + configuration file:: export CCACHE_DIR @@ -1364,17 +1442,17 @@ environment, you must take these two steps: A side effect of the previous steps is that BitBake records the variable as a dependency of the build process in things like the setscene checksums. If doing so results in unnecessary rebuilds of - tasks, you can whitelist the variable so that the setscene code + tasks, you can also flag the variable so that the setscene code ignores the dependency when it creates checksums. 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 :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 ``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:: origenv = d.getVar("BB_ORIGENV", False) bar = origenv.getVar("BAR", False) @@ -1387,7 +1465,7 @@ Variable Flags Variable flags (varflags) help control a task's functionality and dependencies. BitBake reads and writes varflags to the datastore using -the following command forms: :: +the following command forms:: variable = d.getVarFlags("variable") self.d.setVarFlags("FOO", {"func": True}) @@ -1418,12 +1496,35 @@ functionality of the task: directory listed is used as the current working directory for the task. +- ``[file-checksums]``: Controls the file dependencies for a task. The + baseline file list is the set of files associated with + :term:`SRC_URI`. May be used to set additional dependencies on + files not associated with :term:`SRC_URI`. + + The value set to the list is a file-boolean pair where the first + value is the file name and the second is whether or not it + physically exists on the filesystem. :: + + do_configure[file-checksums] += "${MY_DIRPATH}/my-file.txt:True" + + It is important to record any paths which the task looked at and + which didn't exist. This means that if these do exist at a later + time, the task can be rerun with the new additional files. The + "exists" True or False value after the path allows this to be + handled. + - ``[lockfiles]``: Specifies one or more lockfiles to lock while the task executes. Only one task may hold a lockfile, and any task that attempts to lock an already locked file will block until the lock is released. You can use this variable flag to accomplish mutual exclusion. +- ``[network]``: When set to "1", allows a task to access the network. By + default, only the ``do_fetch`` task is granted network access. Recipes + shouldn't access the network outside of ``do_fetch`` as it usually + undermines fetcher source mirroring, image and licence manifests, software + auditing and supply chain security. + - ``[noexec]``: When set to "1", marks the task as being empty, with no execution required. You can use the ``[noexec]`` flag to set up tasks as dependency placeholders, or to disable tasks defined @@ -1456,7 +1557,7 @@ functionality of the task: can result in unpredictable behavior. - 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. - ``[postfuncs]``: List of functions to call after the completion of @@ -1526,7 +1627,7 @@ intent is to make it easy to do things like email notification on build failures. 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 python myclass_eventhandler() { @@ -1565,11 +1666,11 @@ might have an interest in viewing: - ``bb.event.ConfigParsed()``: Fired when the base configuration; which 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 the server changes configuration and reparses. Any given datastore only has one such event executed against it, however. If - ```BB_INVALIDCONF`` <#>`__ is set in the datastore by the event + :term:`BB_INVALIDCONF` is set in the datastore by the event handler, the configuration is reparsed and a new event triggered, allowing the metadata to update configuration. @@ -1636,13 +1737,18 @@ user interfaces: .. _variants-class-extension-mechanism: -Variants - Class Extension Mechanism -==================================== +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 -:term:`BBCLASSEXTEND` and :term:`BBVERSIONS` variables. +BitBake supports multiple incarnations of a recipe file via the +:term:`BBCLASSEXTEND` variable. + +The :term:`BBCLASSEXTEND` variable is a space separated list of classes used +to "extend" the recipe for each variant. Here is an example that results in a +second incarnation of the current recipe being available. This second +incarnation will have the "native" class inherited. :: + + BBCLASSEXTEND = "native" .. note:: @@ -1652,34 +1758,6 @@ incarnations are buildable. These features are enabled through the class. For specific examples, see the OE-Core native , nativesdk , and multilib classes. -- ``BBCLASSEXTEND``: This variable is a space separated list of - classes used to "extend" the recipe for each variant. Here is an - example that results in a second incarnation of the current recipe - being available. This second incarnation will have the "native" class - inherited. :: - - BBCLASSEXTEND = "native" - -- ``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 - :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+ 1.0.[7-9]:1.0.7+" - SRC_URI_append_1.0.7+ = "file://some_patch_which_the_new_versions_need.patch;patch=1" - - The name of the range defaults to the original version of the recipe. For - example, in OpenEmbedded, the recipe file ``foo_1.0.0+.bb`` creates a default - name range of ``1.0.0+``. This is useful because the range 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 (:term:`FILESPATH`). - Dependencies ============ @@ -1708,7 +1786,7 @@ Dependencies Internal to the ``.bb`` File BitBake uses the ``addtask`` directive to manage dependencies that are internal to a given recipe file. You can use the ``addtask`` directive to indicate when a task is dependent on other tasks or when other tasks -depend on that recipe. Here is an example: :: +depend on that recipe. Here is an example:: addtask printdate after do_fetch before do_build @@ -1732,7 +1810,7 @@ task depends on the completion of the ``do_printdate`` task. - The directive ``addtask mytask after do_configure`` by itself never causes ``do_mytask`` to run. ``do_mytask`` can still be run - manually as follows: :: + manually as follows:: $ bitbake recipe -c mytask @@ -1745,13 +1823,13 @@ Build Dependencies 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: :: +the task of each item listed in :term:`DEPENDS` that must complete before +that task can be executed. Here is an example:: do_configure[deptask] = "do_populate_sysroot" In this example, the ``do_populate_sysroot`` task -of each item in ``DEPENDS`` must complete before ``do_configure`` can +of each item in :term:`DEPENDS` must complete before ``do_configure`` can execute. Runtime Dependencies @@ -1760,8 +1838,8 @@ Runtime Dependencies 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 -can have ``RDEPENDS`` and ``RRECOMMENDS`` runtime dependencies. The +The :term:`PACKAGES` variable lists runtime packages. Each of those packages +can have :term:`RDEPENDS` and :term:`RRECOMMENDS` runtime dependencies. The ``[rdeptask]`` flag for tasks is used to signify the task of each item runtime dependency which must have completed before that task can be executed. :: @@ -1769,9 +1847,9 @@ executed. :: do_package_qa[rdeptask] = "do_packagedata" 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. -Although ``RDEPENDS`` contains entries from the +Although :term:`RDEPENDS` contains entries from the runtime dependency namespace, BitBake knows how to map them back to the build-time dependency namespace, in which the tasks are defined. @@ -1788,7 +1866,7 @@ dependencies are discovered and added. The ``[recrdeptask]`` flag is most commonly used in high-level recipes that need to wait for some task to finish "globally". For example, -``image.bbclass`` has the following: :: +``image.bbclass`` has the following:: do_rootfs[recrdeptask] += "do_packagedata" @@ -1797,7 +1875,7 @@ the current recipe and all recipes reachable (by way of dependencies) from the image recipe must run before the ``do_rootfs`` task can run. BitBake allows a task to recursively depend on itself by -referencing itself in the task list: :: +referencing itself in the task list:: do_a[recrdeptask] = "do_a do_b" @@ -1814,7 +1892,7 @@ Inter-Task Dependencies BitBake uses the ``[depends]`` flag in a more generic form to manage inter-task dependencies. This more generic form allows for inter-dependency checks for specific tasks rather than checks for the -data in ``DEPENDS``. Here is an example: :: +data in :term:`DEPENDS`. Here is an example:: do_patch[depends] = "quilt-native:do_populate_sysroot" @@ -1900,6 +1978,33 @@ looking at the source code of the ``bb`` module, which is in the commonly used functions ``bb.utils.contains()`` and ``bb.utils.mkdirhier()``, which come with docstrings. +Extending Python Library Code +----------------------------- + +If you wish to add your own Python library code (e.g. to provide +functions/classes you can use from Python functions in the metadata) +you can do so from any layer using the ``addpylib`` directive. +This directive is typically added to your layer configuration ( +``conf/layer.conf``) although it will be handled in any ``.conf`` file. + +Usage is of the form:: + + addpylib <directory> <namespace> + +Where <directory> specifies the directory to add to the library path. +The specified <namespace> is imported automatically, and if the imported +module specifies an attribute named ``BBIMPORTS``, that list of +sub-modules is iterated and imported too. + +Testing and Debugging BitBake Python code +----------------------------------------- + +The OpenEmbedded build system implements a convenient ``pydevshell`` target which +you can use to access the BitBake datastore and experiment with your own Python +code. See :yocto_docs:`Using a Python Development Shell +</dev-manual/python-development-shell.html#using-a-python-development-shell>` in the Yocto +Project manual for details. + Task Checksums and Setscene =========================== @@ -1909,7 +2014,7 @@ To help understand how BitBake does this, the section assumes an OpenEmbedded metadata-based example. These checksums are stored in :term:`STAMP`. You can -examine the checksums using the following BitBake command: :: +examine the checksums using the following BitBake command:: $ bitbake-dumpsigs @@ -1932,16 +2037,6 @@ The following list describes related variables: Specifies a function BitBake calls that determines whether BitBake requires a setscene dependency to be met. -- :term:`BB_SETSCENE_VERIFY_FUNCTION2`: - Specifies a function to call that verifies the list of planned task - execution before the main task execution happens. - -- :term:`BB_STAMP_POLICY`: Defines the mode - for comparing timestamps of stamp files. - -- :term:`BB_STAMP_WHITELIST`: Lists stamp - files that are looked at when the stamp policy is "whitelist". - - :term:`BB_TASKHASH`: Within an executing task, this variable holds the hash of the task as returned by the currently enabled signature generator. @@ -1956,7 +2051,7 @@ Wildcard Support in Variables ============================= Support for wildcard use in variables varies depending on the context in -which it is used. For example, some variables and file names allow +which it is used. For example, some variables and filenames allow limited use of wildcards through the "``%``" and "``*``" characters. Other variables or names support Python's `glob <https://docs.python.org/3/library/glob.html>`_ syntax, diff --git a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-ref-variables-context.rst b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-ref-variables-context.rst new file mode 100644 index 0000000000..e9c454ba11 --- /dev/null +++ b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-ref-variables-context.rst @@ -0,0 +1,91 @@ +.. SPDX-License-Identifier: CC-BY-2.5 + +================ +Variable Context +================ + +| + +Variables might only have an impact or can be used in certain contexts. Some +should only be used in global files like ``.conf``, while others are intended only +for local files like ``.bb``. This chapter aims to describe some important variable +contexts. + +.. _ref-varcontext-configuration: + +BitBake's own configuration +=========================== + +Variables starting with ``BB_`` usually configure the behaviour of BitBake itself. +For example, one could configure: + +- System resources, like disk space to be used (:term:`BB_DISKMON_DIRS`), + or the number of tasks to be run in parallel by BitBake (:term:`BB_NUMBER_THREADS`). + +- How the fetchers shall behave, e.g., :term:`BB_FETCH_PREMIRRORONLY` is used + by BitBake to determine if BitBake's fetcher shall search only + :term:`PREMIRRORS` for files. + +Those variables are usually configured globally. + +BitBake configuration +===================== + +There are variables: + +- Like :term:`B` or :term:`T`, that are used to specify directories used by + BitBake during the build of a particular recipe. Those variables are + specified in ``bitbake.conf``. Some, like :term:`B`, are quite often + overwritten in recipes. + +- Starting with ``FAKEROOT``, to configure how the ``fakeroot`` command is + handled. Those are usually set by ``bitbake.conf`` and might get adapted in a + ``bbclass``. + +- Detailing where BitBake will store and fetch information from, for + data reuse between build runs like :term:`CACHE`, :term:`DL_DIR` or + :term:`PERSISTENT_DIR`. Those are usually global. + + +Layers and files +================ + +Variables starting with ``LAYER`` configure how BitBake handles layers. +Additionally, variables starting with ``BB`` configure how layers and files are +handled. For example: + +- :term:`LAYERDEPENDS` is used to configure on which layers a given layer + depends. + +- The configured layers are contained in :term:`BBLAYERS` and files in + :term:`BBFILES`. + +Those variables are often used in the files ``layer.conf`` and ``bblayers.conf``. + +Recipes and packages +==================== + +Variables handling recipes and packages can be split into: + +- :term:`PN`, :term:`PV` or :term:`PF` for example, contain information about + the name or revision of a recipe or package. Usually, the default set in + ``bitbake.conf`` is used, but those are from time to time overwritten in + recipes. + +- :term:`SUMMARY`, :term:`DESCRIPTION`, :term:`LICENSE` or :term:`HOMEPAGE` + contain the expected information and should be set specifically for every + recipe. + +- In recipes, variables are also used to control build and runtime + dependencies between recipes/packages with other recipes/packages. The + most common should be: :term:`PROVIDES`, :term:`RPROVIDES`, :term:`DEPENDS`, + and :term:`RDEPENDS`. + +- There are further variables starting with ``SRC`` that specify the sources in + a recipe like :term:`SRC_URI` or :term:`SRCDATE`. Those are also usually set + in recipes. + +- Which version or provider of a recipe should be given preference when + multiple recipes would provide the same item, is controlled by variables + starting with ``PREFERRED_``. Those are normally set in the configuration + files of a ``MACHINE`` or ``DISTRO``. diff --git a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst index 74a3eb8095..899e584f91 100644 --- a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst +++ b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst @@ -23,22 +23,31 @@ overview of their function and contents. systems extend the functionality of the variable as it is described here in this glossary. - - Finally, there are variables mentioned in this glossary that do - not appear in the BitBake glossary. These other variables are - variables used in systems that use BitBake. - .. glossary:: + :sorted: :term:`ASSUME_PROVIDED` Lists recipe names (:term:`PN` values) BitBake does not attempt to build. Instead, BitBake assumes these recipes have already been built. - In OpenEmbedded-Core, ``ASSUME_PROVIDED`` mostly specifies native + In OpenEmbedded-Core, :term:`ASSUME_PROVIDED` mostly specifies native tools that should not be built. An example is ``git-native``, which when specified allows for the Git binary from the host to be used rather than building ``git-native``. + :term:`AZ_SAS` + Azure Storage Shared Access Signature, when using the + :ref:`Azure Storage fetcher <bitbake-user-manual/bitbake-user-manual-fetching:fetchers>` + This variable can be defined to be used by the fetcher to authenticate + and gain access to non-public artifacts:: + + AZ_SAS = ""se=2021-01-01&sp=r&sv=2018-11-09&sr=c&skoid=<skoid>&sig=<signature>"" + + For more information see Microsoft's Azure Storage documentation at + https://docs.microsoft.com/en-us/azure/storage/common/storage-sas-overview + + :term:`B` The directory in which BitBake executes functions during a recipe's build process. @@ -74,14 +83,41 @@ 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 + Using :term:`BB_ALLOWED_NETWORKS` in conjunction with :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 when a host that is not allowed is in a :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. + fetcher does not attempt to use the host listed in :term:`SRC_URI` after + a successful fetch from the :term:`PREMIRRORS` occurs. + + :term:`BB_BASEHASH_IGNORE_VARS` + Lists variables that are excluded from checksum and dependency data. + Variables that are excluded can therefore change without affecting + the checksum mechanism. A common example would be the variable for + the path of the build. BitBake's output should not (and usually does + not) depend on the directory in which it was built. + + :term:`BB_CACHEDIR` + Specifies the code parser cache directory (distinct from :term:`CACHE` + and :term:`PERSISTENT_DIR` although they can be set to the same value + if desired). The default value is "${TOPDIR}/cache". + + :term:`BB_CHECK_SSL_CERTS` + Specifies if SSL certificates should be checked when fetching. The default + value is ``1`` and certificates are not checked if the value is set to ``0``. + + :term:`BB_HASH_CODEPARSER_VALS` + Specifies values for variables to use when populating the codeparser cache. + This can be used selectively to set dummy values for variables to avoid + the codeparser cache growing on every parse. Variables that would typically + be included are those where the value is not significant for where the + codeparser cache is used (i.e. when calculating variable dependencies for + code fragments.) The value is space-separated without quoting values, for + example:: + + BB_HASH_CODEPARSER_VALS = "T=/ WORKDIR=/ DATE=1234 TIME=1234" :term:`BB_CONSOLELOG` Specifies the path to a log file into which BitBake's user interface @@ -108,19 +144,23 @@ overview of their function and contents. command line option). The task name specified should not include the ``do_`` prefix. + :term:`BB_DEFAULT_UMASK` + The default umask to apply to tasks if specified and no task specific + umask flag is set. + :term:`BB_DISKMON_DIRS` Monitors disk space and available inodes during the build and allows you to control the build based on these parameters. Disk space monitoring is disabled by default. When setting this - variable, use the following form: :: + variable, use the following form:: BB_DISKMON_DIRS = "<action>,<dir>,<threshold> [...]" where: <action> is: - ABORT: Immediately abort the build when + HALT: Immediately halt the build when a threshold is broken. STOPTASKS: Stop the build after the currently executing tasks have finished when @@ -149,48 +189,48 @@ overview of their function and contents. not specify G, M, or K, Kbytes is assumed by default. Do not use GB, MB, or KB. - Here are some examples: :: + Here are some examples:: - BB_DISKMON_DIRS = "ABORT,${TMPDIR},1G,100K WARN,${SSTATE_DIR},1G,100K" + BB_DISKMON_DIRS = "HALT,${TMPDIR},1G,100K WARN,${SSTATE_DIR},1G,100K" BB_DISKMON_DIRS = "STOPTASKS,${TMPDIR},1G" - BB_DISKMON_DIRS = "ABORT,${TMPDIR},,100K" + BB_DISKMON_DIRS = "HALT,${TMPDIR},,100K" The first example works only if you also set the :term:`BB_DISKMON_WARNINTERVAL` - variable. This example causes the build system to immediately abort + variable. This example causes the build system to immediately halt when either the disk space in ``${TMPDIR}`` drops below 1 Gbyte or the available free inodes drops below 100 Kbytes. Because two directories are provided with the variable, the build system also issues a warning when the disk space in the ``${SSTATE_DIR}`` directory drops below 1 Gbyte or the number of free inodes drops below 100 Kbytes. Subsequent warnings are issued during intervals as - defined by the ``BB_DISKMON_WARNINTERVAL`` variable. + defined by the :term:`BB_DISKMON_WARNINTERVAL` variable. The second example stops the build after all currently executing tasks complete when the minimum disk space in the ``${TMPDIR}`` directory drops below 1 Gbyte. No disk monitoring occurs for the free inodes in this case. - The final example immediately aborts the build when the number of + The final example immediately halts the build when the number of free inodes in the ``${TMPDIR}`` directory drops below 100 Kbytes. No disk space monitoring for the directory itself occurs in this case. :term:`BB_DISKMON_WARNINTERVAL` 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` variable and define its action as "WARN". During the build, subsequent warnings are issued each time disk space or number of free inodes further reduces by the respective interval. - If you do not provide a ``BB_DISKMON_WARNINTERVAL`` variable and you - do use ``BB_DISKMON_DIRS`` with the "WARN" action, the disk + If you do not provide a :term:`BB_DISKMON_WARNINTERVAL` variable and you + do use :term:`BB_DISKMON_DIRS` with the "WARN" action, the disk monitoring interval defaults to the following: BB_DISKMON_WARNINTERVAL = "50M,5K" When specifying the variable in your configuration file, use the - following form: :: + following form:: BB_DISKMON_WARNINTERVAL = "<disk_space_interval>,<disk_inode_interval>" @@ -206,7 +246,7 @@ overview of their function and contents. G, M, or K for Gbytes, Mbytes, or Kbytes, respectively. You cannot use GB, MB, or KB. - Here is an example: :: + Here is an example:: BB_DISKMON_DIRS = "WARN,${SSTATE_DIR},1G,100K" BB_DISKMON_WARNINTERVAL = "50M,5K" @@ -218,23 +258,23 @@ overview of their function and contents. based on the interval occur each time a respective interval is reached beyond the initial warning (i.e. 1 Gbytes and 100 Kbytes). - :term:`BB_ENV_WHITELIST` - Specifies the internal whitelist of variables to allow through from + :term:`BB_ENV_PASSTHROUGH` + Specifies the internal list 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: :term:`BBPATH`, :term:`BB_PRESERVE_ENV`, - :term:`BB_ENV_WHITELIST`, and :term:`BB_ENV_EXTRAWHITE`. + :term:`BB_ENV_PASSTHROUGH`, and :term:`BB_ENV_PASSTHROUGH_ADDITIONS`. .. note:: You must set this variable in the external environment in order for it to work. - :term:`BB_ENV_EXTRAWHITE` - Specifies an additional set of variables to allow through (whitelist) - from the external environment into BitBake's datastore. This list of - variables are on top of the internal list set in - :term:`BB_ENV_WHITELIST`. + :term:`BB_ENV_PASSTHROUGH_ADDITIONS` + Specifies an additional set of variables to allow through from the + external environment into BitBake's datastore. This list of variables + are on top of the internal list set in + :term:`BB_ENV_PASSTHROUGH`. .. note:: @@ -250,76 +290,82 @@ overview of their function and contents. :term:`BB_FILENAME` Contains the filename of the recipe that owns the currently running task. For example, if the ``do_fetch`` task that resides in the - ``my-recipe.bb`` is executing, the ``BB_FILENAME`` variable contains + ``my-recipe.bb`` is executing, the :term:`BB_FILENAME` variable contains "/foo/path/my-recipe.bb". - :term:`BBFILES_DYNAMIC` - Activates content depending on presence of identified layers. You - identify the layers by the collections that the layers define. + :term:`BB_GENERATE_MIRROR_TARBALLS` + Causes tarballs of the Git repositories, including the Git metadata, + to be placed in the :term:`DL_DIR` directory. Anyone + wishing to create a source mirror would want to enable this variable. - Use the ``BBFILES_DYNAMIC`` variable to avoid ``.bbappend`` files whose - corresponding ``.bb`` file is in a layer that attempts to modify other - layers through ``.bbappend`` but does not want to introduce a hard - dependency on those other layers. + For performance reasons, creating and placing tarballs of the Git + repositories is not the default action by BitBake. :: - Additionally you can prefix the rule with "!" to add ``.bbappend`` and - ``.bb`` files in case a layer is not present. Use this avoid hard - dependency on those other layers. + BB_GENERATE_MIRROR_TARBALLS = "1" - Use the following form for ``BBFILES_DYNAMIC``: :: + :term:`BB_GENERATE_SHALLOW_TARBALLS` + Setting this variable to "1" when :term:`BB_GIT_SHALLOW` is also set to + "1" causes bitbake to generate shallow mirror tarballs when fetching git + repositories. The number of commits included in the shallow mirror + tarballs is controlled by :term:`BB_GIT_SHALLOW_DEPTH`. - collection_name:filename_pattern + If both :term:`BB_GIT_SHALLOW` and :term:`BB_GENERATE_MIRROR_TARBALLS` are + enabled, bitbake will generate shallow mirror tarballs by default for git + repositories. This separate variable exists so that shallow tarball + generation can be enabled without needing to also enable normal mirror + generation if it is not desired. - The following example identifies two collection names and two filename - patterns: :: + For example usage, see :term:`BB_GIT_SHALLOW`. - BBFILES_DYNAMIC += "\ - clang-layer:${LAYERDIR}/bbappends/meta-clang/*/*/*.bbappend \ - core:${LAYERDIR}/bbappends/openembedded-core/meta/*/*/*.bbappend \ - " + :term:`BB_GIT_SHALLOW` + Setting this variable to "1" enables the support for fetching, using and + generating mirror tarballs of `shallow git repositories <https://riptutorial.com/git/example/4584/shallow-clone>`_. + The external `git-make-shallow <https://git.openembedded.org/bitbake/tree/bin/git-make-shallow>`_ + script is used for shallow mirror tarball creation. - When the collection name is prefixed with "!" it will add the file pattern in case - the layer is absent: :: + When :term:`BB_GIT_SHALLOW` is enabled, bitbake will attempt to fetch a shallow + mirror tarball. If the shallow mirror tarball cannot be fetched, it will + try to fetch the full mirror tarball and use that. - BBFILES_DYNAMIC += "\ - !clang-layer:${LAYERDIR}/backfill/meta-clang/*/*/*.bb \ - " + When a mirror tarball is not available, a full git clone will be performed + regardless of whether this variable is set or not. Support for shallow + clones is not currently implemented as git does not directly support + shallow cloning a particular git commit hash (it only supports cloning + from a tag or branch reference). - This next example shows an error message that occurs because invalid - entries are found, which cause parsing to abort: :: + See also :term:`BB_GIT_SHALLOW_DEPTH` and + :term:`BB_GENERATE_SHALLOW_TARBALLS`. - ERROR: BBFILES_DYNAMIC entries must be of the form {!}<collection name>:<filename pattern>, not: - /work/my-layer/bbappends/meta-security-isafw/*/*/*.bbappend - /work/my-layer/bbappends/openembedded-core/meta/*/*/*.bbappend + Example usage:: - :term:`BB_GENERATE_MIRROR_TARBALLS` - Causes tarballs of the Git repositories, including the Git metadata, - to be placed in the :term:`DL_DIR` directory. Anyone - wishing to create a source mirror would want to enable this variable. + BB_GIT_SHALLOW ?= "1" - For performance reasons, creating and placing tarballs of the Git - repositories is not the default action by BitBake. :: + # Keep only the top commit + BB_GIT_SHALLOW_DEPTH ?= "1" - BB_GENERATE_MIRROR_TARBALLS = "1" + # This defaults to enabled if both BB_GIT_SHALLOW and + # BB_GENERATE_MIRROR_TARBALLS are enabled + BB_GENERATE_SHALLOW_TARBALLS ?= "1" - :term:`BB_HASHCONFIG_WHITELIST` - Lists variables that are excluded from base configuration checksum, - which is used to determine if the cache can be reused. + :term:`BB_GIT_SHALLOW_DEPTH` + When used with :term:`BB_GENERATE_SHALLOW_TARBALLS`, this variable sets + the number of commits to include in generated shallow mirror tarballs. + With a depth of 1, only the commit referenced in :term:`SRCREV` is + included in the shallow mirror tarball. Increasing the depth includes + additional parent commits, working back through the commit history. - One of the ways BitBake determines whether to re-parse the main - metadata is through checksums of the variables in the datastore of - the base configuration data. There are variables that you typically - want to exclude when checking whether or not to re-parse and thus - rebuild the cache. As an example, you would usually exclude ``TIME`` - and ``DATE`` because these variables are always changing. If you did - not exclude them, BitBake would never reuse the cache. + If this variable is unset, bitbake will default to a depth of 1 when + generating shallow mirror tarballs. - :term:`BB_HASHBASE_WHITELIST` - Lists variables that are excluded from checksum and dependency data. - Variables that are excluded can therefore change without affecting - the checksum mechanism. A common example would be the variable for - the path of the build. BitBake's output should not (and usually does - not) depend on the directory in which it was built. + For example usage, see :term:`BB_GIT_SHALLOW`. + + :term:`BB_GLOBAL_PYMODULES` + Specifies the list of Python modules to place in the global namespace. + It is intended that only the core layer should set this and it is meant + to be a very small list, typically just ``os`` and ``sys``. + :term:`BB_GLOBAL_PYMODULES` is expected to be set before the first + ``addpylib`` directive. + See also ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:extending python library code`". :term:`BB_HASHCHECK_FUNCTION` Specifies the name of the function to call during the "setscene" part @@ -335,12 +381,66 @@ overview of their function and contents. However, the more accurate the data returned, the more efficient the build will be. + :term:`BB_HASHCONFIG_IGNORE_VARS` + Lists variables that are excluded from base configuration checksum, + which is used to determine if the cache can be reused. + + One of the ways BitBake determines whether to re-parse the main + metadata is through checksums of the variables in the datastore of + the base configuration data. There are variables that you typically + want to exclude when checking whether or not to re-parse and thus + rebuild the cache. As an example, you would usually exclude ``TIME`` + and ``DATE`` because these variables are always changing. If you did + not exclude them, BitBake would never reuse the cache. + + :term:`BB_HASHSERVE` + Specifies the Hash Equivalence server to use. + + If set to ``auto``, BitBake automatically starts its own server + over a UNIX domain socket. An option is to connect this server + to an upstream one, by setting :term:`BB_HASHSERVE_UPSTREAM`. + + If set to ``unix://path``, BitBake will connect to an existing + hash server available over a UNIX domain socket. + + If set to ``host:port``, BitBake will connect to a remote server on the + specified host. This allows multiple clients to share the same + hash equivalence data. + + The remote server can be started manually through + the ``bin/bitbake-hashserv`` script provided by BitBake, + which supports UNIX domain sockets too. This script also allows + to start the server in read-only mode, to avoid accepting + equivalences that correspond to Share State caches that are + only available on specific clients. + + :term:`BB_HASHSERVE_UPSTREAM` + Specifies an upstream Hash Equivalence server. + + This optional setting is only useful when a local Hash Equivalence + server is started (setting :term:`BB_HASHSERVE` to ``auto``), + and you wish the local server to query an upstream server for + Hash Equivalence data. + + Example usage:: + + BB_HASHSERVE_UPSTREAM = "hashserv.yocto.io:8687" + :term:`BB_INVALIDCONF` Used in combination with the ``ConfigParsed`` event to trigger re-parsing the base metadata (i.e. all the recipes). The ``ConfigParsed`` event can set the variable to trigger the re-parse. You must be careful to avoid recursive loops with this functionality. + :term:`BB_LOADFACTOR_MAX` + Setting this to a value will cause BitBake to check the system load + average before executing new tasks. If the load average is above the + the number of CPUs multipled by this factor, no new task will be started + unless there is no task executing. A value of "1.5" has been found to + work reasonably. This is helpful for systems which don't have pressure + regulation enabled, which is more granular. Pressure values take + precedence over loadfactor. + :term:`BB_LOGCONFIG` Specifies the name of a config file that contains the user logging configuration. See @@ -349,15 +449,28 @@ overview of their function and contents. :term:`BB_LOGFMT` Specifies the name of the log files saved into - ``${``\ :term:`T`\ ``}``. By default, the ``BB_LOGFMT`` - variable is undefined and the log file names get created using the - following form: :: + ``${``\ :term:`T`\ ``}``. By default, the :term:`BB_LOGFMT` + variable is undefined and the log filenames get created using the + following form:: log.{task}.{pid} If you want to force log files to take a specific name, you can set this variable in a configuration file. + :term:`BB_MULTI_PROVIDER_ALLOWED` + Allows you to suppress BitBake warnings caused when building two + separate recipes that provide the same output. + + BitBake normally issues a warning when building two different recipes + where each provides the same output. This scenario is usually + something the user does not want. However, cases do exist where it + makes sense, particularly in the ``virtual/*`` namespace. You can use + this variable to suppress BitBake's warnings. + + To use the variable, list provider names (e.g. recipe names, + ``virtual/kernel``, and so forth). + :term:`BB_NICE_LEVEL` Allows BitBake to run at a specific priority (i.e. nice level). System permissions usually mean that BitBake can reduce its priority @@ -373,19 +486,20 @@ overview of their function and contents. running builds when not connected to the Internet, and when operating in certain kinds of firewall environments. + :term:`BB_NUMBER_PARSE_THREADS` + Sets the number of threads BitBake uses when parsing. By default, the + number of threads is equal to the number of cores on the system. + :term:`BB_NUMBER_THREADS` The maximum number of tasks BitBake should run in parallel at any one time. If your host development system supports multiple cores, a good rule of thumb is to set this variable to twice the number of cores. - :term:`BB_NUMBER_PARSE_THREADS` - Sets the number of threads BitBake uses when parsing. By default, the - number of threads is equal to the number of cores on the system. - :term:`BB_ORIGENV` Contains a copy of the original external environment in which BitBake - was run. The copy is taken before any whitelisted variable values are - filtered into BitBake's datastore. + was run. The copy is taken before any variable values configured to + pass through from the external environment are filtered into BitBake's + datastore. .. note:: @@ -393,21 +507,72 @@ overview of their function and contents. queried using the normal datastore operations. :term:`BB_PRESERVE_ENV` - Disables whitelisting and instead allows all variables through from - the external environment into BitBake's datastore. + Disables environment filtering and instead allows all variables through + from the external environment into BitBake's datastore. .. note:: You must set this variable in the external environment in order for it to work. + :term:`BB_PRESSURE_MAX_CPU` + Specifies a maximum CPU pressure threshold, above which BitBake's + scheduler will not start new tasks (providing there is at least + one active task). If no value is set, CPU pressure is not + monitored when starting tasks. + + The pressure data is calculated based upon what Linux kernels since + version 4.20 expose under ``/proc/pressure``. The threshold represents + the difference in "total" pressure from the previous second. The + minimum value is 1.0 (extremely slow builds) and the maximum is + 1000000 (a pressure value unlikely to ever be reached). + + This threshold can be set in ``conf/local.conf`` as:: + + BB_PRESSURE_MAX_CPU = "500" + + :term:`BB_PRESSURE_MAX_IO` + Specifies a maximum I/O pressure threshold, above which BitBake's + scheduler will not start new tasks (providing there is at least + one active task). If no value is set, I/O pressure is not + monitored when starting tasks. + + The pressure data is calculated based upon what Linux kernels since + version 4.20 expose under ``/proc/pressure``. The threshold represents + the difference in "total" pressure from the previous second. The + minimum value is 1.0 (extremely slow builds) and the maximum is + 1000000 (a pressure value unlikely to ever be reached). + + At this point in time, experiments show that IO pressure tends to + be short-lived and regulating just the CPU with + :term:`BB_PRESSURE_MAX_CPU` can help to reduce it. + + :term:`BB_PRESSURE_MAX_MEMORY` + + Specifies a maximum memory pressure threshold, above which BitBake's + scheduler will not start new tasks (providing there is at least + one active task). If no value is set, memory pressure is not + monitored when starting tasks. + + The pressure data is calculated based upon what Linux kernels since + version 4.20 expose under ``/proc/pressure``. The threshold represents + the difference in "total" pressure from the previous second. The + minimum value is 1.0 (extremely slow builds) and the maximum is + 1000000 (a pressure value unlikely to ever be reached). + + Memory pressure is experienced when time is spent swapping, + refaulting pages from the page cache or performing direct reclaim. + This is why memory pressure is rarely seen, but setting this variable + might be useful as a last resort to prevent OOM errors if they are + occurring during builds. + :term:`BB_RUNFMT` Specifies the name of the executable script files (i.e. run files) saved into ``${``\ :term:`T`\ ``}``. By default, the - ``BB_RUNFMT`` variable is undefined and the run file names get - created using the following form: :: + :term:`BB_RUNFMT` variable is undefined and the run filenames get + created using the following form:: - run.{task}.{pid} + run.{func}.{pid} If you want to force run files to take a specific name, you can set this variable in a configuration file. @@ -421,14 +586,14 @@ overview of their function and contents. Selects the name of the scheduler to use for the scheduling of BitBake tasks. Three options exist: - - *basic* - The basic framework from which everything derives. Using + - *basic* --- the basic framework from which everything derives. Using this option causes tasks to be ordered numerically as they are parsed. - - *speed* - Executes tasks first that have more tasks depending on + - *speed* --- executes tasks first that have more tasks depending on them. The "speed" option is the default. - - *completion* - Causes the scheduler to try to complete a given + - *completion* --- causes the scheduler to try to complete a given recipe once its build has started. :term:`BB_SCHEDULERS` @@ -448,17 +613,6 @@ overview of their function and contents. The function specified by this variable returns a "True" or "False" depending on whether the dependency needs to be met. - :term:`BB_SETSCENE_VERIFY_FUNCTION2` - Specifies a function to call that verifies the list of planned task - execution before the main task execution happens. The function is - called once BitBake has a list of setscene tasks that have run and - either succeeded or failed. - - The function allows for a task list check to see if they make sense. - Even if BitBake was planning to skip a task, the returned value of - the function can force BitBake to run the task, which is necessary - under certain metadata defined circumstances. - :term:`BB_SIGNATURE_EXCLUDE_FLAGS` Lists variable flags (varflags) that can be safely excluded from checksum and dependency data for keys in the datastore. When @@ -481,40 +635,17 @@ overview of their function and contents. :term:`BB_SRCREV_POLICY` Defines the behavior of the fetcher when it interacts with source control systems and dynamic source revisions. The - ``BB_SRCREV_POLICY`` variable is useful when working without a + :term:`BB_SRCREV_POLICY` variable is useful when working without a network. The variable can be set using one of two policies: - - *cache* - Retains the value the system obtained previously rather + - *cache* --- retains the value the system obtained previously rather than querying the source control system each time. - - *clear* - Queries the source controls system every time. With this + - *clear* --- queries the source controls system every time. With this policy, there is no cache. The "clear" policy is the default. - :term:`BB_STAMP_POLICY` - Defines the mode used for how timestamps of stamp files are compared. - You can set the variable to one of the following modes: - - - *perfile* - Timestamp comparisons are only made between timestamps - of a specific recipe. This is the default mode. - - - *full* - Timestamp comparisons are made for all dependencies. - - - *whitelist* - Identical to "full" mode except timestamp - comparisons are made for recipes listed in the - :term:`BB_STAMP_WHITELIST` variable. - - .. note:: - - Stamp policies are largely obsolete with the introduction of - setscene tasks. - - :term:`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 :term:`BB_STAMP_POLICY` variable. - :term:`BB_STRICT_CHECKSUM` Sets a more strict checksum mechanism for non-local URLs. Setting this variable to a value causes BitBake to report an error if it @@ -525,7 +656,7 @@ overview of their function and contents. Allows adjustment of a task's Input/Output priority. During Autobuilder testing, random failures can occur for tasks due to I/O starvation. These failures occur during various QEMU runtime - timeouts. You can use the ``BB_TASK_IONICE_LEVEL`` variable to adjust + timeouts. You can use the :term:`BB_TASK_IONICE_LEVEL` variable to adjust the I/O priority of these tasks. .. note:: @@ -533,7 +664,7 @@ overview of their function and contents. This variable works similarly to the :term:`BB_TASK_NICE_LEVEL` variable except with a task's I/O priorities. - Set the variable as follows: :: + Set the variable as follows:: BB_TASK_IONICE_LEVEL = "class.prio" @@ -551,7 +682,7 @@ overview of their function and contents. In order for your I/O priority settings to take effect, you need the Completely Fair Queuing (CFQ) Scheduler selected for the backing block device. To select the scheduler, use the following command form where - device is the device (e.g. sda, sdb, and so forth): :: + device is the device (e.g. sda, sdb, and so forth):: $ sudo sh -c "echo cfq > /sys/block/device/queu/scheduler" @@ -560,7 +691,7 @@ overview of their function and contents. You can use this variable in combination with task overrides to raise or lower priorities of specific tasks. For example, on the `Yocto - Project <http://www.yoctoproject.org>`__ autobuilder, QEMU emulation + Project <https://www.yoctoproject.org>`__ autobuilder, QEMU emulation in images is given a higher priority as compared to build tasks to ensure that images do not suffer timeouts on loaded systems. @@ -592,20 +723,20 @@ overview of their function and contents. To build a different variant of the recipe with a minimal amount of code, it usually is as simple as adding the variable to your recipe. Here are two examples. The "native" variants are from the - OpenEmbedded-Core metadata: :: + OpenEmbedded-Core metadata:: BBCLASSEXTEND =+ "native nativesdk" BBCLASSEXTEND =+ "multilib:multilib_name" .. note:: - Internally, the ``BBCLASSEXTEND`` mechanism generates recipe + Internally, the :term:`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 :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 possible to include a different file depending on the variant, since ``include`` statements are processed when the recipe is @@ -638,17 +769,17 @@ overview of their function and contents. This variable is useful in situations where the same recipe appears in more than one layer. Setting this variable allows you to prioritize a layer against other layers that contain the same recipe - - effectively letting you control the precedence for the multiple + --- effectively letting you control the precedence for the multiple layers. The precedence established through this variable stands 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 + For example, a layer that has a recipe with a higher :term:`PV` value but + for which the :term:`BBFILE_PRIORITY` is set to have a lower precedence still has a lower precedence. - A larger value for the ``BBFILE_PRIORITY`` variable results in a + A larger value for the :term:`BBFILE_PRIORITY` variable results in a higher precedence. For example, the value 6 has a higher precedence - than the value 5. If not specified, the ``BBFILE_PRIORITY`` variable - is set based on layer dependencies (see the ``LAYERDEPENDS`` variable + than the value 5. If not specified, the :term:`BBFILE_PRIORITY` variable + is set based on layer dependencies (see the :term:`LAYERDEPENDS` variable for more information. The default priority, if unspecified for a layer with no dependencies, is the lowest defined priority + 1 (or 1 if no priorities are defined). @@ -667,6 +798,45 @@ overview of their function and contents. For details on the syntax, see the documentation by following the previous link. + :term:`BBFILES_DYNAMIC` + Activates content depending on presence of identified layers. You + identify the layers by the collections that the layers define. + + Use the :term:`BBFILES_DYNAMIC` variable to avoid ``.bbappend`` files whose + corresponding ``.bb`` file is in a layer that attempts to modify other + layers through ``.bbappend`` but does not want to introduce a hard + dependency on those other layers. + + Additionally you can prefix the rule with "!" to add ``.bbappend`` and + ``.bb`` files in case a layer is not present. Use this avoid hard + dependency on those other layers. + + Use the following form for :term:`BBFILES_DYNAMIC`:: + + collection_name:filename_pattern + + The following example identifies two collection names and two filename + patterns:: + + BBFILES_DYNAMIC += "\ + clang-layer:${LAYERDIR}/bbappends/meta-clang/*/*/*.bbappend \ + core:${LAYERDIR}/bbappends/openembedded-core/meta/*/*/*.bbappend \ + " + + When the collection name is prefixed with "!" it will add the file pattern in case + the layer is absent:: + + BBFILES_DYNAMIC += "\ + !clang-layer:${LAYERDIR}/backfill/meta-clang/*/*/*.bb \ + " + + This next example shows an error message that occurs because invalid + entries are found, which cause parsing to fail:: + + ERROR: BBFILES_DYNAMIC entries must be of the form {!}<collection name>:<filename pattern>, not: + /work/my-layer/bbappends/meta-security-isafw/*/*/*.bbappend + /work/my-layer/bbappends/openembedded-core/meta/*/*/*.bbappend + :term:`BBINCLUDED` Contains a space-separated list of all of all files that BitBake's parser included during parsing of the current file. @@ -678,13 +848,13 @@ overview of their function and contents. :term:`BBINCLUDELOGS_LINES` 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``, + reporting a failed task. If you do not set :term:`BBINCLUDELOGS_LINES`, the entire log is printed. :term:`BBLAYERS` Lists the layers to enable during the build. This variable is defined in the ``bblayers.conf`` configuration file in the build directory. - Here is an example: :: + Here is an example:: BBLAYERS = " \ /home/scottrif/poky/meta \ @@ -704,7 +874,7 @@ overview of their function and contents. :term:`BBMASK` 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 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 @@ -718,13 +888,13 @@ overview of their function and contents. The following example uses a complete regular expression to tell BitBake to ignore all recipe and recipe append files in the - ``meta-ti/recipes-misc/`` directory: :: + ``meta-ti/recipes-misc/`` directory:: BBMASK = "meta-ti/recipes-misc/" If you want to mask out multiple directories or recipes, you can specify multiple regular expression fragments. This next example - masks out multiple directories and individual recipes: :: + masks out multiple directories and individual recipes:: BBMASK += "/meta-ti/recipes-misc/ meta-ti/recipes-ti/packagegroup/" BBMASK += "/meta-oe/recipes-support/" @@ -741,11 +911,11 @@ overview of their function and contents. Enables BitBake to perform multiple configuration builds and lists each separate configuration (multiconfig). You can use this variable to cause BitBake to build multiple targets where each target has a - separate configuration. Define ``BBMULTICONFIG`` in your + separate configuration. Define :term:`BBMULTICONFIG` in your ``conf/local.conf`` configuration file. As an example, the following line specifies three multiconfigs, each - having a separate configuration file: :: + having a separate configuration file:: BBMULTIFONFIG = "configA configB configC" @@ -753,20 +923,20 @@ overview of their function and contents. build directory within a directory named ``conf/multiconfig`` (e.g. build_directory\ ``/conf/multiconfig/configA.conf``). - For information on how to use ``BBMULTICONFIG`` in an environment + For information on how to use :term:`BBMULTICONFIG` in an environment that supports building targets with multiple configurations, see the ":ref:`bitbake-user-manual/bitbake-user-manual-intro:executing a multiple configuration build`" section. :term:`BBPATH` - Used by BitBake to locate class (``.bbclass``) and configuration - (``.conf``) files. This variable is analogous to the ``PATH`` - variable. + A colon-separated list used by BitBake to locate class (``.bbclass``) + and configuration (``.conf``) files. This variable is analogous to the + ``PATH`` variable. If you run BitBake from a directory outside of the build directory, - you must be sure to set ``BBPATH`` to point to the build directory. + 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 - BitBake: :: + BitBake:: $ BBPATH="build_directory" $ export BBPATH @@ -780,16 +950,6 @@ overview of their function and contents. Allows you to use a configuration file to add to the list of command-line target recipes you want to build. - :term:`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 :term:`OVERRIDES` mechanism for a - single version or for an optionally named range of versions. - - For more information on ``BBVERSIONS``, see the - ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:variants - class extension mechanism`" - section. - :term:`BITBAKE_UI` Used to specify the UI module to use when running BitBake. Using this variable is equivalent to using the ``-u`` command-line option. @@ -821,7 +981,7 @@ overview of their function and contents. The most common usage of this is variable is to set it to "-1" within a recipe for a development version of a piece of software. Using the variable in this way causes the stable version of the recipe to build - by default in the absence of ``PREFERRED_VERSION`` being used to + by default in the absence of :term:`PREFERRED_VERSION` being used to build the development version. .. note:: @@ -834,8 +994,8 @@ overview of their function and contents. Lists a recipe's build-time dependencies (i.e. other recipe files). Consider this simple example for two recipes named "a" and "b" that - produce similarly named packages. In this example, the ``DEPENDS`` - statement appears in the "a" recipe: :: + produce similarly named packages. In this example, the :term:`DEPENDS` + statement appears in the "a" recipe:: DEPENDS = "b" @@ -852,7 +1012,7 @@ overview of their function and contents. :term:`DL_DIR` 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 repositories, use the :term:`BB_GENERATE_MIRROR_TARBALLS` variable. @@ -863,18 +1023,18 @@ overview of their function and contents. ``bblayers.conf`` configuration file. To exclude a recipe from a world build using this variable, set the - variable to "1" in the recipe. + variable to "1" in the recipe. Set it to "0" to add it back to world build. .. 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 - 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. :term:`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 the glossary for more information. @@ -921,6 +1081,11 @@ overview of their function and contents. environment variable. The value is a colon-separated list of directories that are searched left-to-right in order. + :term:`FILE_LAYERNAME` + During parsing and task execution, this is set to the name of the + layer containing the recipe file. Code can use this to identify which + layer a recipe is from. + :term:`GITDIR` The directory in which a local copy of a Git repository is stored when it is cloned. @@ -937,9 +1102,9 @@ overview of their function and contents. Causes the named class or classes to be inherited globally. Anonymous functions in the class or classes are not executed for the base configuration and in each individual recipe. The OpenEmbedded build - system ignores changes to ``INHERIT`` in individual recipes. + 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`" section. @@ -969,6 +1134,29 @@ overview of their function and contents. variable is not available outside of ``layer.conf`` and references are expanded immediately when parsing of the file completes. + :term:`LAYERSERIES_COMPAT` + Lists the versions of the OpenEmbedded-Core (OE-Core) for which + a layer is compatible. Using the :term:`LAYERSERIES_COMPAT` variable + allows the layer maintainer to indicate which combinations of the + layer and OE-Core can be expected to work. The variable gives the + system a way to detect when a layer has not been tested with new + releases of OE-Core (e.g. the layer is not maintained). + + To specify the OE-Core versions for which a layer is compatible, use + this variable in your layer's ``conf/layer.conf`` configuration file. + For the list, use the Yocto Project release name (e.g. "kirkstone", + "mickledore"). To specify multiple OE-Core versions for the layer, use + a space-separated list:: + + LAYERSERIES_COMPAT_layer_root_name = "kirkstone mickledore" + + .. note:: + + Setting :term:`LAYERSERIES_COMPAT` is required by the Yocto Project + Compatible version 2 standard. + The OpenEmbedded build system produces a warning if the variable + is not set for any given layer. + :term:`LAYERVERSION` Optionally specifies the version of a layer as a single number. You can use this variable within @@ -987,29 +1175,16 @@ 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 :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. - :term:`MULTI_PROVIDER_WHITELIST` - Allows you to suppress BitBake warnings caused when building two - separate recipes that provide the same output. - - BitBake normally issues a warning when building two different recipes - where each provides the same output. This scenario is usually - something the user does not want. However, cases do exist where it - makes sense, particularly in the ``virtual/*`` namespace. You can use - this variable to suppress BitBake's warnings. - - To use the variable, list provider names (e.g. recipe names, - ``virtual/kernel``, and so forth). - :term:`OVERRIDES` - BitBake uses ``OVERRIDES`` to control what variables are overridden - after BitBake parses recipes and configuration files. + A colon-separated list that BitBake uses to control what variables are + overridden after BitBake parses recipes and configuration files. Following is a simple example that uses an overrides list based on machine architectures: OVERRIDES = "arm:x86:mips:powerpc" You can - find information on how to use ``OVERRIDES`` in the + find information on how to use :term:`OVERRIDES` in the ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:conditional syntax (overrides)`" section. @@ -1023,11 +1198,11 @@ overview of their function and contents. :term:`PACKAGES_DYNAMIC` A promise that your recipe satisfies runtime dependencies for optional modules that are found in other recipes. - ``PACKAGES_DYNAMIC`` does not actually satisfy the dependencies, it + :term:`PACKAGES_DYNAMIC` does not actually satisfy the dependencies, it only states that they should be satisfied. For example, if a hard, 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 + :term:`PACKAGES_DYNAMIC` variable, but a package with the module name is never actually produced, then the other package will be broken. :term:`PE` @@ -1057,7 +1232,7 @@ overview of their function and contents. 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 :term:`PN` of the recipe to which you want to give - precedence. Some examples: :: + precedence. Some examples:: PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto" PREFERRED_PROVIDER_virtual/xserver = "xserver-xf86" @@ -1066,30 +1241,30 @@ overview of their function and contents. :term:`PREFERRED_PROVIDERS` Determines which recipe should be given preference for cases where multiple recipes provide the same item. Functionally, - ``PREFERRED_PROVIDERS`` is identical to - :term:`PREFERRED_PROVIDER`. However, the ``PREFERRED_PROVIDERS`` variable + :term:`PREFERRED_PROVIDERS` is identical to + :term:`PREFERRED_PROVIDER`. However, the :term:`PREFERRED_PROVIDERS` variable lets you define preferences for multiple situations using the following - form: :: + form:: PREFERRED_PROVIDERS = "xxx:yyy aaa:bbb ..." - This form is a convenient replacement for the following: :: + This form is a convenient replacement for the following:: PREFERRED_PROVIDER_xxx = "yyy" PREFERRED_PROVIDER_aaa = "bbb" :term:`PREFERRED_VERSION` - If there are multiple versions of recipes available, this variable - determines which recipe should be given preference. You must always + If there are multiple versions of a recipe available, this variable + determines which version should be given preference. You must always 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 + The :term:`PREFERRED_VERSION` variable supports limited wildcard use through the "``%``" character. You can use the character to match any number of characters, which can be useful when specifying versions that contain long revision numbers that potentially change. Here are - two examples: :: + two examples:: PREFERRED_VERSION_python = "2.7.3" PREFERRED_VERSION_linux-yocto = "4.12%" @@ -1100,22 +1275,26 @@ overview of their function and contents. end of the string. You cannot use the wildcard character in any other location of the string. + If a recipe with the specified version is not available, a warning + message will be shown. See :term:`REQUIRED_VERSION` if you want this + to be an error instead. + :term:`PREMIRRORS` Specifies additional paths from which BitBake gets source code. When the build system searches for source code, it first tries the local download directory. If that location fails, the build system tries - locations defined by ``PREMIRRORS``, the upstream source, and then + locations defined by :term:`PREMIRRORS`, the upstream source, and then locations specified by :term:`MIRRORS` in that order. Typically, you would add a specific server for the build system to attempt before any others by adding something like the following to - your configuration: :: + your configuration:: - PREMIRRORS_prepend = "\ - git://.*/.* http://www.yoctoproject.org/sources/ \n \ - ftp://.*/.* http://www.yoctoproject.org/sources/ \n \ - http://.*/.* http://www.yoctoproject.org/sources/ \n \ - https://.*/.* http://www.yoctoproject.org/sources/ \n" + PREMIRRORS:prepend = "\ + git://.*/.* http://downloads.yoctoproject.org/mirror/sources/ \ + ftp://.*/.* http://downloads.yoctoproject.org/mirror/sources/ \ + http://.*/.* http://downloads.yoctoproject.org/mirror/sources/ \ + https://.*/.* http://downloads.yoctoproject.org/mirror/sources/" These changes cause the build system to intercept Git, FTP, HTTP, and HTTPS requests and direct them to the ``http://`` sources mirror. You can @@ -1124,25 +1303,25 @@ overview of their function and contents. :term:`PROVIDES` A list of aliases by which a particular recipe can be known. By - default, a recipe's own ``PN`` is implicitly already in its - ``PROVIDES`` list. If a recipe uses ``PROVIDES``, the additional + default, a recipe's own :term:`PN` is implicitly already in its + :term:`PROVIDES` list. If a recipe uses :term:`PROVIDES`, the additional aliases are synonyms for the recipe and can be useful satisfying dependencies of other recipes during the build as specified by - ``DEPENDS``. + :term:`DEPENDS`. - Consider the following example ``PROVIDES`` statement from a recipe - file ``libav_0.8.11.bb``: :: + Consider the following example :term:`PROVIDES` statement from a recipe + file ``libav_0.8.11.bb``:: 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". 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 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 virtual target in :term:`DEPENDS` to leave the choice of provider open. @@ -1154,12 +1333,12 @@ overview of their function and contents. :term:`PRSERV_HOST` 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" 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. :term:`PV` @@ -1171,26 +1350,26 @@ overview of their function and contents. a package in this list cannot be found during the build, you will get a build error. - Because the ``RDEPENDS`` variable applies to packages being built, + Because the :term:`RDEPENDS` variable applies to packages being built, you should always use the variable in a form with an attached package name. For example, suppose you are building a development package that depends on the ``perl`` package. In this case, you would use the - following ``RDEPENDS`` statement: :: + following :term:`RDEPENDS` statement:: - RDEPENDS_${PN}-dev += "perl" + RDEPENDS:${PN}-dev += "perl" In the example, the development package depends on the ``perl`` package. - Thus, the ``RDEPENDS`` variable has the ``${PN}-dev`` package name as part + Thus, the :term:`RDEPENDS` variable has the ``${PN}-dev`` package name as part of the variable. BitBake supports specifying versioned dependencies. Although the syntax varies depending on the packaging format, BitBake hides these differences from you. Here is the general syntax to specify versions - with the ``RDEPENDS`` variable: :: + with the :term:`RDEPENDS` variable:: - RDEPENDS_${PN} = "package (operator version)" + RDEPENDS:${PN} = "package (operator version)" - For ``operator``, you can specify the following: :: + For ``operator``, you can specify the following:: = < @@ -1199,9 +1378,9 @@ overview of their function and contents. >= For example, the following sets up a dependency on version 1.2 or - greater of the package ``foo``: :: + greater of the package ``foo``:: - RDEPENDS_${PN} = "foo (>= 1.2)" + RDEPENDS:${PN} = "foo (>= 1.2)" For information on build-time dependencies, see the :term:`DEPENDS` variable. @@ -1210,33 +1389,43 @@ overview of their function and contents. The directory in which a local copy of a ``google-repo`` directory is stored when it is synced. + :term:`REQUIRED_VERSION` + If there are multiple versions of a recipe available, this variable + determines which version should be given preference. :term:`REQUIRED_VERSION` + works in exactly the same manner as :term:`PREFERRED_VERSION`, except + that if the specified version is not available then an error message + is shown and the build fails immediately. + + If both :term:`REQUIRED_VERSION` and :term:`PREFERRED_VERSION` are set for + the same recipe, the :term:`REQUIRED_VERSION` value applies. + :term:`RPROVIDES` A list of package name aliases that a package also provides. These aliases are useful for satisfying runtime dependencies of other packages both during the build and on the target (as specified by - ``RDEPENDS``). + :term:`RDEPENDS`). As with all package-controlling variables, you must always use the variable in conjunction with a package name override. Here is an - example: :: + example:: - RPROVIDES_${PN} = "widget-abi-2" + RPROVIDES:${PN} = "widget-abi-2" :term:`RRECOMMENDS` A list of packages that extends the usability of a package being built. The package being built does not depend on this list of packages in order to successfully build, but needs them for the extended usability. To specify runtime dependencies for packages, see - the ``RDEPENDS`` variable. + the :term:`RDEPENDS` variable. BitBake supports specifying versioned recommends. Although the syntax varies depending on the packaging format, BitBake hides these differences from you. Here is the general syntax to specify versions - with the ``RRECOMMENDS`` variable: :: + with the :term:`RRECOMMENDS` variable:: - RRECOMMENDS_${PN} = "package (operator version)" + RRECOMMENDS:${PN} = "package (operator version)" - For ``operator``, you can specify the following: :: + For ``operator``, you can specify the following:: = < @@ -1245,76 +1434,114 @@ overview of their function and contents. >= For example, the following sets up a recommend on version - 1.2 or greater of the package ``foo``: :: + 1.2 or greater of the package ``foo``:: - RRECOMMENDS_${PN} = "foo (>= 1.2)" + RRECOMMENDS:${PN} = "foo (>= 1.2)" :term:`SECTION` The section in which packages should be categorized. :term:`SRC_URI` - 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 example, if the recipe or append file needs to fetch a single tarball - from the Internet, the recipe or append file uses a ``SRC_URI`` entry - that specifies that tarball. On the other hand, if the recipe or - append file needs to fetch a tarball and include a custom file, the - recipe or append file needs an ``SRC_URI`` variable that specifies - all those sources. - - The following list explains the available URI protocols: + 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 + append file needs to fetch a tarball, apply two patches, and include + a custom file, the recipe or append file needs an :term:`SRC_URI` + variable that specifies all those sources. + + The following list explains the available URI protocols. URI + protocols are highly dependent on particular BitBake Fetcher + submodules. Depending on the fetcher BitBake uses, various URL + parameters are employed. For specifics on the supported Fetchers, see + the :ref:`bitbake-user-manual/bitbake-user-manual-fetching:fetchers` + section. - - ``file://`` : Fetches files, which are usually files shipped - with the metadata, from the local machine. The path is relative to - the :term:`FILESPATH` variable. + - ``az://``: Fetches files from an Azure Storage account using HTTPS. - - ``bzr://`` : Fetches files from a Bazaar revision control + - ``bzr://``: Fetches files from a Bazaar revision control repository. - - ``git://`` : Fetches files from a Git revision control + - ``ccrc://``: Fetches files from a ClearCase repository. + + - ``cvs://``: Fetches files from a CVS revision control repository. - - ``osc://`` : Fetches files from an OSC (OpenSUSE Build service) - revision control repository. + - ``file://``: Fetches files, which are usually files shipped + with the Metadata, from the local machine. + The path is relative to the :term:`FILESPATH` + variable. Thus, the build system searches, in order, from the + following directories, which are assumed to be a subdirectories of + the directory in which the recipe file (``.bb``) or append file + (``.bbappend``) resides: - - ``repo://`` : Fetches files from a repo (Git) repository. + - ``${BPN}``: the base recipe name without any special suffix + or version numbers. - - ``http://`` : Fetches files from the Internet using HTTP. + - ``${BP}`` - ``${BPN}-${PV}``: the base recipe name and + version but without any special package name suffix. - - ``https://`` : Fetches files from the Internet using HTTPS. + - ``files``: files within a directory, which is named ``files`` + and is also alongside the recipe or append file. - - ``ftp://`` : Fetches files from the Internet using FTP. + - ``ftp://``: Fetches files from the Internet using FTP. - - ``cvs://`` : Fetches files from a CVS revision control + - ``git://``: Fetches files from a Git revision control repository. - - ``hg://`` : Fetches files from a Mercurial (``hg``) revision + - ``gitsm://``: Fetches submodules from a Git revision control + repository. + + - ``hg://``: Fetches files from a Mercurial (``hg``) revision control repository. - - ``p4://`` : Fetches files from a Perforce (``p4``) revision + - ``http://``: Fetches files from the Internet using HTTP. + + - ``https://``: Fetches files from the Internet using HTTPS. + + - ``npm://``: Fetches JavaScript modules from a registry. + + - ``osc://``: Fetches files from an OSC (OpenSUSE Build service) + revision control repository. + + - ``p4://``: Fetches files from a Perforce (``p4``) revision control repository. - - ``ssh://`` : Fetches files from a secure shell. + - ``repo://``: Fetches files from a repo (Git) repository. + + - ``ssh://``: Fetches files from a secure shell. - - ``svn://`` : Fetches files from a Subversion (``svn``) revision + - ``svn://``: Fetches files from a Subversion (``svn``) revision control repository. Here are some additional options worth mentioning: - - ``unpack`` : Controls whether or not to unpack the file if it is - an archive. The default action is to unpack the file. + - ``downloadfilename``: Specifies the filename used when storing + the downloaded file. + + - ``name``: Specifies a name to be used for association with + :term:`SRC_URI` checksums or :term:`SRCREV` when you have more than one + file or git repository specified in :term:`SRC_URI`. For example:: + + SRC_URI = "git://example.com/foo.git;branch=main;name=first \ + git://example.com/bar.git;branch=main;name=second \ + http://example.com/file.tar.gz;name=third" - - ``subdir`` : Places the file (or extracts its contents) into the + SRCREV_first = "f1d2d2f924e986ac86fdf7b36c94bcdf32beec15" + SRCREV_second = "e242ed3bffccdf271b7fbaf34ed72d089537b42f" + SRC_URI[third.sha256sum] = "13550350a8681c84c861aac2e5b440161c2b33a3e4f302ac680ca5b686de48de" + + - ``subdir``: Places the file (or extracts its contents) into the specified subdirectory. This option is useful for unusual tarballs or other archives that do not have their files already in a subdirectory within the archive. - - ``name`` : Specifies a name to be used for association with - ``SRC_URI`` checksums when you have more than one file specified - in ``SRC_URI``. + - ``subpath``: Limits the checkout to a specific subpath of the + tree when using the Git fetcher is used. - - ``downloadfilename`` : Specifies the filename used when storing - the downloaded file. + - ``unpack``: Controls whether or not to unpack the file if it is + an archive. The default action is to unpack the file. :term:`SRCDATE` The date of the source code used to build the package. This variable @@ -1326,7 +1553,7 @@ overview of their function and contents. variable applies only when using Subversion, Git, Mercurial and Bazaar. If you want to build a fixed revision and you want to avoid performing a query on the remote repository every time BitBake parses - your recipe, you should specify a ``SRCREV`` that is a full revision + your recipe, you should specify a :term:`SRCREV` that is a full revision identifier and not just a tag. :term:`SRCREV_FORMAT` @@ -1335,10 +1562,10 @@ overview of their function and contents. :term:`SRC_URI`. The system needs help constructing these values under these - circumstances. Each component in the ``SRC_URI`` is assigned a name - and these are referenced in the ``SRCREV_FORMAT`` variable. Consider + circumstances. Each component in the :term:`SRC_URI` is assigned a name + and these are referenced in the :term:`SRCREV_FORMAT` variable. Consider an example with URLs named "machine" and "meta". In this case, - ``SRCREV_FORMAT`` could look like "machine_meta" and those names + :term:`SRCREV_FORMAT` could look like "machine_meta" and those names would have the SCM versions substituted into each position. Only one ``AUTOINC`` placeholder is added and if needed. And, this placeholder is placed at the start of the returned string. @@ -1350,7 +1577,7 @@ overview of their function and contents. :term:`STAMPCLEAN` 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 remove. BitBake uses a clean operation to remove any other stamps it should be removing when creating a new stamp. diff --git a/bitbake/doc/conf.py b/bitbake/doc/conf.py index 354dff36f7..fc2ee08111 100644 --- a/bitbake/doc/conf.py +++ b/bitbake/doc/conf.py @@ -14,6 +14,7 @@ # import sys # sys.path.insert(0, os.path.abspath('.')) +import sys import datetime current_version = "dev" diff --git a/bitbake/doc/index.rst b/bitbake/doc/index.rst index 3ff8b1580f..ee1660ac15 100644 --- a/bitbake/doc/index.rst +++ b/bitbake/doc/index.rst @@ -13,6 +13,7 @@ BitBake User Manual bitbake-user-manual/bitbake-user-manual-intro bitbake-user-manual/bitbake-user-manual-execution bitbake-user-manual/bitbake-user-manual-metadata + bitbake-user-manual/bitbake-user-manual-ref-variables-context bitbake-user-manual/bitbake-user-manual-fetching bitbake-user-manual/bitbake-user-manual-ref-variables bitbake-user-manual/bitbake-user-manual-hello diff --git a/bitbake/doc/releases.rst b/bitbake/doc/releases.rst index d68d71599c..b38b1c0652 100644 --- a/bitbake/doc/releases.rst +++ b/bitbake/doc/releases.rst @@ -1,32 +1,76 @@ .. SPDX-License-Identifier: CC-BY-2.5 -========================= - Current Release Manuals -========================= +================================= +BitBake Supported Release Manuals +================================= + +******************************* +Release Series 4.2 (mickledore) +******************************* + +- :yocto_docs:`BitBake 2.4 User Manual </bitbake/2.4/>` + +****************************** +Release Series 4.0 (kirkstone) +****************************** + +- :yocto_docs:`BitBake 2.0 User Manual </bitbake/2.0/>` **************************** -3.1 'dunfell' Release Series +Release Series 3.1 (dunfell) **************************** +- :yocto_docs:`BitBake 1.46 User Manual </bitbake/1.46/>` + +================================ +BitBake Outdated Release Manuals +================================ + +***************************** +Release Series 4.1 (langdale) +***************************** + +- :yocto_docs:`BitBake 2.2 User Manual </bitbake/2.2/>` + +****************************** +Release Series 3.4 (honister) +****************************** + +- :yocto_docs:`BitBake 1.52 User Manual </bitbake/1.52/>` + +****************************** +Release Series 3.3 (hardknott) +****************************** + +- :yocto_docs:`BitBake 1.50 User Manual </bitbake/1.50/>` + +******************************* +Release Series 3.2 (gatesgarth) +******************************* + +- :yocto_docs:`BitBake 1.48 User Manual </bitbake/1.48/>` + +******************************************* +Release Series 3.1 (dunfell first versions) +******************************************* + - :yocto_docs:`3.1 BitBake User Manual </3.1/bitbake-user-manual/bitbake-user-manual.html>` - :yocto_docs:`3.1.1 BitBake User Manual </3.1.1/bitbake-user-manual/bitbake-user-manual.html>` - :yocto_docs:`3.1.2 BitBake User Manual </3.1.2/bitbake-user-manual/bitbake-user-manual.html>` - -========================== - Previous Release Manuals -========================== +- :yocto_docs:`3.1.3 BitBake User Manual </3.1.3/bitbake-user-manual/bitbake-user-manual.html>` ************************* -3.0 'zeus' Release Series +Release Series 3.0 (zeus) ************************* - :yocto_docs:`3.0 BitBake User Manual </3.0/bitbake-user-manual/bitbake-user-manual.html>` - :yocto_docs:`3.0.1 BitBake User Manual </3.0.1/bitbake-user-manual/bitbake-user-manual.html>` - :yocto_docs:`3.0.2 BitBake User Manual </3.0.2/bitbake-user-manual/bitbake-user-manual.html>` - :yocto_docs:`3.0.3 BitBake User Manual </3.0.3/bitbake-user-manual/bitbake-user-manual.html>` +- :yocto_docs:`3.0.4 BitBake User Manual </3.0.4/bitbake-user-manual/bitbake-user-manual.html>` **************************** -2.7 'warrior' Release Series +Release Series 2.7 (warrior) **************************** - :yocto_docs:`2.7 BitBake User Manual </2.7/bitbake-user-manual/bitbake-user-manual.html>` @@ -36,7 +80,7 @@ - :yocto_docs:`2.7.4 BitBake User Manual </2.7.4/bitbake-user-manual/bitbake-user-manual.html>` ************************* -2.6 'thud' Release Series +Release Series 2.6 (thud) ************************* - :yocto_docs:`2.6 BitBake User Manual </2.6/bitbake-user-manual/bitbake-user-manual.html>` @@ -46,16 +90,16 @@ - :yocto_docs:`2.6.4 BitBake User Manual </2.6.4/bitbake-user-manual/bitbake-user-manual.html>` ************************* -2.5 'sumo' Release Series +Release Series 2.5 (sumo) ************************* -- :yocto_docs:`2.5 BitBake User Manual </2.5/bitbake-user-manual/bitbake-user-manual.html>` -- :yocto_docs:`2.5.1 BitBake User Manual </2.5.1/bitbake-user-manual/bitbake-user-manual.html>` -- :yocto_docs:`2.5.2 BitBake User Manual </2.5.2/bitbake-user-manual/bitbake-user-manual.html>` -- :yocto_docs:`2.5.3 BitBake User Manual </2.5.3/bitbake-user-manual/bitbake-user-manual.html>` +- :yocto_docs:`2.5 Documentation </2.5>` +- :yocto_docs:`2.5.1 Documentation </2.5.1>` +- :yocto_docs:`2.5.2 Documentation </2.5.2>` +- :yocto_docs:`2.5.3 Documentation </2.5.3>` ************************** -2.4 'rocko' Release Series +Release Series 2.4 (rocko) ************************** - :yocto_docs:`2.4 BitBake User Manual </2.4/bitbake-user-manual/bitbake-user-manual.html>` @@ -65,7 +109,7 @@ - :yocto_docs:`2.4.4 BitBake User Manual </2.4.4/bitbake-user-manual/bitbake-user-manual.html>` ************************* -2.3 'pyro' Release Series +Release Series 2.3 (pyro) ************************* - :yocto_docs:`2.3 BitBake User Manual </2.3/bitbake-user-manual/bitbake-user-manual.html>` @@ -75,7 +119,7 @@ - :yocto_docs:`2.3.4 BitBake User Manual </2.3.4/bitbake-user-manual/bitbake-user-manual.html>` ************************** -2.2 'morty' Release Series +Release Series 2.2 (morty) ************************** - :yocto_docs:`2.2 BitBake User Manual </2.2/bitbake-user-manual/bitbake-user-manual.html>` @@ -84,7 +128,7 @@ - :yocto_docs:`2.2.3 BitBake User Manual </2.2.3/bitbake-user-manual/bitbake-user-manual.html>` **************************** -2.1 'krogoth' Release Series +Release Series 2.1 (krogoth) **************************** - :yocto_docs:`2.1 BitBake User Manual </2.1/bitbake-user-manual/bitbake-user-manual.html>` @@ -93,7 +137,7 @@ - :yocto_docs:`2.1.3 BitBake User Manual </2.1.3/bitbake-user-manual/bitbake-user-manual.html>` *************************** -2.0 'jethro' Release Series +Release Series 2.0 (jethro) *************************** - :yocto_docs:`1.9 BitBake User Manual </1.9/bitbake-user-manual/bitbake-user-manual.html>` @@ -103,7 +147,7 @@ - :yocto_docs:`2.0.3 BitBake User Manual </2.0.3/bitbake-user-manual/bitbake-user-manual.html>` ************************* -1.8 'fido' Release Series +Release Series 1.8 (fido) ************************* - :yocto_docs:`1.8 BitBake User Manual </1.8/bitbake-user-manual/bitbake-user-manual.html>` @@ -111,7 +155,7 @@ - :yocto_docs:`1.8.2 BitBake User Manual </1.8.2/bitbake-user-manual/bitbake-user-manual.html>` ************************** -1.7 'dizzy' Release Series +Release Series 1.7 (dizzy) ************************** - :yocto_docs:`1.7 BitBake User Manual </1.7/bitbake-user-manual/bitbake-user-manual.html>` @@ -120,7 +164,7 @@ - :yocto_docs:`1.7.3 BitBake User Manual </1.7.3/bitbake-user-manual/bitbake-user-manual.html>` ************************** -1.6 'daisy' Release Series +Release Series 1.6 (daisy) ************************** - :yocto_docs:`1.6 BitBake User Manual </1.6/bitbake-user-manual/bitbake-user-manual.html>` |