diff options
Diffstat (limited to 'bitbake/doc/bitbake-user-manual/bitbake-user-manual-execution.rst')
-rw-r--r-- | bitbake/doc/bitbake-user-manual/bitbake-user-manual-execution.rst | 74 |
1 files changed, 37 insertions, 37 deletions
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 9488ea9bae..d97fea42ad 100644 --- a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-execution.rst +++ b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-execution.rst | |||
@@ -20,7 +20,7 @@ Command <#bitbake-user-manual-command>`__" section. | |||
20 | 20 | ||
21 | Prior to executing BitBake, you should take advantage of available | 21 | Prior to executing BitBake, you should take advantage of available |
22 | parallel thread execution on your build host by setting the | 22 | parallel thread execution on your build host by setting the |
23 | ```BB_NUMBER_THREADS`` <#var-bb-BB_NUMBER_THREADS>`__ variable in | 23 | :term:`BB_NUMBER_THREADS` variable in |
24 | your project's ``local.conf`` configuration file. | 24 | your project's ``local.conf`` configuration file. |
25 | 25 | ||
26 | A common method to determine this value for your build host is to run | 26 | A common method to determine this value for your build host is to run |
@@ -52,7 +52,7 @@ data itself is of various types: | |||
52 | together. | 52 | together. |
53 | 53 | ||
54 | The ``layer.conf`` files are used to construct key variables such as | 54 | The ``layer.conf`` files are used to construct key variables such as |
55 | ```BBPATH`` <#var-bb-BBPATH>`__ and ```BBFILES`` <#var-bb-BBFILES>`__. | 55 | :term:`BBPATH` and :term:`BBFILES`. |
56 | ``BBPATH`` is used to search for configuration and class files under the | 56 | ``BBPATH`` is used to search for configuration and class files under the |
57 | ``conf`` and ``classes`` directories, respectively. ``BBFILES`` is used | 57 | ``conf`` and ``classes`` directories, respectively. ``BBFILES`` is used |
58 | to locate both recipe and recipe append files (``.bb`` and | 58 | to locate both recipe and recipe append files (``.bb`` and |
@@ -67,15 +67,15 @@ directives. | |||
67 | Prior to parsing configuration files, BitBake looks at certain | 67 | Prior to parsing configuration files, BitBake looks at certain |
68 | variables, including: | 68 | variables, including: |
69 | 69 | ||
70 | - ```BB_ENV_WHITELIST`` <#var-bb-BB_ENV_WHITELIST>`__ | 70 | - :term:`BB_ENV_WHITELIST` |
71 | 71 | ||
72 | - ```BB_ENV_EXTRAWHITE`` <#var-bb-BB_ENV_EXTRAWHITE>`__ | 72 | - :term:`BB_ENV_EXTRAWHITE` |
73 | 73 | ||
74 | - ```BB_PRESERVE_ENV`` <#var-bb-BB_PRESERVE_ENV>`__ | 74 | - :term:`BB_PRESERVE_ENV` |
75 | 75 | ||
76 | - ```BB_ORIGENV`` <#var-bb-BB_ORIGENV>`__ | 76 | - :term:`BB_ORIGENV` |
77 | 77 | ||
78 | - ```BITBAKE_UI`` <#var-bb-BITBAKE_UI>`__ | 78 | - :term:`BITBAKE_UI` |
79 | 79 | ||
80 | The first four variables in this list relate to how BitBake treats shell | 80 | The first four variables in this list relate to how BitBake treats shell |
81 | environment variables during task execution. By default, BitBake cleans | 81 | environment variables during task execution. By default, BitBake cleans |
@@ -93,16 +93,16 @@ recipes and tasks that are executed. | |||
93 | 93 | ||
94 | BitBake first searches the current working directory for an optional | 94 | BitBake first searches the current working directory for an optional |
95 | ``conf/bblayers.conf`` configuration file. This file is expected to | 95 | ``conf/bblayers.conf`` configuration file. This file is expected to |
96 | contain a ```BBLAYERS`` <#var-bb-BBLAYERS>`__ variable that is a | 96 | contain a :term:`BBLAYERS` variable that is a |
97 | space-delimited list of 'layer' directories. Recall that if BitBake | 97 | space-delimited list of 'layer' directories. Recall that if BitBake |
98 | cannot find a ``bblayers.conf`` file, then it is assumed the user has | 98 | cannot find a ``bblayers.conf`` file, then it is assumed the user has |
99 | set the ``BBPATH`` and ``BBFILES`` variables directly in the | 99 | set the ``BBPATH`` and ``BBFILES`` variables directly in the |
100 | environment. | 100 | environment. |
101 | 101 | ||
102 | For each directory (layer) in this list, a ``conf/layer.conf`` file is | 102 | For each directory (layer) in this list, a ``conf/layer.conf`` file is |
103 | located and parsed with the ```LAYERDIR`` <#var-bb-LAYERDIR>`__ variable | 103 | located and parsed with the :term:`LAYERDIR` variable |
104 | being set to the directory where the layer was found. The idea is these | 104 | being set to the directory where the layer was found. The idea is these |
105 | files automatically set up ```BBPATH`` <#var-bb-BBPATH>`__ and other | 105 | files automatically set up :term:`BBPATH` and other |
106 | variables correctly for a given build directory. | 106 | variables correctly for a given build directory. |
107 | 107 | ||
108 | BitBake then expects to find the ``conf/bitbake.conf`` file somewhere in | 108 | BitBake then expects to find the ``conf/bitbake.conf`` file somewhere in |
@@ -125,7 +125,7 @@ responsible for getting that class is encountered. | |||
125 | 125 | ||
126 | The ``base.bbclass`` file is always included. Other classes that are | 126 | The ``base.bbclass`` file is always included. Other classes that are |
127 | specified in the configuration using the | 127 | specified in the configuration using the |
128 | ```INHERIT`` <#var-bb-INHERIT>`__ variable are also included. BitBake | 128 | :term:`INHERIT` variable are also included. BitBake |
129 | searches for class files in a ``classes`` subdirectory under the paths | 129 | searches for class files in a ``classes`` subdirectory under the paths |
130 | in ``BBPATH`` in the same way as configuration files. | 130 | in ``BBPATH`` in the same way as configuration files. |
131 | 131 | ||
@@ -157,7 +157,7 @@ Locating and Parsing Recipes | |||
157 | ============================ | 157 | ============================ |
158 | 158 | ||
159 | During the configuration phase, BitBake will have set | 159 | During the configuration phase, BitBake will have set |
160 | ```BBFILES`` <#var-bb-BBFILES>`__. BitBake now uses it to construct a | 160 | :term:`BBFILES`. BitBake now uses it to construct a |
161 | list of recipes to parse, along with any append files (``.bbappend``) to | 161 | list of recipes to parse, along with any append files (``.bbappend``) to |
162 | apply. ``BBFILES`` is a space-separated list of available files and | 162 | apply. ``BBFILES`` is a space-separated list of available files and |
163 | supports wildcards. An example would be: BBFILES = | 163 | supports wildcards. An example would be: BBFILES = |
@@ -174,13 +174,13 @@ various variables into the datastore. | |||
174 | For each file, a fresh copy of the base configuration is made, then the | 174 | For each file, a fresh copy of the base configuration is made, then the |
175 | recipe is parsed line by line. Any inherit statements cause BitBake to | 175 | recipe is parsed line by line. Any inherit statements cause BitBake to |
176 | find and then parse class files (``.bbclass``) using | 176 | find and then parse class files (``.bbclass``) using |
177 | ```BBPATH`` <#var-bb-BBPATH>`__ as the search path. Finally, BitBake | 177 | :term:`BBPATH` as the search path. Finally, BitBake |
178 | parses in order any append files found in ``BBFILES``. | 178 | parses in order any append files found in ``BBFILES``. |
179 | 179 | ||
180 | One common convention is to use the recipe filename to define pieces of | 180 | One common convention is to use the recipe filename to define pieces of |
181 | metadata. For example, in ``bitbake.conf`` the recipe name and version | 181 | metadata. For example, in ``bitbake.conf`` the recipe name and version |
182 | are used to set the variables ```PN`` <#var-bb-PN>`__ and | 182 | are used to set the variables :term:`PN` and |
183 | ```PV`` <#var-bb-PV>`__: PN = | 183 | :term:`PV`: PN = |
184 | "${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE', False),d)[0] or | 184 | "${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE', False),d)[0] or |
185 | 'defaultpkgname'}" PV = | 185 | 'defaultpkgname'}" PV = |
186 | "${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE', False),d)[1] or | 186 | "${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE', False),d)[1] or |
@@ -201,7 +201,7 @@ and then reload it. | |||
201 | Where possible, subsequent BitBake commands reuse this cache of recipe | 201 | Where possible, subsequent BitBake commands reuse this cache of recipe |
202 | information. The validity of this cache is determined by first computing | 202 | information. The validity of this cache is determined by first computing |
203 | a checksum of the base configuration data (see | 203 | a checksum of the base configuration data (see |
204 | ```BB_HASHCONFIG_WHITELIST`` <#var-bb-BB_HASHCONFIG_WHITELIST>`__) and | 204 | :term:`BB_HASHCONFIG_WHITELIST`) and |
205 | then checking if the checksum matches. If that checksum matches what is | 205 | then checking if the checksum matches. If that checksum matches what is |
206 | in the cache and the recipe and class files have not changed, BitBake is | 206 | in the cache and the recipe and class files have not changed, BitBake is |
207 | able to use the cache. BitBake then reloads the cached information about | 207 | able to use the cache. BitBake then reloads the cached information about |
@@ -233,8 +233,8 @@ the recipe files have been parsed, BitBake starts to figure out how to | |||
233 | build the target. BitBake looks through the ``PROVIDES`` list for each | 233 | build the target. BitBake looks through the ``PROVIDES`` list for each |
234 | of the recipes. A ``PROVIDES`` list is the list of names by which the | 234 | of the recipes. A ``PROVIDES`` list is the list of names by which the |
235 | recipe can be known. Each recipe's ``PROVIDES`` list is created | 235 | recipe can be known. Each recipe's ``PROVIDES`` list is created |
236 | implicitly through the recipe's ```PN`` <#var-bb-PN>`__ variable and | 236 | implicitly through the recipe's :term:`PN` variable and |
237 | explicitly through the recipe's ```PROVIDES`` <#var-bb-PROVIDES>`__ | 237 | explicitly through the recipe's :term:`PROVIDES` |
238 | variable, which is optional. | 238 | variable, which is optional. |
239 | 239 | ||
240 | When a recipe uses ``PROVIDES``, that recipe's functionality can be | 240 | When a recipe uses ``PROVIDES``, that recipe's functionality can be |
@@ -259,7 +259,7 @@ A common example in which a target has multiple providers is | |||
259 | recipe. Each machine often selects the best kernel provider by using a | 259 | recipe. Each machine often selects the best kernel provider by using a |
260 | line similar to the following in the machine configuration file: | 260 | line similar to the following in the machine configuration file: |
261 | PREFERRED_PROVIDER_virtual/kernel = "linux-yocto" The default | 261 | PREFERRED_PROVIDER_virtual/kernel = "linux-yocto" The default |
262 | ```PREFERRED_PROVIDER`` <#var-bb-PREFERRED_PROVIDER>`__ is the provider | 262 | :term:`PREFERRED_PROVIDER` is the provider |
263 | with the same name as the target. BitBake iterates through each target | 263 | with the same name as the target. BitBake iterates through each target |
264 | it needs to build and resolves them and their dependencies using this | 264 | it needs to build and resolves them and their dependencies using this |
265 | process. | 265 | process. |
@@ -268,9 +268,9 @@ Understanding how providers are chosen is made complicated by the fact | |||
268 | that multiple versions might exist for a given provider. BitBake | 268 | that multiple versions might exist for a given provider. BitBake |
269 | defaults to the highest version of a provider. Version comparisons are | 269 | defaults to the highest version of a provider. Version comparisons are |
270 | made using the same method as Debian. You can use the | 270 | made using the same method as Debian. You can use the |
271 | ```PREFERRED_VERSION`` <#var-bb-PREFERRED_VERSION>`__ variable to | 271 | :term:`PREFERRED_VERSION` variable to |
272 | specify a particular version. You can influence the order by using the | 272 | specify a particular version. You can influence the order by using the |
273 | ```DEFAULT_PREFERENCE`` <#var-bb-DEFAULT_PREFERENCE>`__ variable. | 273 | :term:`DEFAULT_PREFERENCE` variable. |
274 | 274 | ||
275 | By default, files have a preference of "0". Setting | 275 | By default, files have a preference of "0". Setting |
276 | ``DEFAULT_PREFERENCE`` to "-1" makes the recipe unlikely to be used | 276 | ``DEFAULT_PREFERENCE`` to "-1" makes the recipe unlikely to be used |
@@ -283,15 +283,15 @@ undergone sufficient testing to be considered stable. | |||
283 | When there are multiple “versions” of a given recipe, BitBake defaults | 283 | When there are multiple “versions” of a given recipe, BitBake defaults |
284 | to selecting the most recent version, unless otherwise specified. If the | 284 | to selecting the most recent version, unless otherwise specified. If the |
285 | recipe in question has a | 285 | recipe in question has a |
286 | ```DEFAULT_PREFERENCE`` <#var-bb-DEFAULT_PREFERENCE>`__ set lower than | 286 | :term:`DEFAULT_PREFERENCE` set lower than |
287 | the other recipes (default is 0), then it will not be selected. This | 287 | the other recipes (default is 0), then it will not be selected. This |
288 | allows the person or persons maintaining the repository of recipe files | 288 | allows the person or persons maintaining the repository of recipe files |
289 | to specify their preference for the default selected version. | 289 | to specify their preference for the default selected version. |
290 | Additionally, the user can specify their preferred version. | 290 | Additionally, the user can specify their preferred version. |
291 | 291 | ||
292 | If the first recipe is named ``a_1.1.bb``, then the | 292 | If the first recipe is named ``a_1.1.bb``, then the |
293 | ```PN`` <#var-bb-PN>`__ variable will be set to “a”, and the | 293 | :term:`PN` variable will be set to “a”, and the |
294 | ```PV`` <#var-bb-PV>`__ variable will be set to 1.1. | 294 | :term:`PV` variable will be set to 1.1. |
295 | 295 | ||
296 | Thus, if a recipe named ``a_1.2.bb`` exists, BitBake will choose 1.2 by | 296 | Thus, if a recipe named ``a_1.2.bb`` exists, BitBake will choose 1.2 by |
297 | default. However, if you define the following variable in a ``.conf`` | 297 | default. However, if you define the following variable in a ``.conf`` |
@@ -326,8 +326,8 @@ Dependencies are defined through several variables. You can find | |||
326 | information about variables BitBake uses in the `Variables | 326 | information about variables BitBake uses in the `Variables |
327 | Glossary <#ref-bb-variables-glos>`__ near the end of this manual. At a | 327 | Glossary <#ref-bb-variables-glos>`__ near the end of this manual. At a |
328 | basic level, it is sufficient to know that BitBake uses the | 328 | basic level, it is sufficient to know that BitBake uses the |
329 | ```DEPENDS`` <#var-bb-DEPENDS>`__ and | 329 | :term:`DEPENDS` and |
330 | ```RDEPENDS`` <#var-bb-RDEPENDS>`__ variables when calculating | 330 | :term:`RDEPENDS` variables when calculating |
331 | dependencies. | 331 | dependencies. |
332 | 332 | ||
333 | For more information on how BitBake handles dependencies, see the | 333 | For more information on how BitBake handles dependencies, see the |
@@ -345,7 +345,7 @@ section has more information on how BitBake chooses which task to | |||
345 | execute next. | 345 | execute next. |
346 | 346 | ||
347 | The build now starts with BitBake forking off threads up to the limit | 347 | The build now starts with BitBake forking off threads up to the limit |
348 | set in the ```BB_NUMBER_THREADS`` <#var-bb-BB_NUMBER_THREADS>`__ | 348 | set in the :term:`BB_NUMBER_THREADS` |
349 | variable. BitBake continues to fork threads as long as there are tasks | 349 | variable. BitBake continues to fork threads as long as there are tasks |
350 | ready to run, those tasks have all their dependencies met, and the | 350 | ready to run, those tasks have all their dependencies met, and the |
351 | thread threshold has not been exceeded. | 351 | thread threshold has not been exceeded. |
@@ -354,7 +354,7 @@ It is worth noting that you can greatly speed up the build time by | |||
354 | properly setting the ``BB_NUMBER_THREADS`` variable. | 354 | properly setting the ``BB_NUMBER_THREADS`` variable. |
355 | 355 | ||
356 | As each task completes, a timestamp is written to the directory | 356 | As each task completes, a timestamp is written to the directory |
357 | specified by the ```STAMP`` <#var-bb-STAMP>`__ variable. On subsequent | 357 | specified by the :term:`STAMP` variable. On subsequent |
358 | runs, BitBake looks in the build directory within ``tmp/stamps`` and | 358 | runs, BitBake looks in the build directory within ``tmp/stamps`` and |
359 | does not rerun tasks that are already completed unless a timestamp is | 359 | does not rerun tasks that are already completed unless a timestamp is |
360 | found to be invalid. Currently, invalid timestamps are only considered | 360 | found to be invalid. Currently, invalid timestamps are only considered |
@@ -386,7 +386,7 @@ Executing Tasks | |||
386 | 386 | ||
387 | Tasks can be either a shell task or a Python task. For shell tasks, | 387 | Tasks can be either a shell task or a Python task. For shell tasks, |
388 | BitBake writes a shell script to | 388 | BitBake writes a shell script to |
389 | ``${``\ ```T`` <#var-bb-T>`__\ ``}/run.do_taskname.pid`` and then | 389 | ``${``\ :term:`T`\ ``}/run.do_taskname.pid`` and then |
390 | executes the script. The generated shell script contains all the | 390 | executes the script. The generated shell script contains all the |
391 | exported variables, and the shell functions with all variables expanded. | 391 | exported variables, and the shell functions with all variables expanded. |
392 | Output from the shell script goes to the file | 392 | Output from the shell script goes to the file |
@@ -404,9 +404,9 @@ scheduler. It is possible to configure the scheduler and define custom | |||
404 | implementations for specific use cases. For more information, see these | 404 | implementations for specific use cases. For more information, see these |
405 | variables that control the behavior: | 405 | variables that control the behavior: |
406 | 406 | ||
407 | - ```BB_SCHEDULER`` <#var-bb-BB_SCHEDULER>`__ | 407 | - :term:`BB_SCHEDULER` |
408 | 408 | ||
409 | - ```BB_SCHEDULERS`` <#var-bb-BB_SCHEDULERS>`__ | 409 | - :term:`BB_SCHEDULERS` |
410 | 410 | ||
411 | It is possible to have functions run before and after a task's main | 411 | It is possible to have functions run before and after a task's main |
412 | function. This is done using the ``[prefuncs]`` and ``[postfuncs]`` | 412 | function. This is done using the ``[prefuncs]`` and ``[postfuncs]`` |
@@ -432,7 +432,7 @@ changes because it should not affect the output for target packages. The | |||
432 | simplistic approach for excluding the working directory is to set it to | 432 | simplistic approach for excluding the working directory is to set it to |
433 | some fixed value and create the checksum for the "run" script. BitBake | 433 | some fixed value and create the checksum for the "run" script. BitBake |
434 | goes one step better and uses the | 434 | goes one step better and uses the |
435 | ```BB_HASHBASE_WHITELIST`` <#var-bb-BB_HASHBASE_WHITELIST>`__ variable | 435 | :term:`BB_HASHBASE_WHITELIST` variable |
436 | to define a list of variables that should never be included when | 436 | to define a list of variables that should never be included when |
437 | generating the signatures. | 437 | generating the signatures. |
438 | 438 | ||
@@ -508,7 +508,7 @@ behavior is unchanged from previous versions. ``OE-Core`` uses the | |||
508 | version but adds the task hash to the stamp files. This results in any | 508 | version but adds the task hash to the stamp files. This results in any |
509 | metadata change that changes the task hash, automatically causing the | 509 | metadata change that changes the task hash, automatically causing the |
510 | task to be run again. This removes the need to bump | 510 | task to be run again. This removes the need to bump |
511 | ```PR`` <#var-bb-PR>`__ values, and changes to metadata automatically | 511 | :term:`PR` values, and changes to metadata automatically |
512 | ripple across the build. | 512 | ripple across the build. |
513 | 513 | ||
514 | It is also worth noting that the end result of these signature | 514 | It is also worth noting that the end result of these signature |
@@ -570,7 +570,7 @@ information is available, BitBake uses this information instead of | |||
570 | running the main tasks. | 570 | running the main tasks. |
571 | 571 | ||
572 | BitBake first calls the function defined by the | 572 | BitBake first calls the function defined by the |
573 | ```BB_HASHCHECK_FUNCTION`` <#var-bb-BB_HASHCHECK_FUNCTION>`__ variable | 573 | :term:`BB_HASHCHECK_FUNCTION` variable |
574 | with a list of tasks and corresponding hashes it wants to build. This | 574 | with a list of tasks and corresponding hashes it wants to build. This |
575 | function is designed to be fast and returns a list of the tasks for | 575 | function is designed to be fast and returns a list of the tasks for |
576 | which it believes in can obtain artifacts. | 576 | which it believes in can obtain artifacts. |
@@ -586,13 +586,13 @@ or failure. | |||
586 | As previously mentioned, an artifact can cover more than one task. For | 586 | As previously mentioned, an artifact can cover more than one task. For |
587 | example, it is pointless to obtain a compiler if you already have the | 587 | example, it is pointless to obtain a compiler if you already have the |
588 | compiled binary. To handle this, BitBake calls the | 588 | compiled binary. To handle this, BitBake calls the |
589 | ```BB_SETSCENE_DEPVALID`` <#var-bb-BB_SETSCENE_DEPVALID>`__ function for | 589 | :term:`BB_SETSCENE_DEPVALID` function for |
590 | each successful setscene task to know whether or not it needs to obtain | 590 | each successful setscene task to know whether or not it needs to obtain |
591 | the dependencies of that task. | 591 | the dependencies of that task. |
592 | 592 | ||
593 | Finally, after all the setscene tasks have executed, BitBake calls the | 593 | Finally, after all the setscene tasks have executed, BitBake calls the |
594 | function listed in | 594 | function listed in |
595 | ```BB_SETSCENE_VERIFY_FUNCTION2`` <#var-bb-BB_SETSCENE_VERIFY_FUNCTION2>`__ | 595 | :term:`BB_SETSCENE_VERIFY_FUNCTION2` |
596 | with the list of tasks BitBake thinks has been "covered". The metadata | 596 | with the list of tasks BitBake thinks has been "covered". The metadata |
597 | can then ensure that this list is correct and can inform BitBake that it | 597 | can then ensure that this list is correct and can inform BitBake that it |
598 | wants specific tasks to be run regardless of the setscene result. | 598 | wants specific tasks to be run regardless of the setscene result. |
@@ -607,7 +607,7 @@ In addition to the standard command line option to control how verbose | |||
607 | builds are when execute, bitbake also supports user defined | 607 | builds are when execute, bitbake also supports user defined |
608 | configuration of the `Python | 608 | configuration of the `Python |
609 | logging <https://docs.python.org/3/library/logging.html>`__ facilities | 609 | logging <https://docs.python.org/3/library/logging.html>`__ facilities |
610 | through the ```BB_LOGCONFIG`` <#var-bb-BB_LOGCONFIG>`__ variable. This | 610 | through the :term:`BB_LOGCONFIG` variable. This |
611 | variable defines a json or yaml `logging | 611 | variable defines a json or yaml `logging |
612 | configuration <https://docs.python.org/3/library/logging.config.html>`__ | 612 | configuration <https://docs.python.org/3/library/logging.config.html>`__ |
613 | that will be intelligently merged into the default configuration. The | 613 | that will be intelligently merged into the default configuration. The |