| Patrick Williams | 44b3caf | 2024-04-12 16:51:14 -0500 | [diff] [blame] | 1 | .. SPDX-License-Identifier: CC-BY-2.5 |
| 2 | |
| 3 | ================ |
| 4 | Variable Context |
| 5 | ================ |
| 6 | |
| 7 | | |
| 8 | |
| 9 | Variables might only have an impact or can be used in certain contexts. Some |
| 10 | should only be used in global files like ``.conf``, while others are intended only |
| 11 | for local files like ``.bb``. This chapter aims to describe some important variable |
| 12 | contexts. |
| 13 | |
| 14 | .. _ref-varcontext-configuration: |
| 15 | |
| 16 | BitBake's own configuration |
| 17 | =========================== |
| 18 | |
| 19 | Variables starting with ``BB_`` usually configure the behaviour of BitBake itself. |
| 20 | For example, one could configure: |
| 21 | |
| 22 | - System resources, like disk space to be used (:term:`BB_DISKMON_DIRS`), |
| 23 | or the number of tasks to be run in parallel by BitBake (:term:`BB_NUMBER_THREADS`). |
| 24 | |
| 25 | - How the fetchers shall behave, e.g., :term:`BB_FETCH_PREMIRRORONLY` is used |
| 26 | by BitBake to determine if BitBake's fetcher shall search only |
| 27 | :term:`PREMIRRORS` for files. |
| 28 | |
| 29 | Those variables are usually configured globally. |
| 30 | |
| 31 | BitBake configuration |
| 32 | ===================== |
| 33 | |
| 34 | There are variables: |
| 35 | |
| 36 | - Like :term:`B` or :term:`T`, that are used to specify directories used by |
| 37 | BitBake during the build of a particular recipe. Those variables are |
| 38 | specified in ``bitbake.conf``. Some, like :term:`B`, are quite often |
| 39 | overwritten in recipes. |
| 40 | |
| 41 | - Starting with ``FAKEROOT``, to configure how the ``fakeroot`` command is |
| 42 | handled. Those are usually set by ``bitbake.conf`` and might get adapted in a |
| 43 | ``bbclass``. |
| 44 | |
| 45 | - Detailing where BitBake will store and fetch information from, for |
| 46 | data reuse between build runs like :term:`CACHE`, :term:`DL_DIR` or |
| 47 | :term:`PERSISTENT_DIR`. Those are usually global. |
| 48 | |
| 49 | |
| 50 | Layers and files |
| 51 | ================ |
| 52 | |
| 53 | Variables starting with ``LAYER`` configure how BitBake handles layers. |
| 54 | Additionally, variables starting with ``BB`` configure how layers and files are |
| 55 | handled. For example: |
| 56 | |
| 57 | - :term:`LAYERDEPENDS` is used to configure on which layers a given layer |
| 58 | depends. |
| 59 | |
| 60 | - The configured layers are contained in :term:`BBLAYERS` and files in |
| 61 | :term:`BBFILES`. |
| 62 | |
| 63 | Those variables are often used in the files ``layer.conf`` and ``bblayers.conf``. |
| 64 | |
| 65 | Recipes and packages |
| 66 | ==================== |
| 67 | |
| 68 | Variables handling recipes and packages can be split into: |
| 69 | |
| 70 | - :term:`PN`, :term:`PV` or :term:`PF` for example, contain information about |
| 71 | the name or revision of a recipe or package. Usually, the default set in |
| 72 | ``bitbake.conf`` is used, but those are from time to time overwritten in |
| 73 | recipes. |
| 74 | |
| 75 | - :term:`SUMMARY`, :term:`DESCRIPTION`, :term:`LICENSE` or :term:`HOMEPAGE` |
| 76 | contain the expected information and should be set specifically for every |
| 77 | recipe. |
| 78 | |
| 79 | - In recipes, variables are also used to control build and runtime |
| 80 | dependencies between recipes/packages with other recipes/packages. The |
| 81 | most common should be: :term:`PROVIDES`, :term:`RPROVIDES`, :term:`DEPENDS`, |
| 82 | and :term:`RDEPENDS`. |
| 83 | |
| 84 | - There are further variables starting with ``SRC`` that specify the sources in |
| 85 | a recipe like :term:`SRC_URI` or :term:`SRCDATE`. Those are also usually set |
| 86 | in recipes. |
| 87 | |
| 88 | - Which version or provider of a recipe should be given preference when |
| 89 | multiple recipes would provide the same item, is controlled by variables |
| 90 | starting with ``PREFERRED_``. Those are normally set in the configuration |
| 91 | files of a ``MACHINE`` or ``DISTRO``. |