diff options
Diffstat (limited to 'bitbake/doc/bitbake-user-manual')
7 files changed, 1426 insertions, 795 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 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. | |||
16 | 16 | ||
17 | This chapter describes BitBake's execution process from start to finish | 17 | This chapter describes BitBake's execution process from start to finish |
18 | when you use it to create an image. The execution process is launched | 18 | when you use it to create an image. The execution process is launched |
19 | using the following command form: :: | 19 | using the following command form:: |
20 | 20 | ||
21 | $ bitbake target | 21 | $ bitbake target |
22 | 22 | ||
@@ -32,7 +32,7 @@ the BitBake command and its options, see ":ref:`The BitBake Command | |||
32 | your project's ``local.conf`` configuration file. | 32 | your project's ``local.conf`` configuration file. |
33 | 33 | ||
34 | A common method to determine this value for your build host is to run | 34 | A common method to determine this value for your build host is to run |
35 | the following: :: | 35 | the following:: |
36 | 36 | ||
37 | $ grep processor /proc/cpuinfo | 37 | $ grep processor /proc/cpuinfo |
38 | 38 | ||
@@ -40,7 +40,7 @@ the BitBake command and its options, see ":ref:`The BitBake Command | |||
40 | the number of processors, which takes into account hyper-threading. | 40 | the number of processors, which takes into account hyper-threading. |
41 | Thus, a quad-core build host with hyper-threading most likely shows | 41 | Thus, a quad-core build host with hyper-threading most likely shows |
42 | eight processors, which is the value you would then assign to | 42 | eight processors, which is the value you would then assign to |
43 | ``BB_NUMBER_THREADS``. | 43 | :term:`BB_NUMBER_THREADS`. |
44 | 44 | ||
45 | A possibly simpler solution is that some Linux distributions (e.g. | 45 | A possibly simpler solution is that some Linux distributions (e.g. |
46 | Debian and Ubuntu) provide the ``ncpus`` command. | 46 | Debian and Ubuntu) provide the ``ncpus`` command. |
@@ -65,13 +65,13 @@ data itself is of various types: | |||
65 | 65 | ||
66 | The ``layer.conf`` files are used to construct key variables such as | 66 | The ``layer.conf`` files are used to construct key variables such as |
67 | :term:`BBPATH` and :term:`BBFILES`. | 67 | :term:`BBPATH` and :term:`BBFILES`. |
68 | ``BBPATH`` is used to search for configuration and class files under the | 68 | :term:`BBPATH` is used to search for configuration and class files under the |
69 | ``conf`` and ``classes`` directories, respectively. ``BBFILES`` is used | 69 | ``conf`` and ``classes`` directories, respectively. :term:`BBFILES` is used |
70 | to locate both recipe and recipe append files (``.bb`` and | 70 | to locate both recipe and recipe append files (``.bb`` and |
71 | ``.bbappend``). If there is no ``bblayers.conf`` file, it is assumed the | 71 | ``.bbappend``). If there is no ``bblayers.conf`` file, it is assumed the |
72 | user has set the ``BBPATH`` and ``BBFILES`` directly in the environment. | 72 | user has set the :term:`BBPATH` and :term:`BBFILES` directly in the environment. |
73 | 73 | ||
74 | Next, the ``bitbake.conf`` file is located using the ``BBPATH`` variable | 74 | Next, the ``bitbake.conf`` file is located using the :term:`BBPATH` variable |
75 | that was just constructed. The ``bitbake.conf`` file may also include | 75 | that was just constructed. The ``bitbake.conf`` file may also include |
76 | other configuration files using the ``include`` or ``require`` | 76 | other configuration files using the ``include`` or ``require`` |
77 | directives. | 77 | directives. |
@@ -79,8 +79,8 @@ directives. | |||
79 | Prior to parsing configuration files, BitBake looks at certain | 79 | Prior to parsing configuration files, BitBake looks at certain |
80 | variables, including: | 80 | variables, including: |
81 | 81 | ||
82 | - :term:`BB_ENV_WHITELIST` | 82 | - :term:`BB_ENV_PASSTHROUGH` |
83 | - :term:`BB_ENV_EXTRAWHITE` | 83 | - :term:`BB_ENV_PASSTHROUGH_ADDITIONS` |
84 | - :term:`BB_PRESERVE_ENV` | 84 | - :term:`BB_PRESERVE_ENV` |
85 | - :term:`BB_ORIGENV` | 85 | - :term:`BB_ORIGENV` |
86 | - :term:`BITBAKE_UI` | 86 | - :term:`BITBAKE_UI` |
@@ -104,7 +104,7 @@ BitBake first searches the current working directory for an optional | |||
104 | contain a :term:`BBLAYERS` variable that is a | 104 | contain a :term:`BBLAYERS` variable that is a |
105 | space-delimited list of 'layer' directories. Recall that if BitBake | 105 | space-delimited list of 'layer' directories. Recall that if BitBake |
106 | cannot find a ``bblayers.conf`` file, then it is assumed the user has | 106 | cannot find a ``bblayers.conf`` file, then it is assumed the user has |
107 | set the ``BBPATH`` and ``BBFILES`` variables directly in the | 107 | set the :term:`BBPATH` and :term:`BBFILES` variables directly in the |
108 | environment. | 108 | environment. |
109 | 109 | ||
110 | For each directory (layer) in this list, a ``conf/layer.conf`` file is | 110 | 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 | |||
114 | variables correctly for a given build directory. | 114 | variables correctly for a given build directory. |
115 | 115 | ||
116 | BitBake then expects to find the ``conf/bitbake.conf`` file somewhere in | 116 | BitBake then expects to find the ``conf/bitbake.conf`` file somewhere in |
117 | the user-specified ``BBPATH``. That configuration file generally has | 117 | the user-specified :term:`BBPATH`. That configuration file generally has |
118 | include directives to pull in any other metadata such as files specific | 118 | include directives to pull in any other metadata such as files specific |
119 | to the architecture, the machine, the local environment, and so forth. | 119 | to the architecture, the machine, the local environment, and so forth. |
120 | 120 | ||
@@ -135,11 +135,11 @@ The ``base.bbclass`` file is always included. Other classes that are | |||
135 | specified in the configuration using the | 135 | specified in the configuration using the |
136 | :term:`INHERIT` variable are also included. BitBake | 136 | :term:`INHERIT` variable are also included. BitBake |
137 | searches for class files in a ``classes`` subdirectory under the paths | 137 | searches for class files in a ``classes`` subdirectory under the paths |
138 | in ``BBPATH`` in the same way as configuration files. | 138 | in :term:`BBPATH` in the same way as configuration files. |
139 | 139 | ||
140 | A good way to get an idea of the configuration files and the class files | 140 | A good way to get an idea of the configuration files and the class files |
141 | used in your execution environment is to run the following BitBake | 141 | used in your execution environment is to run the following BitBake |
142 | command: :: | 142 | command:: |
143 | 143 | ||
144 | $ bitbake -e > mybb.log | 144 | $ bitbake -e > mybb.log |
145 | 145 | ||
@@ -155,7 +155,7 @@ execution environment. | |||
155 | pair of curly braces in a shell function, the closing curly brace | 155 | pair of curly braces in a shell function, the closing curly brace |
156 | must not be located at the start of the line without leading spaces. | 156 | must not be located at the start of the line without leading spaces. |
157 | 157 | ||
158 | Here is an example that causes BitBake to produce a parsing error: :: | 158 | Here is an example that causes BitBake to produce a parsing error:: |
159 | 159 | ||
160 | fakeroot create_shar() { | 160 | fakeroot create_shar() { |
161 | cat << "EOF" > ${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.sh | 161 | cat << "EOF" > ${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.sh |
@@ -184,13 +184,13 @@ Locating and Parsing Recipes | |||
184 | During the configuration phase, BitBake will have set | 184 | During the configuration phase, BitBake will have set |
185 | :term:`BBFILES`. BitBake now uses it to construct a | 185 | :term:`BBFILES`. BitBake now uses it to construct a |
186 | list of recipes to parse, along with any append files (``.bbappend``) to | 186 | list of recipes to parse, along with any append files (``.bbappend``) to |
187 | apply. ``BBFILES`` is a space-separated list of available files and | 187 | apply. :term:`BBFILES` is a space-separated list of available files and |
188 | supports wildcards. An example would be: :: | 188 | supports wildcards. An example would be:: |
189 | 189 | ||
190 | BBFILES = "/path/to/bbfiles/*.bb /path/to/appends/*.bbappend" | 190 | BBFILES = "/path/to/bbfiles/*.bb /path/to/appends/*.bbappend" |
191 | 191 | ||
192 | BitBake parses each | 192 | BitBake parses each |
193 | recipe and append file located with ``BBFILES`` and stores the values of | 193 | recipe and append file located with :term:`BBFILES` and stores the values of |
194 | various variables into the datastore. | 194 | various variables into the datastore. |
195 | 195 | ||
196 | .. note:: | 196 | .. note:: |
@@ -201,18 +201,18 @@ For each file, a fresh copy of the base configuration is made, then the | |||
201 | recipe is parsed line by line. Any inherit statements cause BitBake to | 201 | recipe is parsed line by line. Any inherit statements cause BitBake to |
202 | find and then parse class files (``.bbclass``) using | 202 | find and then parse class files (``.bbclass``) using |
203 | :term:`BBPATH` as the search path. Finally, BitBake | 203 | :term:`BBPATH` as the search path. Finally, BitBake |
204 | parses in order any append files found in ``BBFILES``. | 204 | parses in order any append files found in :term:`BBFILES`. |
205 | 205 | ||
206 | One common convention is to use the recipe filename to define pieces of | 206 | One common convention is to use the recipe filename to define pieces of |
207 | metadata. For example, in ``bitbake.conf`` the recipe name and version | 207 | metadata. For example, in ``bitbake.conf`` the recipe name and version |
208 | are used to set the variables :term:`PN` and | 208 | are used to set the variables :term:`PN` and |
209 | :term:`PV`: :: | 209 | :term:`PV`:: |
210 | 210 | ||
211 | PN = "${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE', False),d)[0] or 'defaultpkgname'}" | 211 | PN = "${@bb.parse.vars_from_file(d.getVar('FILE', False),d)[0] or 'defaultpkgname'}" |
212 | PV = "${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE', False),d)[1] or '1.0'}" | 212 | PV = "${@bb.parse.vars_from_file(d.getVar('FILE', False),d)[1] or '1.0'}" |
213 | 213 | ||
214 | In this example, a recipe called "something_1.2.3.bb" would set | 214 | In this example, a recipe called "something_1.2.3.bb" would set |
215 | ``PN`` to "something" and ``PV`` to "1.2.3". | 215 | :term:`PN` to "something" and :term:`PV` to "1.2.3". |
216 | 216 | ||
217 | By the time parsing is complete for a recipe, BitBake has a list of | 217 | By the time parsing is complete for a recipe, BitBake has a list of |
218 | tasks that the recipe defines and a set of data consisting of keys and | 218 | tasks that the recipe defines and a set of data consisting of keys and |
@@ -228,7 +228,7 @@ and then reload it. | |||
228 | Where possible, subsequent BitBake commands reuse this cache of recipe | 228 | Where possible, subsequent BitBake commands reuse this cache of recipe |
229 | information. The validity of this cache is determined by first computing | 229 | information. The validity of this cache is determined by first computing |
230 | a checksum of the base configuration data (see | 230 | a checksum of the base configuration data (see |
231 | :term:`BB_HASHCONFIG_WHITELIST`) and | 231 | :term:`BB_HASHCONFIG_IGNORE_VARS`) and |
232 | then checking if the checksum matches. If that checksum matches what is | 232 | then checking if the checksum matches. If that checksum matches what is |
233 | in the cache and the recipe and class files have not changed, BitBake is | 233 | in the cache and the recipe and class files have not changed, BitBake is |
234 | able to use the cache. BitBake then reloads the cached information about | 234 | 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 | |||
238 | repositories of ``.bb`` files that contain the same exact package. For | 238 | repositories of ``.bb`` files that contain the same exact package. For |
239 | example, one could easily use them to make one's own local copy of an | 239 | example, one could easily use them to make one's own local copy of an |
240 | upstream repository, but with custom modifications that one does not | 240 | upstream repository, but with custom modifications that one does not |
241 | want upstream. Here is an example: :: | 241 | want upstream. Here is an example:: |
242 | 242 | ||
243 | BBFILES = "/stuff/openembedded/*/*.bb /stuff/openembedded.modified/*/*.bb" | 243 | BBFILES = "/stuff/openembedded/*/*.bb /stuff/openembedded.modified/*/*.bb" |
244 | BBFILE_COLLECTIONS = "upstream local" | 244 | BBFILE_COLLECTIONS = "upstream local" |
245 | BBFILE_PATTERN_upstream = "^/stuff/openembedded/" | 245 | BBFILE_PATTERN_upstream = "^/stuff/openembedded/" |
246 | BBFILE_PATTERN_local = "^/stuff/openembedded.modified/" | 246 | BBFILE_PATTERN_local = "^/stuff/openembedded.modified/" |
247 | BBFILE_PRIORITY_upstream = "5" BBFILE_PRIORITY_local = "10" | 247 | BBFILE_PRIORITY_upstream = "5" |
248 | BBFILE_PRIORITY_local = "10" | ||
248 | 249 | ||
249 | .. note:: | 250 | .. note:: |
250 | 251 | ||
@@ -259,21 +260,21 @@ Providers | |||
259 | 260 | ||
260 | Assuming BitBake has been instructed to execute a target and that all | 261 | Assuming BitBake has been instructed to execute a target and that all |
261 | the recipe files have been parsed, BitBake starts to figure out how to | 262 | the recipe files have been parsed, BitBake starts to figure out how to |
262 | build the target. BitBake looks through the ``PROVIDES`` list for each | 263 | build the target. BitBake looks through the :term:`PROVIDES` list for each |
263 | of the recipes. A ``PROVIDES`` list is the list of names by which the | 264 | of the recipes. A :term:`PROVIDES` list is the list of names by which the |
264 | recipe can be known. Each recipe's ``PROVIDES`` list is created | 265 | recipe can be known. Each recipe's :term:`PROVIDES` list is created |
265 | implicitly through the recipe's :term:`PN` variable and | 266 | implicitly through the recipe's :term:`PN` variable and |
266 | explicitly through the recipe's :term:`PROVIDES` | 267 | explicitly through the recipe's :term:`PROVIDES` |
267 | variable, which is optional. | 268 | variable, which is optional. |
268 | 269 | ||
269 | When a recipe uses ``PROVIDES``, that recipe's functionality can be | 270 | When a recipe uses :term:`PROVIDES`, that recipe's functionality can be |
270 | found under an alternative name or names other than the implicit ``PN`` | 271 | found under an alternative name or names other than the implicit :term:`PN` |
271 | name. As an example, suppose a recipe named ``keyboard_1.0.bb`` | 272 | name. As an example, suppose a recipe named ``keyboard_1.0.bb`` |
272 | contained the following: :: | 273 | contained the following:: |
273 | 274 | ||
274 | PROVIDES += "fullkeyboard" | 275 | PROVIDES += "fullkeyboard" |
275 | 276 | ||
276 | The ``PROVIDES`` | 277 | The :term:`PROVIDES` |
277 | list for this recipe becomes "keyboard", which is implicit, and | 278 | list for this recipe becomes "keyboard", which is implicit, and |
278 | "fullkeyboard", which is explicit. Consequently, the functionality found | 279 | "fullkeyboard", which is explicit. Consequently, the functionality found |
279 | in ``keyboard_1.0.bb`` can be found under two different names. | 280 | 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. | |||
283 | Preferences | 284 | Preferences |
284 | =========== | 285 | =========== |
285 | 286 | ||
286 | The ``PROVIDES`` list is only part of the solution for figuring out a | 287 | The :term:`PROVIDES` list is only part of the solution for figuring out a |
287 | target's recipes. Because targets might have multiple providers, BitBake | 288 | target's recipes. Because targets might have multiple providers, BitBake |
288 | needs to prioritize providers by determining provider preferences. | 289 | needs to prioritize providers by determining provider preferences. |
289 | 290 | ||
290 | A common example in which a target has multiple providers is | 291 | A common example in which a target has multiple providers is |
291 | "virtual/kernel", which is on the ``PROVIDES`` list for each kernel | 292 | "virtual/kernel", which is on the :term:`PROVIDES` list for each kernel |
292 | recipe. Each machine often selects the best kernel provider by using a | 293 | recipe. Each machine often selects the best kernel provider by using a |
293 | line similar to the following in the machine configuration file: :: | 294 | line similar to the following in the machine configuration file:: |
294 | 295 | ||
295 | PREFERRED_PROVIDER_virtual/kernel = "linux-yocto" | 296 | PREFERRED_PROVIDER_virtual/kernel = "linux-yocto" |
296 | 297 | ||
@@ -308,10 +309,10 @@ specify a particular version. You can influence the order by using the | |||
308 | :term:`DEFAULT_PREFERENCE` variable. | 309 | :term:`DEFAULT_PREFERENCE` variable. |
309 | 310 | ||
310 | By default, files have a preference of "0". Setting | 311 | By default, files have a preference of "0". Setting |
311 | ``DEFAULT_PREFERENCE`` to "-1" makes the recipe unlikely to be used | 312 | :term:`DEFAULT_PREFERENCE` to "-1" makes the recipe unlikely to be used |
312 | unless it is explicitly referenced. Setting ``DEFAULT_PREFERENCE`` to | 313 | unless it is explicitly referenced. Setting :term:`DEFAULT_PREFERENCE` to |
313 | "1" makes it likely the recipe is used. ``PREFERRED_VERSION`` overrides | 314 | "1" makes it likely the recipe is used. :term:`PREFERRED_VERSION` overrides |
314 | any ``DEFAULT_PREFERENCE`` setting. ``DEFAULT_PREFERENCE`` is often used | 315 | any :term:`DEFAULT_PREFERENCE` setting. :term:`DEFAULT_PREFERENCE` is often used |
315 | to mark newer and more experimental recipe versions until they have | 316 | to mark newer and more experimental recipe versions until they have |
316 | undergone sufficient testing to be considered stable. | 317 | undergone sufficient testing to be considered stable. |
317 | 318 | ||
@@ -330,7 +331,7 @@ If the first recipe is named ``a_1.1.bb``, then the | |||
330 | 331 | ||
331 | Thus, if a recipe named ``a_1.2.bb`` exists, BitBake will choose 1.2 by | 332 | Thus, if a recipe named ``a_1.2.bb`` exists, BitBake will choose 1.2 by |
332 | default. However, if you define the following variable in a ``.conf`` | 333 | default. However, if you define the following variable in a ``.conf`` |
333 | file that BitBake parses, you can change that preference: :: | 334 | file that BitBake parses, you can change that preference:: |
334 | 335 | ||
335 | PREFERRED_VERSION_a = "1.1" | 336 | PREFERRED_VERSION_a = "1.1" |
336 | 337 | ||
@@ -393,7 +394,7 @@ ready to run, those tasks have all their dependencies met, and the | |||
393 | thread threshold has not been exceeded. | 394 | thread threshold has not been exceeded. |
394 | 395 | ||
395 | It is worth noting that you can greatly speed up the build time by | 396 | It is worth noting that you can greatly speed up the build time by |
396 | properly setting the ``BB_NUMBER_THREADS`` variable. | 397 | properly setting the :term:`BB_NUMBER_THREADS` variable. |
397 | 398 | ||
398 | As each task completes, a timestamp is written to the directory | 399 | As each task completes, a timestamp is written to the directory |
399 | specified by the :term:`STAMP` variable. On subsequent | 400 | specified by the :term:`STAMP` variable. On subsequent |
@@ -434,7 +435,7 @@ BitBake writes a shell script to | |||
434 | executes the script. The generated shell script contains all the | 435 | executes the script. The generated shell script contains all the |
435 | exported variables, and the shell functions with all variables expanded. | 436 | exported variables, and the shell functions with all variables expanded. |
436 | Output from the shell script goes to the file | 437 | Output from the shell script goes to the file |
437 | ``${T}/log.do_taskname.pid``. Looking at the expanded shell functions in | 438 | ``${``\ :term:`T`\ ``}/log.do_taskname.pid``. Looking at the expanded shell functions in |
438 | the run file and the output in the log files is a useful debugging | 439 | the run file and the output in the log files is a useful debugging |
439 | technique. | 440 | technique. |
440 | 441 | ||
@@ -476,7 +477,7 @@ changes because it should not affect the output for target packages. The | |||
476 | simplistic approach for excluding the working directory is to set it to | 477 | simplistic approach for excluding the working directory is to set it to |
477 | some fixed value and create the checksum for the "run" script. BitBake | 478 | some fixed value and create the checksum for the "run" script. BitBake |
478 | goes one step better and uses the | 479 | goes one step better and uses the |
479 | :term:`BB_HASHBASE_WHITELIST` variable | 480 | :term:`BB_BASEHASH_IGNORE_VARS` variable |
480 | to define a list of variables that should never be included when | 481 | to define a list of variables that should never be included when |
481 | generating the signatures. | 482 | generating the signatures. |
482 | 483 | ||
@@ -497,7 +498,7 @@ to the task. | |||
497 | 498 | ||
498 | Like the working directory case, situations exist where dependencies | 499 | Like the working directory case, situations exist where dependencies |
499 | should be ignored. For these cases, you can instruct the build process | 500 | should be ignored. For these cases, you can instruct the build process |
500 | to ignore a dependency by using a line like the following: :: | 501 | to ignore a dependency by using a line like the following:: |
501 | 502 | ||
502 | PACKAGE_ARCHS[vardepsexclude] = "MACHINE" | 503 | PACKAGE_ARCHS[vardepsexclude] = "MACHINE" |
503 | 504 | ||
@@ -507,7 +508,7 @@ even if it does reference it. | |||
507 | 508 | ||
508 | Equally, there are cases where we need to add dependencies BitBake is | 509 | Equally, there are cases where we need to add dependencies BitBake is |
509 | not able to find. You can accomplish this by using a line like the | 510 | not able to find. You can accomplish this by using a line like the |
510 | following: :: | 511 | following:: |
511 | 512 | ||
512 | PACKAGE_ARCHS[vardeps] = "MACHINE" | 513 | PACKAGE_ARCHS[vardeps] = "MACHINE" |
513 | 514 | ||
@@ -522,7 +523,7 @@ it cannot figure out dependencies. | |||
522 | Thus far, this section has limited discussion to the direct inputs into | 523 | Thus far, this section has limited discussion to the direct inputs into |
523 | a task. Information based on direct inputs is referred to as the | 524 | a task. Information based on direct inputs is referred to as the |
524 | "basehash" in the code. However, there is still the question of a task's | 525 | "basehash" in the code. However, there is still the question of a task's |
525 | indirect inputs - the things that were already built and present in the | 526 | indirect inputs --- the things that were already built and present in the |
526 | build directory. The checksum (or signature) for a particular task needs | 527 | build directory. The checksum (or signature) for a particular task needs |
527 | to add the hashes of all the tasks on which the particular task depends. | 528 | to add the hashes of all the tasks on which the particular task depends. |
528 | Choosing which dependencies to add is a policy decision. However, the | 529 | 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 | |||
533 | dependent task hashes can be influenced. Within the BitBake | 534 | dependent task hashes can be influenced. Within the BitBake |
534 | configuration file, we can give BitBake some extra information to help | 535 | configuration file, we can give BitBake some extra information to help |
535 | it construct the basehash. The following statement effectively results | 536 | it construct the basehash. The following statement effectively results |
536 | in a list of global variable dependency excludes - variables never | 537 | in a list of global variable dependency excludes --- variables never |
537 | included in any checksum. This example uses variables from OpenEmbedded | 538 | included in any checksum. This example uses variables from OpenEmbedded |
538 | to help illustrate the concept: :: | 539 | to help illustrate the concept:: |
539 | 540 | ||
540 | BB_HASHBASE_WHITELIST ?= "TMPDIR FILE PATH PWD BB_TASKHASH BBPATH DL_DIR \ | 541 | BB_BASEHASH_IGNORE_VARS ?= "TMPDIR FILE PATH PWD BB_TASKHASH BBPATH DL_DIR \ |
541 | SSTATE_DIR THISDIR FILESEXTRAPATHS FILE_DIRNAME HOME LOGNAME SHELL \ | 542 | SSTATE_DIR THISDIR FILESEXTRAPATHS FILE_DIRNAME HOME LOGNAME SHELL \ |
542 | USER FILESPATH STAGING_DIR_HOST STAGING_DIR_TARGET COREBASE PRSERV_HOST \ | 543 | USER FILESPATH STAGING_DIR_HOST STAGING_DIR_TARGET COREBASE PRSERV_HOST \ |
543 | PRSERV_DUMPDIR PRSERV_DUMPFILE PRSERV_LOCKDOWN PARALLEL_MAKE \ | 544 | PRSERV_DUMPDIR PRSERV_DUMPFILE PRSERV_LOCKDOWN PARALLEL_MAKE \ |
@@ -551,23 +552,22 @@ through dependency chains are more complex and are generally | |||
551 | accomplished with a Python function. The code in | 552 | accomplished with a Python function. The code in |
552 | ``meta/lib/oe/sstatesig.py`` shows two examples of this and also | 553 | ``meta/lib/oe/sstatesig.py`` shows two examples of this and also |
553 | illustrates how you can insert your own policy into the system if so | 554 | illustrates how you can insert your own policy into the system if so |
554 | desired. This file defines the two basic signature generators | 555 | desired. This file defines the basic signature generator |
555 | OpenEmbedded-Core uses: "OEBasic" and "OEBasicHash". By default, there | 556 | OpenEmbedded-Core uses: "OEBasicHash". By default, there |
556 | is a dummy "noop" signature handler enabled in BitBake. This means that | 557 | is a dummy "noop" signature handler enabled in BitBake. This means that |
557 | behavior is unchanged from previous versions. ``OE-Core`` uses the | 558 | behavior is unchanged from previous versions. ``OE-Core`` uses the |
558 | "OEBasicHash" signature handler by default through this setting in the | 559 | "OEBasicHash" signature handler by default through this setting in the |
559 | ``bitbake.conf`` file: :: | 560 | ``bitbake.conf`` file:: |
560 | 561 | ||
561 | BB_SIGNATURE_HANDLER ?= "OEBasicHash" | 562 | BB_SIGNATURE_HANDLER ?= "OEBasicHash" |
562 | 563 | ||
563 | The "OEBasicHash" ``BB_SIGNATURE_HANDLER`` is the same as the "OEBasic" | 564 | The main feature of the "OEBasicHash" :term:`BB_SIGNATURE_HANDLER` is that |
564 | version but adds the task hash to the stamp files. This results in any | 565 | it adds the task hash to the stamp files. Thanks to this, any metadata |
565 | metadata change that changes the task hash, automatically causing the | 566 | change will change the task hash, automatically causing the task to be run |
566 | task to be run again. This removes the need to bump | 567 | again. This removes the need to bump :term:`PR` values, and changes to |
567 | :term:`PR` values, and changes to metadata automatically | 568 | metadata automatically ripple across the build. |
568 | ripple across the build. | ||
569 | 569 | ||
570 | It is also worth noting that the end result of these signature | 570 | It is also worth noting that the end result of signature |
571 | generators is to make some dependency and hash information available to | 571 | generators is to make some dependency and hash information available to |
572 | the build. This information includes: | 572 | the build. This information includes: |
573 | 573 | ||
@@ -577,10 +577,7 @@ the build. This information includes: | |||
577 | - ``BB_BASEHASH_``\ *filename:taskname*: The base hashes for each | 577 | - ``BB_BASEHASH_``\ *filename:taskname*: The base hashes for each |
578 | dependent task. | 578 | dependent task. |
579 | 579 | ||
580 | - ``BBHASHDEPS_``\ *filename:taskname*: The task dependencies for | 580 | - :term:`BB_TASKHASH`: The hash of the currently running task. |
581 | each task. | ||
582 | |||
583 | - ``BB_TASKHASH``: The hash of the currently running task. | ||
584 | 581 | ||
585 | It is worth noting that BitBake's "-S" option lets you debug BitBake's | 582 | It is worth noting that BitBake's "-S" option lets you debug BitBake's |
586 | processing of signatures. The options passed to -S allow different | 583 | 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 | |||
589 | simplest parameter to pass is "none", which causes a set of signature | 586 | simplest parameter to pass is "none", which causes a set of signature |
590 | information to be written out into ``STAMPS_DIR`` corresponding to the | 587 | information to be written out into ``STAMPS_DIR`` corresponding to the |
591 | targets specified. The other currently available parameter is | 588 | targets specified. The other currently available parameter is |
592 | "printdiff", which causes BitBake to try to establish the closest | 589 | "printdiff", which causes BitBake to try to establish the most recent |
593 | signature match it can (e.g. in the sstate cache) and then run | 590 | signature match it can (e.g. in the sstate cache) and then run |
594 | ``bitbake-diffsigs`` over the matches to determine the stamps and delta | 591 | compare the matched signatures to determine the stamps and delta |
595 | where these two stamp trees diverge. | 592 | where these two stamp trees diverge. This can be used to determine why |
593 | tasks need to be re-run in situations where that is not expected. | ||
596 | 594 | ||
597 | .. note:: | 595 | .. note:: |
598 | 596 | ||
@@ -647,13 +645,6 @@ compiled binary. To handle this, BitBake calls the | |||
647 | each successful setscene task to know whether or not it needs to obtain | 645 | each successful setscene task to know whether or not it needs to obtain |
648 | the dependencies of that task. | 646 | the dependencies of that task. |
649 | 647 | ||
650 | Finally, after all the setscene tasks have executed, BitBake calls the | ||
651 | function listed in | ||
652 | :term:`BB_SETSCENE_VERIFY_FUNCTION2` | ||
653 | with the list of tasks BitBake thinks has been "covered". The metadata | ||
654 | can then ensure that this list is correct and can inform BitBake that it | ||
655 | wants specific tasks to be run regardless of the setscene result. | ||
656 | |||
657 | You can find more information on setscene metadata in the | 648 | You can find more information on setscene metadata in the |
658 | :ref:`bitbake-user-manual/bitbake-user-manual-metadata:task checksums and setscene` | 649 | :ref:`bitbake-user-manual/bitbake-user-manual-metadata:task checksums and setscene` |
659 | section. | 650 | section. |
@@ -666,7 +657,7 @@ builds are when execute, bitbake also supports user defined | |||
666 | configuration of the `Python | 657 | configuration of the `Python |
667 | logging <https://docs.python.org/3/library/logging.html>`__ facilities | 658 | logging <https://docs.python.org/3/library/logging.html>`__ facilities |
668 | through the :term:`BB_LOGCONFIG` variable. This | 659 | through the :term:`BB_LOGCONFIG` variable. This |
669 | variable defines a json or yaml `logging | 660 | variable defines a JSON or YAML `logging |
670 | configuration <https://docs.python.org/3/library/logging.config.html>`__ | 661 | configuration <https://docs.python.org/3/library/logging.config.html>`__ |
671 | that will be intelligently merged into the default configuration. The | 662 | that will be intelligently merged into the default configuration. The |
672 | logging configuration is merged using the following rules: | 663 | logging configuration is merged using the following rules: |
@@ -700,9 +691,9 @@ logging configuration is merged using the following rules: | |||
700 | adds a filter called ``BitBake.defaultFilter``, both filters will be | 691 | adds a filter called ``BitBake.defaultFilter``, both filters will be |
701 | applied to the logger | 692 | applied to the logger |
702 | 693 | ||
703 | As an example, consider the following user logging configuration file | 694 | As a first example, you can create a ``hashequiv.json`` user logging |
704 | which logs all Hash Equivalence related messages of VERBOSE or higher to | 695 | configuration file to log all Hash Equivalence related messages of ``VERBOSE`` |
705 | a file called ``hashequiv.log`` :: | 696 | or higher priority to a file called ``hashequiv.log``:: |
706 | 697 | ||
707 | { | 698 | { |
708 | "version": 1, | 699 | "version": 1, |
@@ -731,3 +722,40 @@ a file called ``hashequiv.log`` :: | |||
731 | } | 722 | } |
732 | } | 723 | } |
733 | } | 724 | } |
725 | |||
726 | Then set the :term:`BB_LOGCONFIG` variable in ``conf/local.conf``:: | ||
727 | |||
728 | BB_LOGCONFIG = "hashequiv.json" | ||
729 | |||
730 | Another example is this ``warn.json`` file to log all ``WARNING`` and | ||
731 | higher priority messages to a ``warn.log`` file:: | ||
732 | |||
733 | { | ||
734 | "version": 1, | ||
735 | "formatters": { | ||
736 | "warnlogFormatter": { | ||
737 | "()": "bb.msg.BBLogFormatter", | ||
738 | "format": "%(levelname)s: %(message)s" | ||
739 | } | ||
740 | }, | ||
741 | |||
742 | "handlers": { | ||
743 | "warnlog": { | ||
744 | "class": "logging.FileHandler", | ||
745 | "formatter": "warnlogFormatter", | ||
746 | "level": "WARNING", | ||
747 | "filename": "warn.log" | ||
748 | } | ||
749 | }, | ||
750 | |||
751 | "loggers": { | ||
752 | "BitBake": { | ||
753 | "handlers": ["warnlog"] | ||
754 | } | ||
755 | }, | ||
756 | |||
757 | "@disable_existing_loggers": false | ||
758 | } | ||
759 | |||
760 | Note that BitBake's helper classes for structured logging are implemented in | ||
761 | ``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. | |||
27 | Patching, however, is not covered by this module. | 27 | Patching, however, is not covered by this module. |
28 | 28 | ||
29 | The code to execute the first part of this process, a fetch, looks | 29 | The code to execute the first part of this process, a fetch, looks |
30 | something like the following: :: | 30 | something like the following:: |
31 | 31 | ||
32 | src_uri = (d.getVar('SRC_URI') or "").split() | 32 | src_uri = (d.getVar('SRC_URI') or "").split() |
33 | fetcher = bb.fetch2.Fetch(src_uri, d) | 33 | 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 | |||
37 | space-separated list of URLs from the :term:`SRC_URI` | 37 | space-separated list of URLs from the :term:`SRC_URI` |
38 | variable and then calls the ``download`` method to download the files. | 38 | variable and then calls the ``download`` method to download the files. |
39 | 39 | ||
40 | The instantiation of the fetch class is usually followed by: :: | 40 | The instantiation of the fetch class is usually followed by:: |
41 | 41 | ||
42 | rootdir = l.getVar('WORKDIR') | 42 | rootdir = l.getVar('WORKDIR') |
43 | fetcher.unpack(rootdir) | 43 | fetcher.unpack(rootdir) |
@@ -51,7 +51,7 @@ This code unpacks the downloaded files to the specified by ``WORKDIR``. | |||
51 | examine the OpenEmbedded class file ``base.bbclass`` | 51 | examine the OpenEmbedded class file ``base.bbclass`` |
52 | . | 52 | . |
53 | 53 | ||
54 | The ``SRC_URI`` and ``WORKDIR`` variables are not hardcoded into the | 54 | The :term:`SRC_URI` and ``WORKDIR`` variables are not hardcoded into the |
55 | fetcher, since those fetcher methods can be (and are) called with | 55 | fetcher, since those fetcher methods can be (and are) called with |
56 | different variable names. In OpenEmbedded for example, the shared state | 56 | different variable names. In OpenEmbedded for example, the shared state |
57 | (sstate) code uses the fetch module to fetch the sstate files. | 57 | (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: | |||
64 | :term:`PREMIRRORS` variable. | 64 | :term:`PREMIRRORS` variable. |
65 | 65 | ||
66 | - *Source URI:* If pre-mirrors fail, BitBake uses the original URL (e.g | 66 | - *Source URI:* If pre-mirrors fail, BitBake uses the original URL (e.g |
67 | from ``SRC_URI``). | 67 | from :term:`SRC_URI`). |
68 | 68 | ||
69 | - *Mirror Sites:* If fetch failures occur, BitBake next uses mirror | 69 | - *Mirror Sites:* If fetch failures occur, BitBake next uses mirror |
70 | locations as defined by the :term:`MIRRORS` variable. | 70 | locations as defined by the :term:`MIRRORS` variable. |
71 | 71 | ||
72 | For each URL passed to the fetcher, the fetcher calls the submodule that | 72 | For each URL passed to the fetcher, the fetcher calls the submodule that |
73 | handles that particular URL type. This behavior can be the source of | 73 | handles that particular URL type. This behavior can be the source of |
74 | some confusion when you are providing URLs for the ``SRC_URI`` variable. | 74 | some confusion when you are providing URLs for the :term:`SRC_URI` variable. |
75 | Consider the following two URLs: :: | 75 | Consider the following two URLs:: |
76 | 76 | ||
77 | http://git.yoctoproject.org/git/poky;protocol=git | 77 | https://git.yoctoproject.org/git/poky;protocol=git |
78 | git://git.yoctoproject.org/git/poky;protocol=http | 78 | git://git.yoctoproject.org/git/poky;protocol=http |
79 | 79 | ||
80 | In the former case, the URL is passed to the ``wget`` fetcher, which does not | 80 | In the former case, the URL is passed to the ``wget`` fetcher, which does not |
81 | understand "git". Therefore, the latter case is the correct form since the Git | 81 | understand "git". Therefore, the latter case is the correct form since the Git |
82 | fetcher does know how to use HTTP as a transport. | 82 | fetcher does know how to use HTTP as a transport. |
83 | 83 | ||
84 | Here are some examples that show commonly used mirror definitions: :: | 84 | Here are some examples that show commonly used mirror definitions:: |
85 | 85 | ||
86 | PREMIRRORS ?= "\ | 86 | PREMIRRORS ?= "\ |
87 | bzr://.*/.\* http://somemirror.org/sources/ \\n \ | 87 | bzr://.*/.\* http://somemirror.org/sources/ \ |
88 | cvs://.*/.\* http://somemirror.org/sources/ \\n \ | 88 | cvs://.*/.\* http://somemirror.org/sources/ \ |
89 | git://.*/.\* http://somemirror.org/sources/ \\n \ | 89 | git://.*/.\* http://somemirror.org/sources/ \ |
90 | hg://.*/.\* http://somemirror.org/sources/ \\n \ | 90 | hg://.*/.\* http://somemirror.org/sources/ \ |
91 | osc://.*/.\* http://somemirror.org/sources/ \\n \ | 91 | osc://.*/.\* http://somemirror.org/sources/ \ |
92 | p4://.*/.\* http://somemirror.org/sources/ \\n \ | 92 | p4://.*/.\* http://somemirror.org/sources/ \ |
93 | svn://.*/.\* http://somemirror.org/sources/ \\n" | 93 | svn://.*/.\* http://somemirror.org/sources/" |
94 | 94 | ||
95 | MIRRORS =+ "\ | 95 | MIRRORS =+ "\ |
96 | ftp://.*/.\* http://somemirror.org/sources/ \\n \ | 96 | ftp://.*/.\* http://somemirror.org/sources/ \ |
97 | http://.*/.\* http://somemirror.org/sources/ \\n \ | 97 | http://.*/.\* http://somemirror.org/sources/ \ |
98 | https://.*/.\* http://somemirror.org/sources/ \\n" | 98 | https://.*/.\* http://somemirror.org/sources/" |
99 | 99 | ||
100 | It is useful to note that BitBake | 100 | It is useful to note that BitBake |
101 | supports cross-URLs. It is possible to mirror a Git repository on an | 101 | 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. | |||
110 | File integrity is of key importance for reproducing builds. For | 110 | File integrity is of key importance for reproducing builds. For |
111 | non-local archive downloads, the fetcher code can verify SHA-256 and MD5 | 111 | non-local archive downloads, the fetcher code can verify SHA-256 and MD5 |
112 | checksums to ensure the archives have been downloaded correctly. You can | 112 | checksums to ensure the archives have been downloaded correctly. You can |
113 | specify these checksums by using the ``SRC_URI`` variable with the | 113 | specify these checksums by using the :term:`SRC_URI` variable with the |
114 | appropriate varflags as follows: :: | 114 | appropriate varflags as follows:: |
115 | 115 | ||
116 | SRC_URI[md5sum] = "value" | 116 | SRC_URI[md5sum] = "value" |
117 | SRC_URI[sha256sum] = "value" | 117 | SRC_URI[sha256sum] = "value" |
118 | 118 | ||
119 | You can also specify the checksums as | 119 | You can also specify the checksums as |
120 | parameters on the ``SRC_URI`` as shown below: :: | 120 | parameters on the :term:`SRC_URI` as shown below:: |
121 | 121 | ||
122 | SRC_URI = "http://example.com/foobar.tar.bz2;md5sum=4a8e0f237e961fd7785d19d07fdb994d" | 122 | SRC_URI = "http://example.com/foobar.tar.bz2;md5sum=4a8e0f237e961fd7785d19d07fdb994d" |
123 | 123 | ||
124 | If multiple URIs exist, you can specify the checksums either directly as | 124 | If multiple URIs exist, you can specify the checksums either directly as |
125 | in the previous example, or you can name the URLs. The following syntax | 125 | in the previous example, or you can name the URLs. The following syntax |
126 | shows how you name the URIs: :: | 126 | shows how you name the URIs:: |
127 | 127 | ||
128 | SRC_URI = "http://example.com/foobar.tar.bz2;name=foo" | 128 | SRC_URI = "http://example.com/foobar.tar.bz2;name=foo" |
129 | SRC_URI[foo.md5sum] = 4a8e0f237e961fd7785d19d07fdb994d | 129 | SRC_URI[foo.md5sum] = 4a8e0f237e961fd7785d19d07fdb994d |
130 | 130 | ||
131 | After a file has been downloaded and | 131 | After a file has been downloaded and |
132 | has had its checksum checked, a ".done" stamp is placed in ``DL_DIR``. | 132 | has had its checksum checked, a ".done" stamp is placed in :term:`DL_DIR`. |
133 | BitBake uses this stamp during subsequent builds to avoid downloading or | 133 | BitBake uses this stamp during subsequent builds to avoid downloading or |
134 | comparing a checksum for the file again. | 134 | comparing a checksum for the file again. |
135 | 135 | ||
@@ -144,6 +144,10 @@ download without a checksum triggers an error message. The | |||
144 | make any attempted network access a fatal error, which is useful for | 144 | make any attempted network access a fatal error, which is useful for |
145 | checking that mirrors are complete as well as other things. | 145 | checking that mirrors are complete as well as other things. |
146 | 146 | ||
147 | If :term:`BB_CHECK_SSL_CERTS` is set to ``0`` then SSL certificate checking will | ||
148 | be disabled. This variable defaults to ``1`` so SSL certificates are normally | ||
149 | checked. | ||
150 | |||
147 | .. _bb-the-unpack: | 151 | .. _bb-the-unpack: |
148 | 152 | ||
149 | The Unpack | 153 | The Unpack |
@@ -163,8 +167,8 @@ govern the behavior of the unpack stage: | |||
163 | - *dos:* Applies to ``.zip`` and ``.jar`` files and specifies whether | 167 | - *dos:* Applies to ``.zip`` and ``.jar`` files and specifies whether |
164 | to use DOS line ending conversion on text files. | 168 | to use DOS line ending conversion on text files. |
165 | 169 | ||
166 | - *basepath:* Instructs the unpack stage to strip the specified | 170 | - *striplevel:* Strip specified number of leading components (levels) |
167 | directories from the source path when unpacking. | 171 | from file names on extraction |
168 | 172 | ||
169 | - *subdir:* Unpacks the specific URL to the specified subdirectory | 173 | - *subdir:* Unpacks the specific URL to the specified subdirectory |
170 | within the root directory. | 174 | within the root directory. |
@@ -204,7 +208,7 @@ time the ``download()`` method is called. | |||
204 | If you specify a directory, the entire directory is unpacked. | 208 | If you specify a directory, the entire directory is unpacked. |
205 | 209 | ||
206 | Here are a couple of example URLs, the first relative and the second | 210 | Here are a couple of example URLs, the first relative and the second |
207 | absolute: :: | 211 | absolute:: |
208 | 212 | ||
209 | SRC_URI = "file://relativefile.patch" | 213 | SRC_URI = "file://relativefile.patch" |
210 | SRC_URI = "file:///Users/ich/very_important_software" | 214 | SRC_URI = "file:///Users/ich/very_important_software" |
@@ -225,7 +229,12 @@ downloaded file is useful for avoiding collisions in | |||
225 | :term:`DL_DIR` when dealing with multiple files that | 229 | :term:`DL_DIR` when dealing with multiple files that |
226 | have the same name. | 230 | have the same name. |
227 | 231 | ||
228 | Some example URLs are as follows: :: | 232 | If a username and password are specified in the ``SRC_URI``, a Basic |
233 | Authorization header will be added to each request, including across redirects. | ||
234 | To instead limit the Authorization header to the first request, add | ||
235 | "redirectauth=0" to the list of parameters. | ||
236 | |||
237 | Some example URLs are as follows:: | ||
229 | 238 | ||
230 | SRC_URI = "http://oe.handhelds.org/not_there.aac" | 239 | SRC_URI = "http://oe.handhelds.org/not_there.aac" |
231 | SRC_URI = "ftp://oe.handhelds.org/not_there_as_well.aac" | 240 | SRC_URI = "ftp://oe.handhelds.org/not_there_as_well.aac" |
@@ -235,15 +244,13 @@ Some example URLs are as follows: :: | |||
235 | 244 | ||
236 | Because URL parameters are delimited by semi-colons, this can | 245 | Because URL parameters are delimited by semi-colons, this can |
237 | introduce ambiguity when parsing URLs that also contain semi-colons, | 246 | introduce ambiguity when parsing URLs that also contain semi-colons, |
238 | for example: | 247 | for example:: |
239 | :: | ||
240 | 248 | ||
241 | SRC_URI = "http://abc123.org/git/?p=gcc/gcc.git;a=snapshot;h=a5dd47" | 249 | SRC_URI = "http://abc123.org/git/?p=gcc/gcc.git;a=snapshot;h=a5dd47" |
242 | 250 | ||
243 | 251 | ||
244 | Such URLs should should be modified by replacing semi-colons with '&' | 252 | Such URLs should should be modified by replacing semi-colons with '&' |
245 | characters: | 253 | characters:: |
246 | :: | ||
247 | 254 | ||
248 | SRC_URI = "http://abc123.org/git/?p=gcc/gcc.git&a=snapshot&h=a5dd47" | 255 | SRC_URI = "http://abc123.org/git/?p=gcc/gcc.git&a=snapshot&h=a5dd47" |
249 | 256 | ||
@@ -251,8 +258,7 @@ Some example URLs are as follows: :: | |||
251 | In most cases this should work. Treating semi-colons and '&' in | 258 | In most cases this should work. Treating semi-colons and '&' in |
252 | queries identically is recommended by the World Wide Web Consortium | 259 | queries identically is recommended by the World Wide Web Consortium |
253 | (W3C). Note that due to the nature of the URL, you may have to | 260 | (W3C). Note that due to the nature of the URL, you may have to |
254 | specify the name of the downloaded file as well: | 261 | specify the name of the downloaded file as well:: |
255 | :: | ||
256 | 262 | ||
257 | SRC_URI = "http://abc123.org/git/?p=gcc/gcc.git&a=snapshot&h=a5dd47;downloadfilename=myfile.bz2" | 263 | SRC_URI = "http://abc123.org/git/?p=gcc/gcc.git&a=snapshot&h=a5dd47;downloadfilename=myfile.bz2" |
258 | 264 | ||
@@ -321,7 +327,7 @@ The supported parameters are as follows: | |||
321 | 327 | ||
322 | - *"port":* The port to which the CVS server connects. | 328 | - *"port":* The port to which the CVS server connects. |
323 | 329 | ||
324 | Some example URLs are as follows: :: | 330 | Some example URLs are as follows:: |
325 | 331 | ||
326 | SRC_URI = "cvs://CVSROOT;module=mymodule;tag=some-version;method=ext" | 332 | SRC_URI = "cvs://CVSROOT;module=mymodule;tag=some-version;method=ext" |
327 | SRC_URI = "cvs://CVSROOT;module=mymodule;date=20060126;localdir=usethat" | 333 | SRC_URI = "cvs://CVSROOT;module=mymodule;date=20060126;localdir=usethat" |
@@ -363,7 +369,7 @@ The supported parameters are as follows: | |||
363 | username is different than the username used in the main URL, which | 369 | username is different than the username used in the main URL, which |
364 | is passed to the subversion command. | 370 | is passed to the subversion command. |
365 | 371 | ||
366 | Following are three examples using svn: :: | 372 | Following are three examples using svn:: |
367 | 373 | ||
368 | SRC_URI = "svn://myrepos/proj1;module=vip;protocol=http;rev=667" | 374 | SRC_URI = "svn://myrepos/proj1;module=vip;protocol=http;rev=667" |
369 | SRC_URI = "svn://myrepos/proj1;module=opie;protocol=svn+ssh" | 375 | SRC_URI = "svn://myrepos/proj1;module=opie;protocol=svn+ssh" |
@@ -390,6 +396,19 @@ This fetcher supports the following parameters: | |||
390 | protocol is "file". You can also use "http", "https", "ssh" and | 396 | protocol is "file". You can also use "http", "https", "ssh" and |
391 | "rsync". | 397 | "rsync". |
392 | 398 | ||
399 | .. note:: | ||
400 | |||
401 | When ``protocol`` is "ssh", the URL expected in :term:`SRC_URI` differs | ||
402 | from the one that is typically passed to ``git clone`` command and provided | ||
403 | by the Git server to fetch from. For example, the URL returned by GitLab | ||
404 | server for ``mesa`` when cloning over SSH is | ||
405 | ``git@gitlab.freedesktop.org:mesa/mesa.git``, however the expected URL in | ||
406 | :term:`SRC_URI` is the following:: | ||
407 | |||
408 | SRC_URI = "git://git@gitlab.freedesktop.org/mesa/mesa.git;branch=main;protocol=ssh;..." | ||
409 | |||
410 | Note the ``:`` character changed for a ``/`` before the path to the project. | ||
411 | |||
393 | - *"nocheckout":* Tells the fetcher to not checkout source code when | 412 | - *"nocheckout":* Tells the fetcher to not checkout source code when |
394 | unpacking when set to "1". Set this option for the URL where there is | 413 | unpacking when set to "1". Set this option for the URL where there is |
395 | a custom routine to checkout code. The default is "0". | 414 | a custom routine to checkout code. The default is "0". |
@@ -405,17 +424,17 @@ This fetcher supports the following parameters: | |||
405 | 424 | ||
406 | - *"nobranch":* Tells the fetcher to not check the SHA validation for | 425 | - *"nobranch":* Tells the fetcher to not check the SHA validation for |
407 | the branch when set to "1". The default is "0". Set this option for | 426 | the branch when set to "1". The default is "0". Set this option for |
408 | the recipe that refers to the commit that is valid for a tag instead | 427 | the recipe that refers to the commit that is valid for any namespace |
409 | of the branch. | 428 | (branch, tag, ...) instead of the branch. |
410 | 429 | ||
411 | - *"bareclone":* Tells the fetcher to clone a bare clone into the | 430 | - *"bareclone":* Tells the fetcher to clone a bare clone into the |
412 | destination directory without checking out a working tree. Only the | 431 | destination directory without checking out a working tree. Only the |
413 | raw Git metadata is provided. This parameter implies the "nocheckout" | 432 | raw Git metadata is provided. This parameter implies the "nocheckout" |
414 | parameter as well. | 433 | parameter as well. |
415 | 434 | ||
416 | - *"branch":* The branch(es) of the Git tree to clone. If unset, this | 435 | - *"branch":* The branch(es) of the Git tree to clone. Unless |
417 | is assumed to be "master". The number of branch parameters much match | 436 | "nobranch" is set to "1", this is a mandatory parameter. The number of |
418 | the number of name parameters. | 437 | branch parameters must match the number of name parameters. |
419 | 438 | ||
420 | - *"rev":* The revision to use for the checkout. The default is | 439 | - *"rev":* The revision to use for the checkout. The default is |
421 | "master". | 440 | "master". |
@@ -436,10 +455,35 @@ This fetcher supports the following parameters: | |||
436 | parameter implies no branch and only works when the transfer protocol | 455 | parameter implies no branch and only works when the transfer protocol |
437 | is ``file://``. | 456 | is ``file://``. |
438 | 457 | ||
439 | Here are some example URLs: :: | 458 | Here are some example URLs:: |
459 | |||
460 | SRC_URI = "git://github.com/fronteed/icheck.git;protocol=https;branch=${PV};tag=${PV}" | ||
461 | SRC_URI = "git://github.com/asciidoc/asciidoc-py;protocol=https;branch=main" | ||
462 | SRC_URI = "git://git@gitlab.freedesktop.org/mesa/mesa.git;branch=main;protocol=ssh;..." | ||
463 | |||
464 | .. note:: | ||
440 | 465 | ||
441 | SRC_URI = "git://git.oe.handhelds.org/git/vip.git;tag=version-1" | 466 | When using ``git`` as the fetcher of the main source code of your software, |
442 | SRC_URI = "git://git.oe.handhelds.org/git/vip.git;protocol=http" | 467 | ``S`` should be set accordingly:: |
468 | |||
469 | S = "${WORKDIR}/git" | ||
470 | |||
471 | .. note:: | ||
472 | |||
473 | Specifying passwords directly in ``git://`` urls is not supported. | ||
474 | There are several reasons: :term:`SRC_URI` is often written out to logs and | ||
475 | other places, and that could easily leak passwords; it is also all too | ||
476 | easy to share metadata without removing passwords. SSH keys, ``~/.netrc`` | ||
477 | and ``~/.ssh/config`` files can be used as alternatives. | ||
478 | |||
479 | Using tags with the git fetcher may cause surprising behaviour. Bitbake needs to | ||
480 | resolve the tag to a specific revision and to do that, it has to connect to and use | ||
481 | the upstream repository. This is because the revision the tags point at can change and | ||
482 | we've seen cases of this happening in well known public repositories. This can mean | ||
483 | many more network connections than expected and recipes may be reparsed at every build. | ||
484 | Source mirrors will also be bypassed as the upstream repository is the only source | ||
485 | of truth to resolve the revision accurately. For these reasons, whilst the fetcher | ||
486 | can support tags, we recommend being specific about revisions in recipes. | ||
443 | 487 | ||
444 | .. _gitsm-fetcher: | 488 | .. _gitsm-fetcher: |
445 | 489 | ||
@@ -475,7 +519,7 @@ repository. | |||
475 | 519 | ||
476 | To use this fetcher, make sure your recipe has proper | 520 | To use this fetcher, make sure your recipe has proper |
477 | :term:`SRC_URI`, :term:`SRCREV`, and | 521 | :term:`SRC_URI`, :term:`SRCREV`, and |
478 | :term:`PV` settings. Here is an example: :: | 522 | :term:`PV` settings. Here is an example:: |
479 | 523 | ||
480 | SRC_URI = "ccrc://cc.example.org/ccrc;vob=/example_vob;module=/example_module" | 524 | SRC_URI = "ccrc://cc.example.org/ccrc;vob=/example_vob;module=/example_module" |
481 | SRCREV = "EXAMPLE_CLEARCASE_TAG" | 525 | SRCREV = "EXAMPLE_CLEARCASE_TAG" |
@@ -484,7 +528,7 @@ To use this fetcher, make sure your recipe has proper | |||
484 | The fetcher uses the ``rcleartool`` or | 528 | The fetcher uses the ``rcleartool`` or |
485 | ``cleartool`` remote client, depending on which one is available. | 529 | ``cleartool`` remote client, depending on which one is available. |
486 | 530 | ||
487 | Following are options for the ``SRC_URI`` statement: | 531 | Following are options for the :term:`SRC_URI` statement: |
488 | 532 | ||
489 | - *vob*: The name, which must include the prepending "/" character, | 533 | - *vob*: The name, which must include the prepending "/" character, |
490 | of the ClearCase VOB. This option is required. | 534 | of the ClearCase VOB. This option is required. |
@@ -497,7 +541,7 @@ Following are options for the ``SRC_URI`` statement: | |||
497 | The module and vob options are combined to create the load rule in the | 541 | The module and vob options are combined to create the load rule in the |
498 | view config spec. As an example, consider the vob and module values from | 542 | view config spec. As an example, consider the vob and module values from |
499 | the SRC_URI statement at the start of this section. Combining those values | 543 | the SRC_URI statement at the start of this section. Combining those values |
500 | results in the following: :: | 544 | results in the following:: |
501 | 545 | ||
502 | load /example_vob/example_module | 546 | load /example_vob/example_module |
503 | 547 | ||
@@ -546,10 +590,10 @@ password if you do not wish to keep those values in a recipe itself. If | |||
546 | you choose not to use ``P4CONFIG``, or to explicitly set variables that | 590 | you choose not to use ``P4CONFIG``, or to explicitly set variables that |
547 | ``P4CONFIG`` can contain, you can specify the ``P4PORT`` value, which is | 591 | ``P4CONFIG`` can contain, you can specify the ``P4PORT`` value, which is |
548 | the server's URL and port number, and you can specify a username and | 592 | the server's URL and port number, and you can specify a username and |
549 | password directly in your recipe within ``SRC_URI``. | 593 | password directly in your recipe within :term:`SRC_URI`. |
550 | 594 | ||
551 | Here is an example that relies on ``P4CONFIG`` to specify the server URL | 595 | Here is an example that relies on ``P4CONFIG`` to specify the server URL |
552 | and port, username, and password, and fetches the Head Revision: :: | 596 | and port, username, and password, and fetches the Head Revision:: |
553 | 597 | ||
554 | SRC_URI = "p4://example-depot/main/source/..." | 598 | SRC_URI = "p4://example-depot/main/source/..." |
555 | SRCREV = "${AUTOREV}" | 599 | SRCREV = "${AUTOREV}" |
@@ -557,7 +601,7 @@ and port, username, and password, and fetches the Head Revision: :: | |||
557 | S = "${WORKDIR}/p4" | 601 | S = "${WORKDIR}/p4" |
558 | 602 | ||
559 | Here is an example that specifies the server URL and port, username, and | 603 | Here is an example that specifies the server URL and port, username, and |
560 | password, and fetches a Revision based on a Label: :: | 604 | password, and fetches a Revision based on a Label:: |
561 | 605 | ||
562 | P4PORT = "tcp:p4server.example.net:1666" | 606 | P4PORT = "tcp:p4server.example.net:1666" |
563 | SRC_URI = "p4://user:passwd@example-depot/main/source/..." | 607 | SRC_URI = "p4://user:passwd@example-depot/main/source/..." |
@@ -583,7 +627,7 @@ paths locally is desirable, the fetcher supports two parameters: | |||
583 | paths locally for the specified location, even in combination with the | 627 | paths locally for the specified location, even in combination with the |
584 | ``module`` parameter. | 628 | ``module`` parameter. |
585 | 629 | ||
586 | Here is an example use of the the ``module`` parameter: :: | 630 | Here is an example use of the the ``module`` parameter:: |
587 | 631 | ||
588 | SRC_URI = "p4://user:passwd@example-depot/main;module=source/..." | 632 | SRC_URI = "p4://user:passwd@example-depot/main;module=source/..." |
589 | 633 | ||
@@ -591,7 +635,7 @@ In this case, the content of the top-level directory ``source/`` will be fetched | |||
591 | to ``${P4DIR}``, including the directory itself. The top-level directory will | 635 | to ``${P4DIR}``, including the directory itself. The top-level directory will |
592 | be accesible at ``${P4DIR}/source/``. | 636 | be accesible at ``${P4DIR}/source/``. |
593 | 637 | ||
594 | Here is an example use of the the ``remotepath`` parameter: :: | 638 | Here is an example use of the the ``remotepath`` parameter:: |
595 | 639 | ||
596 | SRC_URI = "p4://user:passwd@example-depot/main;module=source/...;remotepath=keep" | 640 | SRC_URI = "p4://user:passwd@example-depot/main;module=source/...;remotepath=keep" |
597 | 641 | ||
@@ -619,11 +663,166 @@ This fetcher supports the following parameters: | |||
619 | 663 | ||
620 | - *"manifest":* Name of the manifest file (default: ``default.xml``). | 664 | - *"manifest":* Name of the manifest file (default: ``default.xml``). |
621 | 665 | ||
622 | Here are some example URLs: :: | 666 | Here are some example URLs:: |
623 | 667 | ||
624 | SRC_URI = "repo://REPOROOT;protocol=git;branch=some_branch;manifest=my_manifest.xml" | 668 | SRC_URI = "repo://REPOROOT;protocol=git;branch=some_branch;manifest=my_manifest.xml" |
625 | SRC_URI = "repo://REPOROOT;protocol=file;branch=some_branch;manifest=my_manifest.xml" | 669 | SRC_URI = "repo://REPOROOT;protocol=file;branch=some_branch;manifest=my_manifest.xml" |
626 | 670 | ||
671 | .. _az-fetcher: | ||
672 | |||
673 | Az Fetcher (``az://``) | ||
674 | -------------------------- | ||
675 | |||
676 | This submodule fetches data from an | ||
677 | `Azure Storage account <https://docs.microsoft.com/en-us/azure/storage/>`__ , | ||
678 | it inherits its functionality from the HTTP wget fetcher, but modifies its | ||
679 | behavior to accomodate the usage of a | ||
680 | `Shared Access Signature (SAS) <https://docs.microsoft.com/en-us/azure/storage/common/storage-sas-overview>`__ | ||
681 | for non-public data. | ||
682 | |||
683 | Such functionality is set by the variable: | ||
684 | |||
685 | - :term:`AZ_SAS`: The Azure Storage Shared Access Signature provides secure | ||
686 | delegate access to resources, if this variable is set, the Az Fetcher will | ||
687 | use it when fetching artifacts from the cloud. | ||
688 | |||
689 | You can specify the AZ_SAS variable as shown below:: | ||
690 | |||
691 | AZ_SAS = "se=2021-01-01&sp=r&sv=2018-11-09&sr=c&skoid=<skoid>&sig=<signature>" | ||
692 | |||
693 | Here is an example URL:: | ||
694 | |||
695 | SRC_URI = "az://<azure-storage-account>.blob.core.windows.net/<foo_container>/<bar_file>" | ||
696 | |||
697 | It can also be used when setting mirrors definitions using the :term:`PREMIRRORS` variable. | ||
698 | |||
699 | .. _gcp-fetcher: | ||
700 | |||
701 | GCP Fetcher (``gs://``) | ||
702 | -------------------------- | ||
703 | |||
704 | This submodule fetches data from a | ||
705 | `Google Cloud Storage Bucket <https://cloud.google.com/storage/docs/buckets>`__. | ||
706 | It uses the `Google Cloud Storage Python Client <https://cloud.google.com/python/docs/reference/storage/latest>`__ | ||
707 | to check the status of objects in the bucket and download them. | ||
708 | The use of the Python client makes it substantially faster than using command | ||
709 | line tools such as gsutil. | ||
710 | |||
711 | The fetcher requires the Google Cloud Storage Python Client to be installed, along | ||
712 | with the gsutil tool. | ||
713 | |||
714 | The fetcher requires that the machine has valid credentials for accessing the | ||
715 | chosen bucket. Instructions for authentication can be found in the | ||
716 | `Google Cloud documentation <https://cloud.google.com/docs/authentication/provide-credentials-adc#local-dev>`__. | ||
717 | |||
718 | If it used from the OpenEmbedded build system, the fetcher can be used for | ||
719 | fetching sstate artifacts from a GCS bucket by specifying the | ||
720 | ``SSTATE_MIRRORS`` variable as shown below:: | ||
721 | |||
722 | SSTATE_MIRRORS ?= "\ | ||
723 | file://.* gs://<bucket name>/PATH \ | ||
724 | " | ||
725 | |||
726 | The fetcher can also be used in recipes:: | ||
727 | |||
728 | SRC_URI = "gs://<bucket name>/<foo_container>/<bar_file>" | ||
729 | |||
730 | However, the checksum of the file should be also be provided:: | ||
731 | |||
732 | SRC_URI[sha256sum] = "<sha256 string>" | ||
733 | |||
734 | .. _crate-fetcher: | ||
735 | |||
736 | Crate Fetcher (``crate://``) | ||
737 | ---------------------------- | ||
738 | |||
739 | This submodule fetches code for | ||
740 | `Rust language "crates" <https://doc.rust-lang.org/reference/glossary.html?highlight=crate#crate>`__ | ||
741 | corresponding to Rust libraries and programs to compile. Such crates are typically shared | ||
742 | on https://crates.io/ but this fetcher supports other crate registries too. | ||
743 | |||
744 | The format for the :term:`SRC_URI` setting must be:: | ||
745 | |||
746 | SRC_URI = "crate://REGISTRY/NAME/VERSION" | ||
747 | |||
748 | Here is an example URL:: | ||
749 | |||
750 | SRC_URI = "crate://crates.io/glob/0.2.11" | ||
751 | |||
752 | .. _npm-fetcher: | ||
753 | |||
754 | NPM Fetcher (``npm://``) | ||
755 | ------------------------ | ||
756 | |||
757 | This submodule fetches source code from an | ||
758 | `NPM <https://en.wikipedia.org/wiki/Npm_(software)>`__ | ||
759 | Javascript package registry. | ||
760 | |||
761 | The format for the :term:`SRC_URI` setting must be:: | ||
762 | |||
763 | SRC_URI = "npm://some.registry.url;ParameterA=xxx;ParameterB=xxx;..." | ||
764 | |||
765 | This fetcher supports the following parameters: | ||
766 | |||
767 | - *"package":* The NPM package name. This is a mandatory parameter. | ||
768 | |||
769 | - *"version":* The NPM package version. This is a mandatory parameter. | ||
770 | |||
771 | - *"downloadfilename":* Specifies the filename used when storing the downloaded file. | ||
772 | |||
773 | - *"destsuffix":* Specifies the directory to use to unpack the package (default: ``npm``). | ||
774 | |||
775 | Note that NPM fetcher only fetches the package source itself. The dependencies | ||
776 | can be fetched through the `npmsw-fetcher`_. | ||
777 | |||
778 | Here is an example URL with both fetchers:: | ||
779 | |||
780 | SRC_URI = " \ | ||
781 | npm://registry.npmjs.org/;package=cute-files;version=${PV} \ | ||
782 | npmsw://${THISDIR}/${BPN}/npm-shrinkwrap.json \ | ||
783 | " | ||
784 | |||
785 | See :yocto_docs:`Creating Node Package Manager (NPM) Packages | ||
786 | </dev-manual/packages.html#creating-node-package-manager-npm-packages>` | ||
787 | in the Yocto Project manual for details about using | ||
788 | :yocto_docs:`devtool <https://docs.yoctoproject.org/ref-manual/devtool-reference.html>` | ||
789 | to automatically create a recipe from an NPM URL. | ||
790 | |||
791 | .. _npmsw-fetcher: | ||
792 | |||
793 | NPM shrinkwrap Fetcher (``npmsw://``) | ||
794 | ------------------------------------- | ||
795 | |||
796 | This submodule fetches source code from an | ||
797 | `NPM shrinkwrap <https://docs.npmjs.com/cli/v8/commands/npm-shrinkwrap>`__ | ||
798 | description file, which lists the dependencies | ||
799 | of an NPM package while locking their versions. | ||
800 | |||
801 | The format for the :term:`SRC_URI` setting must be:: | ||
802 | |||
803 | SRC_URI = "npmsw://some.registry.url;ParameterA=xxx;ParameterB=xxx;..." | ||
804 | |||
805 | This fetcher supports the following parameters: | ||
806 | |||
807 | - *"dev":* Set this parameter to ``1`` to install "devDependencies". | ||
808 | |||
809 | - *"destsuffix":* Specifies the directory to use to unpack the dependencies | ||
810 | (``${S}`` by default). | ||
811 | |||
812 | Note that the shrinkwrap file can also be provided by the recipe for | ||
813 | the package which has such dependencies, for example:: | ||
814 | |||
815 | SRC_URI = " \ | ||
816 | npm://registry.npmjs.org/;package=cute-files;version=${PV} \ | ||
817 | npmsw://${THISDIR}/${BPN}/npm-shrinkwrap.json \ | ||
818 | " | ||
819 | |||
820 | Such a file can automatically be generated using | ||
821 | :yocto_docs:`devtool <https://docs.yoctoproject.org/ref-manual/devtool-reference.html>` | ||
822 | as described in the :yocto_docs:`Creating Node Package Manager (NPM) Packages | ||
823 | </dev-manual/packages.html#creating-node-package-manager-npm-packages>` | ||
824 | section of the Yocto Project. | ||
825 | |||
627 | Other Fetchers | 826 | Other Fetchers |
628 | -------------- | 827 | -------------- |
629 | 828 | ||
@@ -633,10 +832,10 @@ Fetch submodules also exist for the following: | |||
633 | 832 | ||
634 | - Mercurial (``hg://``) | 833 | - Mercurial (``hg://``) |
635 | 834 | ||
636 | - npm (``npm://``) | ||
637 | |||
638 | - OSC (``osc://``) | 835 | - OSC (``osc://``) |
639 | 836 | ||
837 | - S3 (``s3://``) | ||
838 | |||
640 | - Secure FTP (``sftp://``) | 839 | - Secure FTP (``sftp://``) |
641 | 840 | ||
642 | - Secure Shell (``ssh://``) | 841 | - Secure Shell (``ssh://``) |
@@ -649,4 +848,4 @@ submodules. However, you might find the code helpful and readable. | |||
649 | Auto Revisions | 848 | Auto Revisions |
650 | ============== | 849 | ============== |
651 | 850 | ||
652 | We need to document ``AUTOREV`` and ``SRCREV_FORMAT`` here. | 851 | 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. | |||
18 | Obtaining BitBake | 18 | Obtaining BitBake |
19 | ================= | 19 | ================= |
20 | 20 | ||
21 | See the :ref:`bitbake-user-manual/bitbake-user-manual-hello:obtaining bitbake` section for | 21 | See the :ref:`bitbake-user-manual/bitbake-user-manual-intro:obtaining bitbake` section for |
22 | information on how to obtain BitBake. Once you have the source code on | 22 | information on how to obtain BitBake. Once you have the source code on |
23 | your machine, the BitBake directory appears as follows: :: | 23 | your machine, the BitBake directory appears as follows:: |
24 | 24 | ||
25 | $ ls -al | 25 | $ ls -al |
26 | total 100 | 26 | total 108 |
27 | drwxrwxr-x. 9 wmat wmat 4096 Jan 31 13:44 . | 27 | drwxr-xr-x 9 fawkh 10000 4096 feb 24 12:10 . |
28 | drwxrwxr-x. 3 wmat wmat 4096 Feb 4 10:45 .. | 28 | drwx------ 36 fawkh 10000 4096 mar 2 17:00 .. |
29 | -rw-rw-r--. 1 wmat wmat 365 Nov 26 04:55 AUTHORS | 29 | -rw-r--r-- 1 fawkh 10000 365 feb 24 12:10 AUTHORS |
30 | drwxrwxr-x. 2 wmat wmat 4096 Nov 26 04:55 bin | 30 | drwxr-xr-x 2 fawkh 10000 4096 feb 24 12:10 bin |
31 | drwxrwxr-x. 4 wmat wmat 4096 Jan 31 13:44 build | 31 | -rw-r--r-- 1 fawkh 10000 16501 feb 24 12:10 ChangeLog |
32 | -rw-rw-r--. 1 wmat wmat 16501 Nov 26 04:55 ChangeLog | 32 | drwxr-xr-x 2 fawkh 10000 4096 feb 24 12:10 classes |
33 | drwxrwxr-x. 2 wmat wmat 4096 Nov 26 04:55 classes | 33 | drwxr-xr-x 2 fawkh 10000 4096 feb 24 12:10 conf |
34 | drwxrwxr-x. 2 wmat wmat 4096 Nov 26 04:55 conf | 34 | drwxr-xr-x 5 fawkh 10000 4096 feb 24 12:10 contrib |
35 | drwxrwxr-x. 3 wmat wmat 4096 Nov 26 04:55 contrib | 35 | drwxr-xr-x 6 fawkh 10000 4096 feb 24 12:10 doc |
36 | -rw-rw-r--. 1 wmat wmat 17987 Nov 26 04:55 COPYING | 36 | drwxr-xr-x 8 fawkh 10000 4096 mar 2 16:26 .git |
37 | drwxrwxr-x. 3 wmat wmat 4096 Nov 26 04:55 doc | 37 | -rw-r--r-- 1 fawkh 10000 31 feb 24 12:10 .gitattributes |
38 | -rw-rw-r--. 1 wmat wmat 69 Nov 26 04:55 .gitignore | 38 | -rw-r--r-- 1 fawkh 10000 392 feb 24 12:10 .gitignore |
39 | -rw-rw-r--. 1 wmat wmat 849 Nov 26 04:55 HEADER | 39 | drwxr-xr-x 13 fawkh 10000 4096 feb 24 12:11 lib |
40 | drwxrwxr-x. 5 wmat wmat 4096 Jan 31 13:44 lib | 40 | -rw-r--r-- 1 fawkh 10000 1224 feb 24 12:10 LICENSE |
41 | -rw-rw-r--. 1 wmat wmat 195 Nov 26 04:55 MANIFEST.in | 41 | -rw-r--r-- 1 fawkh 10000 15394 feb 24 12:10 LICENSE.GPL-2.0-only |
42 | -rw-rw-r--. 1 wmat wmat 2887 Nov 26 04:55 TODO | 42 | -rw-r--r-- 1 fawkh 10000 1286 feb 24 12:10 LICENSE.MIT |
43 | -rw-r--r-- 1 fawkh 10000 229 feb 24 12:10 MANIFEST.in | ||
44 | -rw-r--r-- 1 fawkh 10000 2413 feb 24 12:10 README | ||
45 | -rw-r--r-- 1 fawkh 10000 43 feb 24 12:10 toaster-requirements.txt | ||
46 | -rw-r--r-- 1 fawkh 10000 2887 feb 24 12:10 TODO | ||
43 | 47 | ||
44 | At this point, you should have BitBake cloned to a directory that | 48 | At this point, you should have BitBake cloned to a directory that |
45 | matches the previous listing except for dates and user names. | 49 | matches the previous listing except for dates and user names. |
@@ -49,10 +53,10 @@ Setting Up the BitBake Environment | |||
49 | 53 | ||
50 | First, you need to be sure that you can run BitBake. Set your working | 54 | First, you need to be sure that you can run BitBake. Set your working |
51 | directory to where your local BitBake files are and run the following | 55 | directory to where your local BitBake files are and run the following |
52 | command: :: | 56 | command:: |
53 | 57 | ||
54 | $ ./bin/bitbake --version | 58 | $ ./bin/bitbake --version |
55 | BitBake Build Tool Core version 1.23.0, bitbake version 1.23.0 | 59 | BitBake Build Tool Core version 2.3.1 |
56 | 60 | ||
57 | The console output tells you what version | 61 | The console output tells you what version |
58 | you are running. | 62 | you are running. |
@@ -61,14 +65,14 @@ The recommended method to run BitBake is from a directory of your | |||
61 | choice. To be able to run BitBake from any directory, you need to add | 65 | choice. To be able to run BitBake from any directory, you need to add |
62 | the executable binary to your binary to your shell's environment | 66 | the executable binary to your binary to your shell's environment |
63 | ``PATH`` variable. First, look at your current ``PATH`` variable by | 67 | ``PATH`` variable. First, look at your current ``PATH`` variable by |
64 | entering the following: :: | 68 | entering the following:: |
65 | 69 | ||
66 | $ echo $PATH | 70 | $ echo $PATH |
67 | 71 | ||
68 | Next, add the directory location | 72 | Next, add the directory location |
69 | for the BitBake binary to the ``PATH``. Here is an example that adds the | 73 | for the BitBake binary to the ``PATH``. Here is an example that adds the |
70 | ``/home/scott-lenovo/bitbake/bin`` directory to the front of the | 74 | ``/home/scott-lenovo/bitbake/bin`` directory to the front of the |
71 | ``PATH`` variable: :: | 75 | ``PATH`` variable:: |
72 | 76 | ||
73 | $ export PATH=/home/scott-lenovo/bitbake/bin:$PATH | 77 | $ export PATH=/home/scott-lenovo/bitbake/bin:$PATH |
74 | 78 | ||
@@ -99,7 +103,7 @@ discussion mailing list about the BitBake build tool. | |||
99 | 103 | ||
100 | This example was inspired by and drew heavily from | 104 | This example was inspired by and drew heavily from |
101 | `Mailing List post - The BitBake equivalent of "Hello, World!" | 105 | `Mailing List post - The BitBake equivalent of "Hello, World!" |
102 | <http://www.mail-archive.com/yocto@yoctoproject.org/msg09379.html>`_. | 106 | <https://www.mail-archive.com/yocto@yoctoproject.org/msg09379.html>`_. |
103 | 107 | ||
104 | As stated earlier, the goal of this example is to eventually compile | 108 | As stated earlier, the goal of this example is to eventually compile |
105 | "Hello World". However, it is unknown what BitBake needs and what you | 109 | "Hello World". However, it is unknown what BitBake needs and what you |
@@ -116,7 +120,7 @@ Following is the complete "Hello World" example. | |||
116 | 120 | ||
117 | #. **Create a Project Directory:** First, set up a directory for the | 121 | #. **Create a Project Directory:** First, set up a directory for the |
118 | "Hello World" project. Here is how you can do so in your home | 122 | "Hello World" project. Here is how you can do so in your home |
119 | directory: :: | 123 | directory:: |
120 | 124 | ||
121 | $ mkdir ~/hello | 125 | $ mkdir ~/hello |
122 | $ cd ~/hello | 126 | $ cd ~/hello |
@@ -127,41 +131,26 @@ Following is the complete "Hello World" example. | |||
127 | directory is a good way to isolate your project. | 131 | directory is a good way to isolate your project. |
128 | 132 | ||
129 | #. **Run BitBake:** At this point, you have nothing but a project | 133 | #. **Run BitBake:** At this point, you have nothing but a project |
130 | directory. Run the ``bitbake`` command and see what it does: :: | 134 | directory. Run the ``bitbake`` command and see what it does:: |
131 | 135 | ||
132 | $ bitbake | 136 | $ bitbake |
133 | The BBPATH variable is not set and bitbake did not | 137 | ERROR: The BBPATH variable is not set and bitbake did not find a conf/bblayers.conf file in the expected location. |
134 | find a conf/bblayers.conf file in the expected location. | ||
135 | Maybe you accidentally invoked bitbake from the wrong directory? | 138 | Maybe you accidentally invoked bitbake from the wrong directory? |
136 | DEBUG: Removed the following variables from the environment: | ||
137 | GNOME_DESKTOP_SESSION_ID, XDG_CURRENT_DESKTOP, | ||
138 | GNOME_KEYRING_CONTROL, DISPLAY, SSH_AGENT_PID, LANG, no_proxy, | ||
139 | XDG_SESSION_PATH, XAUTHORITY, SESSION_MANAGER, SHLVL, | ||
140 | MANDATORY_PATH, COMPIZ_CONFIG_PROFILE, WINDOWID, EDITOR, | ||
141 | GPG_AGENT_INFO, SSH_AUTH_SOCK, GDMSESSION, GNOME_KEYRING_PID, | ||
142 | XDG_SEAT_PATH, XDG_CONFIG_DIRS, LESSOPEN, DBUS_SESSION_BUS_ADDRESS, | ||
143 | _, XDG_SESSION_COOKIE, DESKTOP_SESSION, LESSCLOSE, DEFAULTS_PATH, | ||
144 | UBUNTU_MENUPROXY, OLDPWD, XDG_DATA_DIRS, COLORTERM, LS_COLORS | ||
145 | |||
146 | The majority of this output is specific to environment variables that | ||
147 | are not directly relevant to BitBake. However, the very first | ||
148 | message regarding the ``BBPATH`` variable and the | ||
149 | ``conf/bblayers.conf`` file is relevant. | ||
150 | 139 | ||
151 | When you run BitBake, it begins looking for metadata files. The | 140 | When you run BitBake, it begins looking for metadata files. The |
152 | :term:`BBPATH` variable is what tells BitBake where | 141 | :term:`BBPATH` variable is what tells BitBake where |
153 | to look for those files. ``BBPATH`` is not set and you need to set | 142 | to look for those files. :term:`BBPATH` is not set and you need to set |
154 | it. Without ``BBPATH``, BitBake cannot find any configuration files | 143 | it. Without :term:`BBPATH`, BitBake cannot find any configuration files |
155 | (``.conf``) or recipe files (``.bb``) at all. BitBake also cannot | 144 | (``.conf``) or recipe files (``.bb``) at all. BitBake also cannot |
156 | find the ``bitbake.conf`` file. | 145 | find the ``bitbake.conf`` file. |
157 | 146 | ||
158 | #. **Setting BBPATH:** For this example, you can set ``BBPATH`` in | 147 | #. **Setting BBPATH:** For this example, you can set :term:`BBPATH` in |
159 | the same manner that you set ``PATH`` earlier in the appendix. You | 148 | the same manner that you set ``PATH`` earlier in the appendix. You |
160 | should realize, though, that it is much more flexible to set the | 149 | should realize, though, that it is much more flexible to set the |
161 | ``BBPATH`` variable up in a configuration file for each project. | 150 | :term:`BBPATH` variable up in a configuration file for each project. |
162 | 151 | ||
163 | From your shell, enter the following commands to set and export the | 152 | From your shell, enter the following commands to set and export the |
164 | ``BBPATH`` variable: :: | 153 | :term:`BBPATH` variable:: |
165 | 154 | ||
166 | $ BBPATH="projectdirectory" | 155 | $ BBPATH="projectdirectory" |
167 | $ export BBPATH | 156 | $ export BBPATH |
@@ -175,24 +164,18 @@ Following is the complete "Hello World" example. | |||
175 | ("~") character as BitBake does not expand that character as the | 164 | ("~") character as BitBake does not expand that character as the |
176 | shell would. | 165 | shell would. |
177 | 166 | ||
178 | #. **Run BitBake:** Now that you have ``BBPATH`` defined, run the | 167 | #. **Run BitBake:** Now that you have :term:`BBPATH` defined, run the |
179 | ``bitbake`` command again: :: | 168 | ``bitbake`` command again:: |
180 | 169 | ||
181 | $ bitbake | 170 | $ bitbake |
182 | ERROR: Traceback (most recent call last): | 171 | ERROR: Unable to parse /home/scott-lenovo/bitbake/lib/bb/parse/__init__.py |
183 | File "/home/scott-lenovo/bitbake/lib/bb/cookerdata.py", line 163, in wrapped | 172 | Traceback (most recent call last): |
184 | return func(fn, *args) | 173 | 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>): |
185 | File "/home/scott-lenovo/bitbake/lib/bb/cookerdata.py", line 173, in parse_config_file | 174 | if not newfn: |
186 | return bb.parse.handle(fn, data, include) | 175 | > raise IOError(errno.ENOENT, "file %s not found in %s" % (fn, bbpath)) |
187 | File "/home/scott-lenovo/bitbake/lib/bb/parse/__init__.py", line 99, in handle | 176 | fn = newfn |
188 | return h['handle'](fn, data, include) | 177 | FileNotFoundError: [Errno 2] file conf/bitbake.conf not found in <projectdirectory> |
189 | File "/home/scott-lenovo/bitbake/lib/bb/parse/parse_py/ConfHandler.py", line 120, in handle | 178 | |
190 | abs_fn = resolve_file(fn, data) | ||
191 | File "/home/scott-lenovo/bitbake/lib/bb/parse/__init__.py", line 117, in resolve_file | ||
192 | raise IOError("file %s not found in %s" % (fn, bbpath)) | ||
193 | IOError: file conf/bitbake.conf not found in /home/scott-lenovo/hello | ||
194 | |||
195 | ERROR: Unable to parse conf/bitbake.conf: file conf/bitbake.conf not found in /home/scott-lenovo/hello | ||
196 | 179 | ||
197 | This sample output shows that BitBake could not find the | 180 | This sample output shows that BitBake could not find the |
198 | ``conf/bitbake.conf`` file in the project directory. This file is | 181 | ``conf/bitbake.conf`` file in the project directory. This file is |
@@ -205,18 +188,18 @@ Following is the complete "Hello World" example. | |||
205 | recipe files. For this example, you need to create the file in your | 188 | recipe files. For this example, you need to create the file in your |
206 | project directory and define some key BitBake variables. For more | 189 | project directory and define some key BitBake variables. For more |
207 | information on the ``bitbake.conf`` file, see | 190 | information on the ``bitbake.conf`` file, see |
208 | http://git.openembedded.org/bitbake/tree/conf/bitbake.conf. | 191 | https://git.openembedded.org/bitbake/tree/conf/bitbake.conf. |
209 | 192 | ||
210 | Use the following commands to create the ``conf`` directory in the | 193 | Use the following commands to create the ``conf`` directory in the |
211 | project directory: :: | 194 | project directory:: |
212 | 195 | ||
213 | $ mkdir conf | 196 | $ mkdir conf |
214 | 197 | ||
215 | From within the ``conf`` directory, | 198 | From within the ``conf`` directory, |
216 | use some editor to create the ``bitbake.conf`` so that it contains | 199 | use some editor to create the ``bitbake.conf`` so that it contains |
217 | the following: :: | 200 | the following:: |
218 | 201 | ||
219 | PN = "${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE', False),d)[0] or 'defaultpkgname'}" | 202 | PN = "${@bb.parse.vars_from_file(d.getVar('FILE', False),d)[0] or 'defaultpkgname'}" |
220 | 203 | ||
221 | TMPDIR = "${TOPDIR}/tmp" | 204 | TMPDIR = "${TOPDIR}/tmp" |
222 | CACHE = "${TMPDIR}/cache" | 205 | CACHE = "${TMPDIR}/cache" |
@@ -226,12 +209,12 @@ Following is the complete "Hello World" example. | |||
226 | 209 | ||
227 | .. note:: | 210 | .. note:: |
228 | 211 | ||
229 | Without a value for PN , the variables STAMP , T , and B , prevent more | 212 | Without a value for :term:`PN`, the variables :term:`STAMP`, :term:`T`, and :term:`B`, prevent more |
230 | than one recipe from working. You can fix this by either setting PN to | 213 | than one recipe from working. You can fix this by either setting :term:`PN` to |
231 | have a value similar to what OpenEmbedded and BitBake use in the default | 214 | have a value similar to what OpenEmbedded and BitBake use in the default |
232 | bitbake.conf file (see previous example). Or, by manually updating each | 215 | ``bitbake.conf`` file (see previous example). Or, by manually updating each |
233 | recipe to set PN . You will also need to include PN as part of the STAMP | 216 | recipe to set :term:`PN`. You will also need to include :term:`PN` as part of the :term:`STAMP`, |
234 | , T , and B variable definitions in the local.conf file. | 217 | :term:`T`, and :term:`B` variable definitions in the ``local.conf`` file. |
235 | 218 | ||
236 | The ``TMPDIR`` variable establishes a directory that BitBake uses | 219 | The ``TMPDIR`` variable establishes a directory that BitBake uses |
237 | for build output and intermediate files other than the cached | 220 | for build output and intermediate files other than the cached |
@@ -251,21 +234,17 @@ Following is the complete "Hello World" example. | |||
251 | glossary. | 234 | glossary. |
252 | 235 | ||
253 | #. **Run BitBake:** After making sure that the ``conf/bitbake.conf`` file | 236 | #. **Run BitBake:** After making sure that the ``conf/bitbake.conf`` file |
254 | exists, you can run the ``bitbake`` command again: :: | 237 | exists, you can run the ``bitbake`` command again:: |
255 | 238 | ||
256 | $ bitbake | 239 | $ bitbake |
257 | ERROR: Traceback (most recent call last): | 240 | ERROR: Unable to parse /home/scott-lenovo/bitbake/lib/bb/parse/parse_py/BBHandler.py |
258 | File "/home/scott-lenovo/bitbake/lib/bb/cookerdata.py", line 163, in wrapped | 241 | Traceback (most recent call last): |
259 | return func(fn, *args) | 242 | 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>): |
260 | File "/home/scott-lenovo/bitbake/lib/bb/cookerdata.py", line 177, in _inherit | 243 | if not os.path.exists(file): |
261 | bb.parse.BBHandler.inherit(bbclass, "configuration INHERITs", 0, data) | 244 | > raise ParseError("Could not inherit file %s" % (file), fn, lineno) |
262 | File "/home/scott-lenovo/bitbake/lib/bb/parse/parse_py/BBHandler.py", line 92, in inherit | 245 | |
263 | include(fn, file, lineno, d, "inherit") | 246 | bb.parse.ParseError: ParseError in configuration INHERITs: Could not inherit file classes/base.bbclass |
264 | File "/home/scott-lenovo/bitbake/lib/bb/parse/parse_py/ConfHandler.py", line 100, in include | 247 | |
265 | raise ParseError("Could not %(error_out)s file %(fn)s" % vars(), oldfn, lineno) | ||
266 | ParseError: ParseError in configuration INHERITs: Could not inherit file classes/base.bbclass | ||
267 | |||
268 | ERROR: Unable to parse base: ParseError in configuration INHERITs: Could not inherit file classes/base.bbclass | ||
269 | 248 | ||
270 | In the sample output, | 249 | In the sample output, |
271 | BitBake could not find the ``classes/base.bbclass`` file. You need | 250 | BitBake could not find the ``classes/base.bbclass`` file. You need |
@@ -278,20 +257,23 @@ Following is the complete "Hello World" example. | |||
278 | in the ``classes`` directory of the project (i.e ``hello/classes`` | 257 | in the ``classes`` directory of the project (i.e ``hello/classes`` |
279 | in this example). | 258 | in this example). |
280 | 259 | ||
281 | Create the ``classes`` directory as follows: :: | 260 | Create the ``classes`` directory as follows:: |
282 | 261 | ||
283 | $ cd $HOME/hello | 262 | $ cd $HOME/hello |
284 | $ mkdir classes | 263 | $ mkdir classes |
285 | 264 | ||
286 | Move to the ``classes`` directory and then create the | 265 | Move to the ``classes`` directory and then create the |
287 | ``base.bbclass`` file by inserting this single line: addtask build | 266 | ``base.bbclass`` file by inserting this single line:: |
267 | |||
268 | addtask build | ||
269 | |||
288 | The minimal task that BitBake runs is the ``do_build`` task. This is | 270 | The minimal task that BitBake runs is the ``do_build`` task. This is |
289 | all the example needs in order to build the project. Of course, the | 271 | all the example needs in order to build the project. Of course, the |
290 | ``base.bbclass`` can have much more depending on which build | 272 | ``base.bbclass`` can have much more depending on which build |
291 | environments BitBake is supporting. | 273 | environments BitBake is supporting. |
292 | 274 | ||
293 | #. **Run BitBake:** After making sure that the ``classes/base.bbclass`` | 275 | #. **Run BitBake:** After making sure that the ``classes/base.bbclass`` |
294 | file exists, you can run the ``bitbake`` command again: :: | 276 | file exists, you can run the ``bitbake`` command again:: |
295 | 277 | ||
296 | $ bitbake | 278 | $ bitbake |
297 | Nothing to do. Use 'bitbake world' to build everything, or run 'bitbake --help' for usage information. | 279 | 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. | |||
314 | Minimally, you need a recipe file and a layer configuration file in | 296 | Minimally, you need a recipe file and a layer configuration file in |
315 | your layer. The configuration file needs to be in the ``conf`` | 297 | your layer. The configuration file needs to be in the ``conf`` |
316 | directory inside the layer. Use these commands to set up the layer | 298 | directory inside the layer. Use these commands to set up the layer |
317 | and the ``conf`` directory: :: | 299 | and the ``conf`` directory:: |
318 | 300 | ||
319 | $ cd $HOME | 301 | $ cd $HOME |
320 | $ mkdir mylayer | 302 | $ mkdir mylayer |
@@ -322,20 +304,29 @@ Following is the complete "Hello World" example. | |||
322 | $ mkdir conf | 304 | $ mkdir conf |
323 | 305 | ||
324 | Move to the ``conf`` directory and create a ``layer.conf`` file that has the | 306 | Move to the ``conf`` directory and create a ``layer.conf`` file that has the |
325 | following: :: | 307 | following:: |
326 | 308 | ||
327 | BBPATH .= ":${LAYERDIR}" | 309 | BBPATH .= ":${LAYERDIR}" |
328 | BBFILES += "${LAYERDIR}/\*.bb" | 310 | BBFILES += "${LAYERDIR}/*.bb" |
329 | BBFILE_COLLECTIONS += "mylayer" | 311 | BBFILE_COLLECTIONS += "mylayer" |
330 | `BBFILE_PATTERN_mylayer := "^${LAYERDIR_RE}/" | 312 | BBFILE_PATTERN_mylayer := "^${LAYERDIR_RE}/" |
313 | LAYERSERIES_CORENAMES = "hello_world_example" | ||
314 | LAYERSERIES_COMPAT_mylayer = "hello_world_example" | ||
331 | 315 | ||
332 | For information on these variables, click on :term:`BBFILES`, | 316 | For information on these variables, click on :term:`BBFILES`, |
333 | :term:`LAYERDIR`, :term:`BBFILE_COLLECTIONS` or :term:`BBFILE_PATTERN_mylayer <BBFILE_PATTERN>` | 317 | :term:`LAYERDIR`, :term:`BBFILE_COLLECTIONS`, :term:`BBFILE_PATTERN_mylayer <BBFILE_PATTERN>` |
334 | to go to the definitions in the glossary. | 318 | or :term:`LAYERSERIES_COMPAT` to go to the definitions in the glossary. |
319 | |||
320 | .. note:: | ||
321 | |||
322 | We are setting both ``LAYERSERIES_CORENAMES`` and :term:`LAYERSERIES_COMPAT` in this particular case, because we | ||
323 | are using bitbake without OpenEmbedded. | ||
324 | You should usually just use :term:`LAYERSERIES_COMPAT` to specify the OE-Core versions for which your layer | ||
325 | is compatible, and add the meta-openembedded layer to your project. | ||
335 | 326 | ||
336 | You need to create the recipe file next. Inside your layer at the | 327 | You need to create the recipe file next. Inside your layer at the |
337 | top-level, use an editor and create a recipe file named | 328 | top-level, use an editor and create a recipe file named |
338 | ``printhello.bb`` that has the following: :: | 329 | ``printhello.bb`` that has the following:: |
339 | 330 | ||
340 | DESCRIPTION = "Prints Hello World" | 331 | DESCRIPTION = "Prints Hello World" |
341 | PN = 'printhello' | 332 | PN = 'printhello' |
@@ -356,7 +347,7 @@ Following is the complete "Hello World" example. | |||
356 | follow the links to the glossary. | 347 | follow the links to the glossary. |
357 | 348 | ||
358 | #. **Run BitBake With a Target:** Now that a BitBake target exists, run | 349 | #. **Run BitBake With a Target:** Now that a BitBake target exists, run |
359 | the command and provide that target: :: | 350 | the command and provide that target:: |
360 | 351 | ||
361 | $ cd $HOME/hello | 352 | $ cd $HOME/hello |
362 | $ bitbake printhello | 353 | $ bitbake printhello |
@@ -376,7 +367,7 @@ Following is the complete "Hello World" example. | |||
376 | ``hello/conf`` for this example). | 367 | ``hello/conf`` for this example). |
377 | 368 | ||
378 | Set your working directory to the ``hello/conf`` directory and then | 369 | Set your working directory to the ``hello/conf`` directory and then |
379 | create the ``bblayers.conf`` file so that it contains the following: :: | 370 | create the ``bblayers.conf`` file so that it contains the following:: |
380 | 371 | ||
381 | BBLAYERS ?= " \ | 372 | BBLAYERS ?= " \ |
382 | /home/<you>/mylayer \ | 373 | /home/<you>/mylayer \ |
@@ -386,15 +377,17 @@ Following is the complete "Hello World" example. | |||
386 | 377 | ||
387 | #. **Run BitBake With a Target:** Now that you have supplied the | 378 | #. **Run BitBake With a Target:** Now that you have supplied the |
388 | ``bblayers.conf`` file, run the ``bitbake`` command and provide the | 379 | ``bblayers.conf`` file, run the ``bitbake`` command and provide the |
389 | target: :: | 380 | target:: |
390 | 381 | ||
391 | $ bitbake printhello | 382 | $ bitbake printhello |
383 | Loading cache: 100% | | ||
384 | Loaded 0 entries from dependency cache. | ||
392 | Parsing recipes: 100% |##################################################################################| | 385 | Parsing recipes: 100% |##################################################################################| |
393 | Time: 00:00:00 | ||
394 | Parsing of 1 .bb files complete (0 cached, 1 parsed). 1 targets, 0 skipped, 0 masked, 0 errors. | 386 | Parsing of 1 .bb files complete (0 cached, 1 parsed). 1 targets, 0 skipped, 0 masked, 0 errors. |
395 | NOTE: Resolving any missing task queue dependencies | 387 | NOTE: Resolving any missing task queue dependencies |
396 | NOTE: Preparing RunQueue | 388 | Initialising tasks: 100% |###############################################################################| |
397 | NOTE: Executing RunQueue Tasks | 389 | NOTE: No setscene tasks |
390 | NOTE: Executing Tasks | ||
398 | ******************** | 391 | ******************** |
399 | * * | 392 | * * |
400 | * Hello, World! * | 393 | * 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. | |||
27 | Conceptually, BitBake is similar to GNU Make in some regards but has | 27 | Conceptually, BitBake is similar to GNU Make in some regards but has |
28 | significant differences: | 28 | significant differences: |
29 | 29 | ||
30 | - BitBake executes tasks according to provided metadata that builds up | 30 | - BitBake executes tasks according to the provided metadata that builds up |
31 | the tasks. Metadata is stored in recipe (``.bb``) and related recipe | 31 | the tasks. Metadata is stored in recipe (``.bb``) and related recipe |
32 | "append" (``.bbappend``) files, configuration (``.conf``) and | 32 | "append" (``.bbappend``) files, configuration (``.conf``) and |
33 | underlying include (``.inc``) files, and in class (``.bbclass``) | 33 | underlying include (``.inc``) files, and in class (``.bbclass``) |
@@ -60,11 +60,10 @@ member Chris Larson split the project into two distinct pieces: | |||
60 | - OpenEmbedded, a metadata set utilized by BitBake | 60 | - OpenEmbedded, a metadata set utilized by BitBake |
61 | 61 | ||
62 | Today, BitBake is the primary basis of the | 62 | Today, BitBake is the primary basis of the |
63 | `OpenEmbedded <http://www.openembedded.org/>`__ project, which is being | 63 | `OpenEmbedded <https://www.openembedded.org/>`__ project, which is being |
64 | used to build and maintain Linux distributions such as the `Angstrom | 64 | used to build and maintain Linux distributions such as the `Poky |
65 | Distribution <http://www.angstrom-distribution.org/>`__, and which is | 65 | Reference Distribution <https://www.yoctoproject.org/software-item/poky/>`__, |
66 | also being used as the build tool for Linux projects such as the `Yocto | 66 | developed under the umbrella of the `Yocto Project <https://www.yoctoproject.org>`__. |
67 | Project <http://www.yoctoproject.org>`__. | ||
68 | 67 | ||
69 | Prior to BitBake, no other build tool adequately met the needs of an | 68 | Prior to BitBake, no other build tool adequately met the needs of an |
70 | aspiring embedded Linux distribution. All of the build systems used by | 69 | aspiring embedded Linux distribution. All of the build systems used by |
@@ -248,13 +247,13 @@ underlying, similarly-named recipe files. | |||
248 | 247 | ||
249 | When you name an append file, you can use the "``%``" wildcard character | 248 | When you name an append file, you can use the "``%``" wildcard character |
250 | to allow for matching recipe names. For example, suppose you have an | 249 | to allow for matching recipe names. For example, suppose you have an |
251 | append file named as follows: :: | 250 | append file named as follows:: |
252 | 251 | ||
253 | busybox_1.21.%.bbappend | 252 | busybox_1.21.%.bbappend |
254 | 253 | ||
255 | That append file | 254 | That append file |
256 | would match any ``busybox_1.21.``\ x\ ``.bb`` version of the recipe. So, | 255 | would match any ``busybox_1.21.``\ x\ ``.bb`` version of the recipe. So, |
257 | the append file would match the following recipe names: :: | 256 | the append file would match the following recipe names:: |
258 | 257 | ||
259 | busybox_1.21.1.bb | 258 | busybox_1.21.1.bb |
260 | busybox_1.21.2.bb | 259 | busybox_1.21.2.bb |
@@ -290,7 +289,7 @@ You can obtain BitBake several different ways: | |||
290 | are using. The metadata is generally backwards compatible but not | 289 | are using. The metadata is generally backwards compatible but not |
291 | forward compatible. | 290 | forward compatible. |
292 | 291 | ||
293 | Here is an example that clones the BitBake repository: :: | 292 | Here is an example that clones the BitBake repository:: |
294 | 293 | ||
295 | $ git clone git://git.openembedded.org/bitbake | 294 | $ git clone git://git.openembedded.org/bitbake |
296 | 295 | ||
@@ -298,7 +297,7 @@ You can obtain BitBake several different ways: | |||
298 | Git repository into a directory called ``bitbake``. Alternatively, | 297 | Git repository into a directory called ``bitbake``. Alternatively, |
299 | you can designate a directory after the ``git clone`` command if you | 298 | you can designate a directory after the ``git clone`` command if you |
300 | want to call the new directory something other than ``bitbake``. Here | 299 | want to call the new directory something other than ``bitbake``. Here |
301 | is an example that names the directory ``bbdev``: :: | 300 | is an example that names the directory ``bbdev``:: |
302 | 301 | ||
303 | $ git clone git://git.openembedded.org/bitbake bbdev | 302 | $ git clone git://git.openembedded.org/bitbake bbdev |
304 | 303 | ||
@@ -317,9 +316,9 @@ You can obtain BitBake several different ways: | |||
317 | method for getting BitBake. Cloning the repository makes it easier | 316 | method for getting BitBake. Cloning the repository makes it easier |
318 | to update as patches are added to the stable branches. | 317 | to update as patches are added to the stable branches. |
319 | 318 | ||
320 | The following example downloads a snapshot of BitBake version 1.17.0: :: | 319 | The following example downloads a snapshot of BitBake version 1.17.0:: |
321 | 320 | ||
322 | $ wget http://git.openembedded.org/bitbake/snapshot/bitbake-1.17.0.tar.gz | 321 | $ wget https://git.openembedded.org/bitbake/snapshot/bitbake-1.17.0.tar.gz |
323 | $ tar zxpvf bitbake-1.17.0.tar.gz | 322 | $ tar zxpvf bitbake-1.17.0.tar.gz |
324 | 323 | ||
325 | After extraction of the tarball using | 324 | After extraction of the tarball using |
@@ -347,7 +346,7 @@ execution examples. | |||
347 | Usage and syntax | 346 | Usage and syntax |
348 | ---------------- | 347 | ---------------- |
349 | 348 | ||
350 | Following is the usage and syntax for BitBake: :: | 349 | Following is the usage and syntax for BitBake:: |
351 | 350 | ||
352 | $ bitbake -h | 351 | $ bitbake -h |
353 | Usage: bitbake [options] [recipename/target recipe:do_task ...] | 352 | Usage: bitbake [options] [recipename/target recipe:do_task ...] |
@@ -417,8 +416,8 @@ Following is the usage and syntax for BitBake: :: | |||
417 | -l DEBUG_DOMAINS, --log-domains=DEBUG_DOMAINS | 416 | -l DEBUG_DOMAINS, --log-domains=DEBUG_DOMAINS |
418 | Show debug logging for the specified logging domains | 417 | Show debug logging for the specified logging domains |
419 | -P, --profile Profile the command and save reports. | 418 | -P, --profile Profile the command and save reports. |
420 | -u UI, --ui=UI The user interface to use (knotty, ncurses or taskexp | 419 | -u UI, --ui=UI The user interface to use (knotty, ncurses, taskexp or |
421 | - default knotty). | 420 | teamcity - default knotty). |
422 | --token=XMLRPCTOKEN Specify the connection token to be used when | 421 | --token=XMLRPCTOKEN Specify the connection token to be used when |
423 | connecting to a remote server. | 422 | connecting to a remote server. |
424 | --revisions-changed Set the exit code depending on whether upstream | 423 | --revisions-changed Set the exit code depending on whether upstream |
@@ -433,6 +432,9 @@ Following is the usage and syntax for BitBake: :: | |||
433 | Environment variable BB_SERVER_TIMEOUT. | 432 | Environment variable BB_SERVER_TIMEOUT. |
434 | --no-setscene Do not run any setscene tasks. sstate will be ignored | 433 | --no-setscene Do not run any setscene tasks. sstate will be ignored |
435 | and everything needed, built. | 434 | and everything needed, built. |
435 | --skip-setscene Skip setscene tasks if they would be executed. Tasks | ||
436 | previously restored from sstate will be kept, unlike | ||
437 | --no-setscene | ||
436 | --setscene-only Only run setscene tasks, don't run any real tasks. | 438 | --setscene-only Only run setscene tasks, don't run any real tasks. |
437 | --remote-server=REMOTE_SERVER | 439 | --remote-server=REMOTE_SERVER |
438 | Connect to the specified server. | 440 | Connect to the specified server. |
@@ -469,11 +471,11 @@ default task, which is "build". BitBake obeys inter-task dependencies | |||
469 | when doing so. | 471 | when doing so. |
470 | 472 | ||
471 | The following command runs the build task, which is the default task, on | 473 | The following command runs the build task, which is the default task, on |
472 | the ``foo_1.0.bb`` recipe file: :: | 474 | the ``foo_1.0.bb`` recipe file:: |
473 | 475 | ||
474 | $ bitbake -b foo_1.0.bb | 476 | $ bitbake -b foo_1.0.bb |
475 | 477 | ||
476 | The following command runs the clean task on the ``foo.bb`` recipe file: :: | 478 | The following command runs the clean task on the ``foo.bb`` recipe file:: |
477 | 479 | ||
478 | $ bitbake -b foo.bb -c clean | 480 | $ bitbake -b foo.bb -c clean |
479 | 481 | ||
@@ -497,13 +499,13 @@ functionality, or when there are multiple versions of a recipe. | |||
497 | The ``bitbake`` command, when not using "--buildfile" or "-b" only | 499 | The ``bitbake`` command, when not using "--buildfile" or "-b" only |
498 | accepts a "PROVIDES". You cannot provide anything else. By default, a | 500 | accepts a "PROVIDES". You cannot provide anything else. By default, a |
499 | recipe file generally "PROVIDES" its "packagename" as shown in the | 501 | recipe file generally "PROVIDES" its "packagename" as shown in the |
500 | following example: :: | 502 | following example:: |
501 | 503 | ||
502 | $ bitbake foo | 504 | $ bitbake foo |
503 | 505 | ||
504 | This next example "PROVIDES" the | 506 | This next example "PROVIDES" the |
505 | package name and also uses the "-c" option to tell BitBake to just | 507 | package name and also uses the "-c" option to tell BitBake to just |
506 | execute the ``do_clean`` task: :: | 508 | execute the ``do_clean`` task:: |
507 | 509 | ||
508 | $ bitbake -c clean foo | 510 | $ bitbake -c clean foo |
509 | 511 | ||
@@ -514,7 +516,7 @@ The BitBake command line supports specifying different tasks for | |||
514 | individual targets when you specify multiple targets. For example, | 516 | individual targets when you specify multiple targets. For example, |
515 | suppose you had two targets (or recipes) ``myfirstrecipe`` and | 517 | suppose you had two targets (or recipes) ``myfirstrecipe`` and |
516 | ``mysecondrecipe`` and you needed BitBake to run ``taskA`` for the first | 518 | ``mysecondrecipe`` and you needed BitBake to run ``taskA`` for the first |
517 | recipe and ``taskB`` for the second recipe: :: | 519 | recipe and ``taskB`` for the second recipe:: |
518 | 520 | ||
519 | $ bitbake myfirstrecipe:do_taskA mysecondrecipe:do_taskB | 521 | $ bitbake myfirstrecipe:do_taskA mysecondrecipe:do_taskB |
520 | 522 | ||
@@ -534,13 +536,13 @@ current working directory: | |||
534 | - ``pn-buildlist``: Shows a simple list of targets that are to be | 536 | - ``pn-buildlist``: Shows a simple list of targets that are to be |
535 | built. | 537 | built. |
536 | 538 | ||
537 | To stop depending on common depends, use the "-I" depend option and | 539 | To stop depending on common depends, use the ``-I`` depend option and |
538 | BitBake omits them from the graph. Leaving this information out can | 540 | BitBake omits them from the graph. Leaving this information out can |
539 | produce more readable graphs. This way, you can remove from the graph | 541 | produce more readable graphs. This way, you can remove from the graph |
540 | ``DEPENDS`` from inherited classes such as ``base.bbclass``. | 542 | :term:`DEPENDS` from inherited classes such as ``base.bbclass``. |
541 | 543 | ||
542 | Here are two examples that create dependency graphs. The second example | 544 | Here are two examples that create dependency graphs. The second example |
543 | omits depends common in OpenEmbedded from the graph: :: | 545 | omits depends common in OpenEmbedded from the graph:: |
544 | 546 | ||
545 | $ bitbake -g foo | 547 | $ bitbake -g foo |
546 | 548 | ||
@@ -564,7 +566,7 @@ for two separate targets: | |||
564 | .. image:: figures/bb_multiconfig_files.png | 566 | .. image:: figures/bb_multiconfig_files.png |
565 | :align: center | 567 | :align: center |
566 | 568 | ||
567 | The reason for this required file hierarchy is because the ``BBPATH`` | 569 | The reason for this required file hierarchy is because the :term:`BBPATH` |
568 | variable is not constructed until the layers are parsed. Consequently, | 570 | variable is not constructed until the layers are parsed. Consequently, |
569 | using the configuration file as a pre-configuration file is not possible | 571 | using the configuration file as a pre-configuration file is not possible |
570 | unless it is located in the current working directory. | 572 | unless it is located in the current working directory. |
@@ -582,17 +584,17 @@ accomplished by setting the | |||
582 | configuration files for ``target1`` and ``target2`` defined in the build | 584 | configuration files for ``target1`` and ``target2`` defined in the build |
583 | directory. The following statement in the ``local.conf`` file both | 585 | directory. The following statement in the ``local.conf`` file both |
584 | enables BitBake to perform multiple configuration builds and specifies | 586 | enables BitBake to perform multiple configuration builds and specifies |
585 | the two extra multiconfigs: :: | 587 | the two extra multiconfigs:: |
586 | 588 | ||
587 | BBMULTICONFIG = "target1 target2" | 589 | BBMULTICONFIG = "target1 target2" |
588 | 590 | ||
589 | Once the target configuration files are in place and BitBake has been | 591 | Once the target configuration files are in place and BitBake has been |
590 | enabled to perform multiple configuration builds, use the following | 592 | enabled to perform multiple configuration builds, use the following |
591 | command form to start the builds: :: | 593 | command form to start the builds:: |
592 | 594 | ||
593 | $ bitbake [mc:multiconfigname:]target [[[mc:multiconfigname:]target] ... ] | 595 | $ bitbake [mc:multiconfigname:]target [[[mc:multiconfigname:]target] ... ] |
594 | 596 | ||
595 | Here is an example for two extra multiconfigs: ``target1`` and ``target2``: :: | 597 | Here is an example for two extra multiconfigs: ``target1`` and ``target2``:: |
596 | 598 | ||
597 | $ bitbake mc::target mc:target1:target mc:target2:target | 599 | $ bitbake mc::target mc:target1:target mc:target2:target |
598 | 600 | ||
@@ -613,12 +615,12 @@ multiconfig. | |||
613 | 615 | ||
614 | To enable dependencies in a multiple configuration build, you must | 616 | To enable dependencies in a multiple configuration build, you must |
615 | declare the dependencies in the recipe using the following statement | 617 | declare the dependencies in the recipe using the following statement |
616 | form: :: | 618 | form:: |
617 | 619 | ||
618 | task_or_package[mcdepends] = "mc:from_multiconfig:to_multiconfig:recipe_name:task_on_which_to_depend" | 620 | task_or_package[mcdepends] = "mc:from_multiconfig:to_multiconfig:recipe_name:task_on_which_to_depend" |
619 | 621 | ||
620 | To better show how to use this statement, consider an example with two | 622 | To better show how to use this statement, consider an example with two |
621 | multiconfigs: ``target1`` and ``target2``: :: | 623 | multiconfigs: ``target1`` and ``target2``:: |
622 | 624 | ||
623 | image_task[mcdepends] = "mc:target1:target2:image2:rootfs_task" | 625 | image_task[mcdepends] = "mc:target1:target2:image2:rootfs_task" |
624 | 626 | ||
@@ -629,7 +631,7 @@ completion of the rootfs_task used to build out image2, which is | |||
629 | associated with the "target2" multiconfig. | 631 | associated with the "target2" multiconfig. |
630 | 632 | ||
631 | Once you set up this dependency, you can build the "target1" multiconfig | 633 | Once you set up this dependency, you can build the "target1" multiconfig |
632 | using a BitBake command as follows: :: | 634 | using a BitBake command as follows:: |
633 | 635 | ||
634 | $ bitbake mc:target1:image1 | 636 | $ bitbake mc:target1:image1 |
635 | 637 | ||
@@ -639,7 +641,7 @@ the ``rootfs_task`` for the "target2" multiconfig build. | |||
639 | 641 | ||
640 | Having a recipe depend on the root filesystem of another build might not | 642 | Having a recipe depend on the root filesystem of another build might not |
641 | seem that useful. Consider this change to the statement in the image1 | 643 | seem that useful. Consider this change to the statement in the image1 |
642 | recipe: :: | 644 | recipe:: |
643 | 645 | ||
644 | image_task[mcdepends] = "mc:target1:target2:image2:image_task" | 646 | image_task[mcdepends] = "mc:target1:target2:image2:image_task" |
645 | 647 | ||
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. :: | |||
26 | VARIABLE = "value" | 26 | VARIABLE = "value" |
27 | 27 | ||
28 | As expected, if you include leading or | 28 | As expected, if you include leading or |
29 | trailing spaces as part of an assignment, the spaces are retained: :: | 29 | trailing spaces as part of an assignment, the spaces are retained:: |
30 | 30 | ||
31 | VARIABLE = " value" | 31 | VARIABLE = " value" |
32 | VARIABLE = "value " | 32 | VARIABLE = "value " |
@@ -40,7 +40,7 @@ blank space (i.e. these are not the same values). :: | |||
40 | 40 | ||
41 | You can use single quotes instead of double quotes when setting a | 41 | You can use single quotes instead of double quotes when setting a |
42 | variable's value. Doing so allows you to use values that contain the | 42 | variable's value. Doing so allows you to use values that contain the |
43 | double quote character: :: | 43 | double quote character:: |
44 | 44 | ||
45 | VARIABLE = 'I have a " in my value' | 45 | VARIABLE = 'I have a " in my value' |
46 | 46 | ||
@@ -77,7 +77,7 @@ occurs, you can use BitBake to check the actual value of the suspect | |||
77 | variable. You can make these checks for both configuration and recipe | 77 | variable. You can make these checks for both configuration and recipe |
78 | level changes: | 78 | level changes: |
79 | 79 | ||
80 | - For configuration changes, use the following: :: | 80 | - For configuration changes, use the following:: |
81 | 81 | ||
82 | $ bitbake -e | 82 | $ bitbake -e |
83 | 83 | ||
@@ -91,9 +91,10 @@ level changes: | |||
91 | Variables that are exported to the environment are preceded by the | 91 | Variables that are exported to the environment are preceded by the |
92 | string "export" in the command's output. | 92 | string "export" in the command's output. |
93 | 93 | ||
94 | - For recipe changes, use the following: :: | 94 | - To find changes to a given variable in a specific recipe, use the |
95 | following:: | ||
95 | 96 | ||
96 | $ bitbake recipe -e \| grep VARIABLE=" | 97 | $ bitbake recipename -e | grep VARIABLENAME=\" |
97 | 98 | ||
98 | This command checks to see if the variable actually makes | 99 | This command checks to see if the variable actually makes |
99 | it into a specific recipe. | 100 | it into a specific recipe. |
@@ -103,20 +104,20 @@ Line Joining | |||
103 | 104 | ||
104 | Outside of :ref:`functions <bitbake-user-manual/bitbake-user-manual-metadata:functions>`, | 105 | Outside of :ref:`functions <bitbake-user-manual/bitbake-user-manual-metadata:functions>`, |
105 | BitBake joins any line ending in | 106 | BitBake joins any line ending in |
106 | a backslash character ("\") with the following line before parsing | 107 | a backslash character ("\\") with the following line before parsing |
107 | statements. The most common use for the "\" character is to split | 108 | statements. The most common use for the "\\" character is to split |
108 | variable assignments over multiple lines, as in the following example: :: | 109 | variable assignments over multiple lines, as in the following example:: |
109 | 110 | ||
110 | FOO = "bar \ | 111 | FOO = "bar \ |
111 | baz \ | 112 | baz \ |
112 | qaz" | 113 | qaz" |
113 | 114 | ||
114 | Both the "\" character and the newline | 115 | Both the "\\" character and the newline |
115 | character that follow it are removed when joining lines. Thus, no | 116 | character that follow it are removed when joining lines. Thus, no |
116 | newline characters end up in the value of ``FOO``. | 117 | newline characters end up in the value of ``FOO``. |
117 | 118 | ||
118 | Consider this additional example where the two assignments both assign | 119 | Consider this additional example where the two assignments both assign |
119 | "barbaz" to ``FOO``: :: | 120 | "barbaz" to ``FOO``:: |
120 | 121 | ||
121 | FOO = "barbaz" | 122 | FOO = "barbaz" |
122 | FOO = "bar\ | 123 | FOO = "bar\ |
@@ -124,7 +125,7 @@ Consider this additional example where the two assignments both assign | |||
124 | 125 | ||
125 | .. note:: | 126 | .. note:: |
126 | 127 | ||
127 | BitBake does not interpret escape sequences like "\n" in variable | 128 | BitBake does not interpret escape sequences like "\\n" in variable |
128 | values. For these to have an effect, the value must be passed to some | 129 | values. For these to have an effect, the value must be passed to some |
129 | utility that interprets escape sequences, such as | 130 | utility that interprets escape sequences, such as |
130 | ``printf`` or ``echo -n``. | 131 | ``printf`` or ``echo -n``. |
@@ -149,7 +150,7 @@ The "=" operator does not immediately expand variable references in the | |||
149 | right-hand side. Instead, expansion is deferred until the variable | 150 | right-hand side. Instead, expansion is deferred until the variable |
150 | assigned to is actually used. The result depends on the current values | 151 | assigned to is actually used. The result depends on the current values |
151 | of the referenced variables. The following example should clarify this | 152 | of the referenced variables. The following example should clarify this |
152 | behavior: :: | 153 | behavior:: |
153 | 154 | ||
154 | A = "${B} baz" | 155 | A = "${B} baz" |
155 | B = "${C} bar" | 156 | B = "${C} bar" |
@@ -158,7 +159,7 @@ behavior: :: | |||
158 | C = "qux" | 159 | C = "qux" |
159 | *At this point, ${A} equals "qux bar baz"* | 160 | *At this point, ${A} equals "qux bar baz"* |
160 | B = "norf" | 161 | B = "norf" |
161 | *At this point, ${A} equals "norf baz"\* | 162 | *At this point, ${A} equals "norf baz"* |
162 | 163 | ||
163 | Contrast this behavior with the | 164 | Contrast this behavior with the |
164 | :ref:`bitbake-user-manual/bitbake-user-manual-metadata:immediate variable | 165 | :ref:`bitbake-user-manual/bitbake-user-manual-metadata:immediate variable |
@@ -177,7 +178,7 @@ Setting a default value (?=) | |||
177 | You can use the "?=" operator to achieve a "softer" assignment for a | 178 | You can use the "?=" operator to achieve a "softer" assignment for a |
178 | variable. This type of assignment allows you to define a variable if it | 179 | variable. This type of assignment allows you to define a variable if it |
179 | is undefined when the statement is parsed, but to leave the value alone | 180 | is undefined when the statement is parsed, but to leave the value alone |
180 | if the variable has a value. Here is an example: :: | 181 | if the variable has a value. Here is an example:: |
181 | 182 | ||
182 | A ?= "aval" | 183 | A ?= "aval" |
183 | 184 | ||
@@ -194,28 +195,51 @@ value. However, if ``A`` is not set, the variable is set to "aval". | |||
194 | Setting a weak default value (??=) | 195 | Setting a weak default value (??=) |
195 | ---------------------------------- | 196 | ---------------------------------- |
196 | 197 | ||
197 | It is possible to use a "weaker" assignment than in the previous section | 198 | The weak default value of a variable is the value which that variable |
198 | by using the "??=" operator. This assignment behaves identical to "?=" | 199 | will expand to if no value has been assigned to it via any of the other |
199 | except that the assignment is made at the end of the parsing process | 200 | assignment operators. The "??=" operator takes effect immediately, replacing |
200 | rather than immediately. Consequently, when multiple "??=" assignments | 201 | any previously defined weak default value. Here is an example:: |
201 | exist, the last one is used. Also, any "=" or "?=" assignment will | ||
202 | override the value set with "??=". Here is an example: :: | ||
203 | 202 | ||
204 | A ??= "somevalue" | 203 | W ??= "x" |
205 | A ??= "someothervalue" | 204 | A := "${W}" # Immediate variable expansion |
205 | W ??= "y" | ||
206 | B := "${W}" # Immediate variable expansion | ||
207 | W ??= "z" | ||
208 | C = "${W}" | ||
209 | W ?= "i" | ||
206 | 210 | ||
207 | If ``A`` is set before the above statements are | 211 | After parsing we will have:: |
208 | parsed, the variable retains its value. If ``A`` is not set, the | ||
209 | variable is set to "someothervalue". | ||
210 | 212 | ||
211 | Again, this assignment is a "lazy" or "weak" assignment because it does | 213 | A = "x" |
212 | not occur until the end of the parsing process. | 214 | B = "y" |
215 | C = "i" | ||
216 | W = "i" | ||
217 | |||
218 | Appending and prepending non-override style will not substitute the weak | ||
219 | default value, which means that after parsing:: | ||
220 | |||
221 | W ??= "x" | ||
222 | W += "y" | ||
223 | |||
224 | we will have:: | ||
225 | |||
226 | W = " y" | ||
227 | |||
228 | On the other hand, override-style appends/prepends/removes are applied after | ||
229 | any active weak default value has been substituted:: | ||
230 | |||
231 | W ??= "x" | ||
232 | W:append = "y" | ||
233 | |||
234 | After parsing we will have:: | ||
235 | |||
236 | W = "xy" | ||
213 | 237 | ||
214 | Immediate variable expansion (:=) | 238 | Immediate variable expansion (:=) |
215 | --------------------------------- | 239 | --------------------------------- |
216 | 240 | ||
217 | The ":=" operator results in a variable's contents being expanded | 241 | The ":=" operator results in a variable's contents being expanded |
218 | immediately, rather than when the variable is actually used: :: | 242 | immediately, rather than when the variable is actually used:: |
219 | 243 | ||
220 | T = "123" | 244 | T = "123" |
221 | A := "test ${T}" | 245 | A := "test ${T}" |
@@ -225,7 +249,7 @@ immediately, rather than when the variable is actually used: :: | |||
225 | C := "${C}append" | 249 | C := "${C}append" |
226 | 250 | ||
227 | In this example, ``A`` contains "test 123", even though the final value | 251 | In this example, ``A`` contains "test 123", even though the final value |
228 | of ``T`` is "456". The variable ``B`` will end up containing "456 | 252 | of :term:`T` is "456". The variable :term:`B` will end up containing "456 |
229 | cvalappend". This is because references to undefined variables are | 253 | cvalappend". This is because references to undefined variables are |
230 | preserved as is during (immediate)expansion. This is in contrast to GNU | 254 | preserved as is during (immediate)expansion. This is in contrast to GNU |
231 | Make, where undefined variables expand to nothing. The variable ``C`` | 255 | Make, where undefined variables expand to nothing. The variable ``C`` |
@@ -241,14 +265,14 @@ the "+=" and "=+" operators. These operators insert a space between the | |||
241 | current value and prepended or appended value. | 265 | current value and prepended or appended value. |
242 | 266 | ||
243 | These operators take immediate effect during parsing. Here are some | 267 | These operators take immediate effect during parsing. Here are some |
244 | examples: :: | 268 | examples:: |
245 | 269 | ||
246 | B = "bval" | 270 | B = "bval" |
247 | B += "additionaldata" | 271 | B += "additionaldata" |
248 | C = "cval" | 272 | C = "cval" |
249 | C =+ "test" | 273 | C =+ "test" |
250 | 274 | ||
251 | The variable ``B`` contains "bval additionaldata" and ``C`` contains "test | 275 | The variable :term:`B` contains "bval additionaldata" and ``C`` contains "test |
252 | cval". | 276 | cval". |
253 | 277 | ||
254 | .. _appending-and-prepending-without-spaces: | 278 | .. _appending-and-prepending-without-spaces: |
@@ -260,14 +284,14 @@ If you want to append or prepend values without an inserted space, use | |||
260 | the ".=" and "=." operators. | 284 | the ".=" and "=." operators. |
261 | 285 | ||
262 | These operators take immediate effect during parsing. Here are some | 286 | These operators take immediate effect during parsing. Here are some |
263 | examples: :: | 287 | examples:: |
264 | 288 | ||
265 | B = "bval" | 289 | B = "bval" |
266 | B .= "additionaldata" | 290 | B .= "additionaldata" |
267 | C = "cval" | 291 | C = "cval" |
268 | C =. "test" | 292 | C =. "test" |
269 | 293 | ||
270 | The variable ``B`` contains "bvaladditionaldata" and ``C`` contains | 294 | The variable :term:`B` contains "bvaladditionaldata" and ``C`` contains |
271 | "testcval". | 295 | "testcval". |
272 | 296 | ||
273 | Appending and Prepending (Override Style Syntax) | 297 | Appending and Prepending (Override Style Syntax) |
@@ -278,16 +302,16 @@ style syntax. When you use this syntax, no spaces are inserted. | |||
278 | 302 | ||
279 | These operators differ from the ":=", ".=", "=.", "+=", and "=+" | 303 | These operators differ from the ":=", ".=", "=.", "+=", and "=+" |
280 | operators in that their effects are applied at variable expansion time | 304 | operators in that their effects are applied at variable expansion time |
281 | rather than being immediately applied. Here are some examples: :: | 305 | rather than being immediately applied. Here are some examples:: |
282 | 306 | ||
283 | B = "bval" | 307 | B = "bval" |
284 | B_append = " additional data" | 308 | B:append = " additional data" |
285 | C = "cval" | 309 | C = "cval" |
286 | C_prepend = "additional data " | 310 | C:prepend = "additional data " |
287 | D = "dval" | 311 | D = "dval" |
288 | D_append = "additional data" | 312 | D:append = "additional data" |
289 | 313 | ||
290 | The variable ``B`` | 314 | The variable :term:`B` |
291 | becomes "bval additional data" and ``C`` becomes "additional data cval". | 315 | becomes "bval additional data" and ``C`` becomes "additional data cval". |
292 | The variable ``D`` becomes "dvaladditional data". | 316 | The variable ``D`` becomes "dvaladditional data". |
293 | 317 | ||
@@ -295,6 +319,10 @@ The variable ``D`` becomes "dvaladditional data". | |||
295 | 319 | ||
296 | You must control all spacing when you use the override syntax. | 320 | You must control all spacing when you use the override syntax. |
297 | 321 | ||
322 | .. note:: | ||
323 | |||
324 | The overrides are applied in this order, ":append", ":prepend", ":remove". | ||
325 | |||
298 | It is also possible to append and prepend to shell functions and | 326 | It is also possible to append and prepend to shell functions and |
299 | 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`" | 327 | 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`" |
300 | sections for examples. | 328 | sections for examples. |
@@ -306,16 +334,17 @@ Removal (Override Style Syntax) | |||
306 | 334 | ||
307 | You can remove values from lists using the removal override style | 335 | You can remove values from lists using the removal override style |
308 | syntax. Specifying a value for removal causes all occurrences of that | 336 | syntax. Specifying a value for removal causes all occurrences of that |
309 | value to be removed from the variable. | 337 | value to be removed from the variable. Unlike ":append" and ":prepend", |
338 | there is no need to add a leading or trailing space to the value. | ||
310 | 339 | ||
311 | When you use this syntax, BitBake expects one or more strings. | 340 | When you use this syntax, BitBake expects one or more strings. |
312 | Surrounding spaces and spacing are preserved. Here is an example: :: | 341 | Surrounding spaces and spacing are preserved. Here is an example:: |
313 | 342 | ||
314 | FOO = "123 456 789 123456 123 456 123 456" | 343 | FOO = "123 456 789 123456 123 456 123 456" |
315 | FOO_remove = "123" | 344 | FOO:remove = "123" |
316 | FOO_remove = "456" | 345 | FOO:remove = "456" |
317 | FOO2 = " abc def ghi abcdef abc def abc def def" | 346 | FOO2 = " abc def ghi abcdef abc def abc def def" |
318 | FOO2_remove = "\ | 347 | FOO2:remove = "\ |
319 | def \ | 348 | def \ |
320 | abc \ | 349 | abc \ |
321 | ghi \ | 350 | ghi \ |
@@ -324,40 +353,62 @@ Surrounding spaces and spacing are preserved. Here is an example: :: | |||
324 | The variable ``FOO`` becomes | 353 | The variable ``FOO`` becomes |
325 | " 789 123456 " and ``FOO2`` becomes " abcdef ". | 354 | " 789 123456 " and ``FOO2`` becomes " abcdef ". |
326 | 355 | ||
327 | Like "_append" and "_prepend", "_remove" is applied at variable | 356 | Like ":append" and ":prepend", ":remove" is applied at variable |
328 | expansion time. | 357 | expansion time. |
329 | 358 | ||
359 | .. note:: | ||
360 | |||
361 | The overrides are applied in this order, ":append", ":prepend", ":remove". | ||
362 | This implies it is not possible to re-append previously removed strings. | ||
363 | However, one can undo a ":remove" by using an intermediate variable whose | ||
364 | content is passed to the ":remove" so that modifying the intermediate | ||
365 | variable equals to keeping the string in:: | ||
366 | |||
367 | FOOREMOVE = "123 456 789" | ||
368 | FOO:remove = "${FOOREMOVE}" | ||
369 | ... | ||
370 | FOOREMOVE = "123 789" | ||
371 | |||
372 | This expands to ``FOO:remove = "123 789"``. | ||
373 | |||
374 | .. note:: | ||
375 | |||
376 | Override application order may not match variable parse history, i.e. | ||
377 | the output of ``bitbake -e`` may contain ":remove" before ":append", | ||
378 | but the result will be removed string, because ":remove" is handled | ||
379 | last. | ||
380 | |||
330 | Override Style Operation Advantages | 381 | Override Style Operation Advantages |
331 | ----------------------------------- | 382 | ----------------------------------- |
332 | 383 | ||
333 | An advantage of the override style operations "_append", "_prepend", and | 384 | An advantage of the override style operations ":append", ":prepend", and |
334 | "_remove" as compared to the "+=" and "=+" operators is that the | 385 | ":remove" as compared to the "+=" and "=+" operators is that the |
335 | override style operators provide guaranteed operations. For example, | 386 | override style operators provide guaranteed operations. For example, |
336 | consider a class ``foo.bbclass`` that needs to add the value "val" to | 387 | consider a class ``foo.bbclass`` that needs to add the value "val" to |
337 | the variable ``FOO``, and a recipe that uses ``foo.bbclass`` as follows: :: | 388 | the variable ``FOO``, and a recipe that uses ``foo.bbclass`` as follows:: |
338 | 389 | ||
339 | inherit foo | 390 | inherit foo |
340 | FOO = "initial" | 391 | FOO = "initial" |
341 | 392 | ||
342 | If ``foo.bbclass`` uses the "+=" operator, | 393 | If ``foo.bbclass`` uses the "+=" operator, |
343 | as follows, then the final value of ``FOO`` will be "initial", which is | 394 | as follows, then the final value of ``FOO`` will be "initial", which is |
344 | not what is desired: :: | 395 | not what is desired:: |
345 | 396 | ||
346 | FOO += "val" | 397 | FOO += "val" |
347 | 398 | ||
348 | If, on the other hand, ``foo.bbclass`` | 399 | If, on the other hand, ``foo.bbclass`` |
349 | uses the "_append" operator, then the final value of ``FOO`` will be | 400 | uses the ":append" operator, then the final value of ``FOO`` will be |
350 | "initial val", as intended: :: | 401 | "initial val", as intended:: |
351 | 402 | ||
352 | FOO_append = " val" | 403 | FOO:append = " val" |
353 | 404 | ||
354 | .. note:: | 405 | .. note:: |
355 | 406 | ||
356 | It is never necessary to use "+=" together with "_append". The following | 407 | It is never necessary to use "+=" together with ":append". The following |
357 | sequence of assignments appends "barbaz" to FOO: :: | 408 | sequence of assignments appends "barbaz" to FOO:: |
358 | 409 | ||
359 | FOO_append = "bar" | 410 | FOO:append = "bar" |
360 | FOO_append = "baz" | 411 | FOO:append = "baz" |
361 | 412 | ||
362 | 413 | ||
363 | The only effect of changing the second assignment in the previous | 414 | 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 | |||
378 | 429 | ||
379 | You can define, append, and prepend values to variable flags. All the | 430 | You can define, append, and prepend values to variable flags. All the |
380 | standard syntax operations previously mentioned work for variable flags | 431 | standard syntax operations previously mentioned work for variable flags |
381 | except for override style syntax (i.e. "_prepend", "_append", and | 432 | except for override style syntax (i.e. ":prepend", ":append", and |
382 | "_remove"). | 433 | ":remove"). |
383 | 434 | ||
384 | Here are some examples showing how to set variable flags: :: | 435 | Here are some examples showing how to set variable flags:: |
385 | 436 | ||
386 | FOO[a] = "abc" | 437 | FOO[a] = "abc" |
387 | FOO[b] = "123" | 438 | FOO[b] = "123" |
@@ -393,15 +444,21 @@ respectively. The ``[a]`` flag becomes "abc 456". | |||
393 | 444 | ||
394 | No need exists to pre-define variable flags. You can simply start using | 445 | No need exists to pre-define variable flags. You can simply start using |
395 | them. One extremely common application is to attach some brief | 446 | them. One extremely common application is to attach some brief |
396 | documentation to a BitBake variable as follows: :: | 447 | documentation to a BitBake variable as follows:: |
397 | 448 | ||
398 | CACHE[doc] = "The directory holding the cache of the metadata." | 449 | CACHE[doc] = "The directory holding the cache of the metadata." |
399 | 450 | ||
451 | .. note:: | ||
452 | |||
453 | Variable flag names starting with an underscore (``_``) character | ||
454 | are allowed but are ignored by ``d.getVarFlags("VAR")`` | ||
455 | in Python code. Such flag names are used internally by BitBake. | ||
456 | |||
400 | Inline Python Variable Expansion | 457 | Inline Python Variable Expansion |
401 | -------------------------------- | 458 | -------------------------------- |
402 | 459 | ||
403 | You can use inline Python variable expansion to set variables. Here is | 460 | You can use inline Python variable expansion to set variables. Here is |
404 | an example: :: | 461 | an example:: |
405 | 462 | ||
406 | DATE = "${@time.strftime('%Y%m%d',time.gmtime())}" | 463 | DATE = "${@time.strftime('%Y%m%d',time.gmtime())}" |
407 | 464 | ||
@@ -410,21 +467,21 @@ This example results in the ``DATE`` variable being set to the current date. | |||
410 | Probably the most common use of this feature is to extract the value of | 467 | Probably the most common use of this feature is to extract the value of |
411 | variables from BitBake's internal data dictionary, ``d``. The following | 468 | variables from BitBake's internal data dictionary, ``d``. The following |
412 | lines select the values of a package name and its version number, | 469 | lines select the values of a package name and its version number, |
413 | respectively: :: | 470 | respectively:: |
414 | 471 | ||
415 | PN = "${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE', False),d)[0] or 'defaultpkgname'}" | 472 | PN = "${@bb.parse.vars_from_file(d.getVar('FILE', False),d)[0] or 'defaultpkgname'}" |
416 | PV = "${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE', False),d)[1] or '1.0'}" | 473 | PV = "${@bb.parse.vars_from_file(d.getVar('FILE', False),d)[1] or '1.0'}" |
417 | 474 | ||
418 | .. note:: | 475 | .. note:: |
419 | 476 | ||
420 | Inline Python expressions work just like variable expansions insofar as the | 477 | Inline Python expressions work just like variable expansions insofar as the |
421 | "=" and ":=" operators are concerned. Given the following assignment, foo() | 478 | "=" and ":=" operators are concerned. Given the following assignment, foo() |
422 | is called each time FOO is expanded: :: | 479 | is called each time FOO is expanded:: |
423 | 480 | ||
424 | FOO = "${@foo()}" | 481 | FOO = "${@foo()}" |
425 | 482 | ||
426 | Contrast this with the following immediate assignment, where foo() is only | 483 | Contrast this with the following immediate assignment, where foo() is only |
427 | called once, while the assignment is parsed: :: | 484 | called once, while the assignment is parsed:: |
428 | 485 | ||
429 | FOO := "${@foo()}" | 486 | FOO := "${@foo()}" |
430 | 487 | ||
@@ -437,7 +494,7 @@ Unsetting variables | |||
437 | 494 | ||
438 | It is possible to completely remove a variable or a variable flag from | 495 | It is possible to completely remove a variable or a variable flag from |
439 | BitBake's internal data dictionary by using the "unset" keyword. Here is | 496 | BitBake's internal data dictionary by using the "unset" keyword. Here is |
440 | an example: :: | 497 | an example:: |
441 | 498 | ||
442 | unset DATE | 499 | unset DATE |
443 | unset do_fetch[noexec] | 500 | unset do_fetch[noexec] |
@@ -452,7 +509,7 @@ When specifying pathnames for use with BitBake, do not use the tilde | |||
452 | cause BitBake to not recognize the path since BitBake does not expand | 509 | cause BitBake to not recognize the path since BitBake does not expand |
453 | this character in the same way a shell would. | 510 | this character in the same way a shell would. |
454 | 511 | ||
455 | Instead, provide a fuller path as the following example illustrates: :: | 512 | Instead, provide a fuller path as the following example illustrates:: |
456 | 513 | ||
457 | BBLAYERS ?= " \ | 514 | BBLAYERS ?= " \ |
458 | /home/scott-lenovo/LayerA \ | 515 | /home/scott-lenovo/LayerA \ |
@@ -463,7 +520,7 @@ Exporting Variables to the Environment | |||
463 | 520 | ||
464 | You can export variables to the environment of running tasks by using | 521 | You can export variables to the environment of running tasks by using |
465 | the ``export`` keyword. For example, in the following example, the | 522 | the ``export`` keyword. For example, in the following example, the |
466 | ``do_foo`` task prints "value from the environment" when run: :: | 523 | ``do_foo`` task prints "value from the environment" when run:: |
467 | 524 | ||
468 | export ENV_VARIABLE | 525 | export ENV_VARIABLE |
469 | ENV_VARIABLE = "value from the environment" | 526 | ENV_VARIABLE = "value from the environment" |
@@ -481,7 +538,7 @@ It does not matter whether ``export ENV_VARIABLE`` appears before or | |||
481 | after assignments to ``ENV_VARIABLE``. | 538 | after assignments to ``ENV_VARIABLE``. |
482 | 539 | ||
483 | It is also possible to combine ``export`` with setting a value for the | 540 | It is also possible to combine ``export`` with setting a value for the |
484 | variable. Here is an example: :: | 541 | variable. Here is an example:: |
485 | 542 | ||
486 | export ENV_VARIABLE = "variable-value" | 543 | export ENV_VARIABLE = "variable-value" |
487 | 544 | ||
@@ -496,78 +553,78 @@ Conditional Syntax (Overrides) | |||
496 | 553 | ||
497 | BitBake uses :term:`OVERRIDES` to control what | 554 | BitBake uses :term:`OVERRIDES` to control what |
498 | variables are overridden after BitBake parses recipes and configuration | 555 | variables are overridden after BitBake parses recipes and configuration |
499 | files. This section describes how you can use ``OVERRIDES`` as | 556 | files. This section describes how you can use :term:`OVERRIDES` as |
500 | conditional metadata, talks about key expansion in relationship to | 557 | conditional metadata, talks about key expansion in relationship to |
501 | ``OVERRIDES``, and provides some examples to help with understanding. | 558 | :term:`OVERRIDES`, and provides some examples to help with understanding. |
502 | 559 | ||
503 | Conditional Metadata | 560 | Conditional Metadata |
504 | -------------------- | 561 | -------------------- |
505 | 562 | ||
506 | You can use ``OVERRIDES`` to conditionally select a specific version of | 563 | You can use :term:`OVERRIDES` to conditionally select a specific version of |
507 | a variable and to conditionally append or prepend the value of a | 564 | a variable and to conditionally append or prepend the value of a |
508 | variable. | 565 | variable. |
509 | 566 | ||
510 | .. note:: | 567 | .. note:: |
511 | 568 | ||
512 | Overrides can only use lower-case characters. Additionally, | 569 | Overrides can only use lower-case characters, digits and dashes. |
513 | underscores are not permitted in override names as they are used to | 570 | In particular, colons are not permitted in override names as they are used to |
514 | separate overrides from each other and from the variable name. | 571 | separate overrides from each other and from the variable name. |
515 | 572 | ||
516 | - *Selecting a Variable:* The ``OVERRIDES`` variable is a | 573 | - *Selecting a Variable:* The :term:`OVERRIDES` variable is a |
517 | colon-character-separated list that contains items for which you want | 574 | colon-character-separated list that contains items for which you want |
518 | to satisfy conditions. Thus, if you have a variable that is | 575 | to satisfy conditions. Thus, if you have a variable that is |
519 | conditional on "arm", and "arm" is in ``OVERRIDES``, then the | 576 | conditional on "arm", and "arm" is in :term:`OVERRIDES`, then the |
520 | "arm"-specific version of the variable is used rather than the | 577 | "arm"-specific version of the variable is used rather than the |
521 | non-conditional version. Here is an example: :: | 578 | non-conditional version. Here is an example:: |
522 | 579 | ||
523 | OVERRIDES = "architecture:os:machine" | 580 | OVERRIDES = "architecture:os:machine" |
524 | TEST = "default" | 581 | TEST = "default" |
525 | TEST_os = "osspecific" | 582 | TEST:os = "osspecific" |
526 | TEST_nooverride = "othercondvalue" | 583 | TEST:nooverride = "othercondvalue" |
527 | 584 | ||
528 | In this example, the ``OVERRIDES`` | 585 | In this example, the :term:`OVERRIDES` |
529 | variable lists three overrides: "architecture", "os", and "machine". | 586 | variable lists three overrides: "architecture", "os", and "machine". |
530 | The variable ``TEST`` by itself has a default value of "default". You | 587 | The variable ``TEST`` by itself has a default value of "default". You |
531 | select the os-specific version of the ``TEST`` variable by appending | 588 | select the os-specific version of the ``TEST`` variable by appending |
532 | the "os" override to the variable (i.e. ``TEST_os``). | 589 | the "os" override to the variable (i.e. ``TEST:os``). |
533 | 590 | ||
534 | To better understand this, consider a practical example that assumes | 591 | To better understand this, consider a practical example that assumes |
535 | an OpenEmbedded metadata-based Linux kernel recipe file. The | 592 | an OpenEmbedded metadata-based Linux kernel recipe file. The |
536 | following lines from the recipe file first set the kernel branch | 593 | following lines from the recipe file first set the kernel branch |
537 | variable ``KBRANCH`` to a default value, then conditionally override | 594 | variable ``KBRANCH`` to a default value, then conditionally override |
538 | that value based on the architecture of the build: :: | 595 | that value based on the architecture of the build:: |
539 | 596 | ||
540 | KBRANCH = "standard/base" | 597 | KBRANCH = "standard/base" |
541 | KBRANCH_qemuarm = "standard/arm-versatile-926ejs" | 598 | KBRANCH:qemuarm = "standard/arm-versatile-926ejs" |
542 | KBRANCH_qemumips = "standard/mti-malta32" | 599 | KBRANCH:qemumips = "standard/mti-malta32" |
543 | KBRANCH_qemuppc = "standard/qemuppc" | 600 | KBRANCH:qemuppc = "standard/qemuppc" |
544 | KBRANCH_qemux86 = "standard/common-pc/base" | 601 | KBRANCH:qemux86 = "standard/common-pc/base" |
545 | KBRANCH_qemux86-64 = "standard/common-pc-64/base" | 602 | KBRANCH:qemux86-64 = "standard/common-pc-64/base" |
546 | KBRANCH_qemumips64 = "standard/mti-malta64" | 603 | KBRANCH:qemumips64 = "standard/mti-malta64" |
547 | 604 | ||
548 | - *Appending and Prepending:* BitBake also supports append and prepend | 605 | - *Appending and Prepending:* BitBake also supports append and prepend |
549 | operations to variable values based on whether a specific item is | 606 | operations to variable values based on whether a specific item is |
550 | listed in ``OVERRIDES``. Here is an example: :: | 607 | listed in :term:`OVERRIDES`. Here is an example:: |
551 | 608 | ||
552 | DEPENDS = "glibc ncurses" | 609 | DEPENDS = "glibc ncurses" |
553 | OVERRIDES = "machine:local" | 610 | OVERRIDES = "machine:local" |
554 | DEPENDS_append_machine = "libmad" | 611 | DEPENDS:append:machine = "libmad" |
555 | 612 | ||
556 | In this example, ``DEPENDS`` becomes "glibc ncurses libmad". | 613 | In this example, :term:`DEPENDS` becomes "glibc ncurses libmad". |
557 | 614 | ||
558 | Again, using an OpenEmbedded metadata-based kernel recipe file as an | 615 | Again, using an OpenEmbedded metadata-based kernel recipe file as an |
559 | example, the following lines will conditionally append to the | 616 | example, the following lines will conditionally append to the |
560 | ``KERNEL_FEATURES`` variable based on the architecture: :: | 617 | ``KERNEL_FEATURES`` variable based on the architecture:: |
561 | 618 | ||
562 | KERNEL_FEATURES_append = " ${KERNEL_EXTRA_FEATURES}" | 619 | KERNEL_FEATURES:append = " ${KERNEL_EXTRA_FEATURES}" |
563 | KERNEL_FEATURES_append_qemux86=" cfg/sound.scc cfg/paravirt_kvm.scc" | 620 | KERNEL_FEATURES:append:qemux86=" cfg/sound.scc cfg/paravirt_kvm.scc" |
564 | KERNEL_FEATURES_append_qemux86-64=" cfg/sound.scc cfg/paravirt_kvm.scc" | 621 | KERNEL_FEATURES:append:qemux86-64=" cfg/sound.scc cfg/paravirt_kvm.scc" |
565 | 622 | ||
566 | - *Setting a Variable for a Single Task:* BitBake supports setting a | 623 | - *Setting a Variable for a Single Task:* BitBake supports setting a |
567 | variable just for the duration of a single task. Here is an example: :: | 624 | variable just for the duration of a single task. Here is an example:: |
568 | 625 | ||
569 | FOO_task-configure = "val 1" | 626 | FOO:task-configure = "val 1" |
570 | FOO_task-compile = "val 2" | 627 | FOO:task-compile = "val 2" |
571 | 628 | ||
572 | In the | 629 | In the |
573 | previous example, ``FOO`` has the value "val 1" while the | 630 | previous example, ``FOO`` has the value "val 1" while the |
@@ -580,15 +637,25 @@ variable. | |||
580 | ``do_compile`` task. | 637 | ``do_compile`` task. |
581 | 638 | ||
582 | You can also use this syntax with other combinations (e.g. | 639 | You can also use this syntax with other combinations (e.g. |
583 | "``_prepend``") as shown in the following example: :: | 640 | "``:prepend``") as shown in the following example:: |
584 | 641 | ||
585 | EXTRA_OEMAKE_prepend_task-compile = "${PARALLEL_MAKE} " | 642 | EXTRA_OEMAKE:prepend:task-compile = "${PARALLEL_MAKE} " |
643 | |||
644 | .. note:: | ||
645 | |||
646 | Before BitBake 1.52 (Honister 3.4), the syntax for :term:`OVERRIDES` | ||
647 | used ``_`` instead of ``:``, so you will still find a lot of documentation | ||
648 | using ``_append``, ``_prepend``, and ``_remove``, for example. | ||
649 | |||
650 | For details, see the | ||
651 | :yocto_docs:`Overrides Syntax Changes </migration-guides/migration-3.4.html#override-syntax-changes>` | ||
652 | section in the Yocto Project manual migration notes. | ||
586 | 653 | ||
587 | Key Expansion | 654 | Key Expansion |
588 | ------------- | 655 | ------------- |
589 | 656 | ||
590 | Key expansion happens when the BitBake datastore is finalized. To better | 657 | Key expansion happens when the BitBake datastore is finalized. To better |
591 | understand this, consider the following example: :: | 658 | understand this, consider the following example:: |
592 | 659 | ||
593 | A${B} = "X" | 660 | A${B} = "X" |
594 | B = "2" | 661 | B = "2" |
@@ -612,57 +679,57 @@ users. | |||
612 | 679 | ||
613 | There is often confusion concerning the order in which overrides and | 680 | There is often confusion concerning the order in which overrides and |
614 | various "append" operators take effect. Recall that an append or prepend | 681 | various "append" operators take effect. Recall that an append or prepend |
615 | operation using "_append" and "_prepend" does not result in an immediate | 682 | operation using ":append" and ":prepend" does not result in an immediate |
616 | assignment as would "+=", ".=", "=+", or "=.". Consider the following | 683 | assignment as would "+=", ".=", "=+", or "=.". Consider the following |
617 | example: :: | 684 | example:: |
618 | 685 | ||
619 | OVERRIDES = "foo" | 686 | OVERRIDES = "foo" |
620 | A = "Z" | 687 | A = "Z" |
621 | A_foo_append = "X" | 688 | A:foo:append = "X" |
622 | 689 | ||
623 | For this case, | 690 | For this case, |
624 | ``A`` is unconditionally set to "Z" and "X" is unconditionally and | 691 | ``A`` is unconditionally set to "Z" and "X" is unconditionally and |
625 | immediately appended to the variable ``A_foo``. Because overrides have | 692 | immediately appended to the variable ``A:foo``. Because overrides have |
626 | not been applied yet, ``A_foo`` is set to "X" due to the append and | 693 | not been applied yet, ``A:foo`` is set to "X" due to the append and |
627 | ``A`` simply equals "Z". | 694 | ``A`` simply equals "Z". |
628 | 695 | ||
629 | Applying overrides, however, changes things. Since "foo" is listed in | 696 | Applying overrides, however, changes things. Since "foo" is listed in |
630 | ``OVERRIDES``, the conditional variable ``A`` is replaced with the "foo" | 697 | :term:`OVERRIDES`, the conditional variable ``A`` is replaced with the "foo" |
631 | version, which is equal to "X". So effectively, ``A_foo`` replaces | 698 | version, which is equal to "X". So effectively, ``A:foo`` replaces |
632 | ``A``. | 699 | ``A``. |
633 | 700 | ||
634 | This next example changes the order of the override and the append: :: | 701 | This next example changes the order of the override and the append:: |
635 | 702 | ||
636 | OVERRIDES = "foo" | 703 | OVERRIDES = "foo" |
637 | A = "Z" | 704 | A = "Z" |
638 | A_append_foo = "X" | 705 | A:append:foo = "X" |
639 | 706 | ||
640 | For this case, before | 707 | For this case, before |
641 | overrides are handled, ``A`` is set to "Z" and ``A_append_foo`` is set | 708 | overrides are handled, ``A`` is set to "Z" and ``A:append:foo`` is set |
642 | to "X". Once the override for "foo" is applied, however, ``A`` gets | 709 | to "X". Once the override for "foo" is applied, however, ``A`` gets |
643 | appended with "X". Consequently, ``A`` becomes "ZX". Notice that spaces | 710 | appended with "X". Consequently, ``A`` becomes "ZX". Notice that spaces |
644 | are not appended. | 711 | are not appended. |
645 | 712 | ||
646 | This next example has the order of the appends and overrides reversed | 713 | This next example has the order of the appends and overrides reversed |
647 | back as in the first example: :: | 714 | back as in the first example:: |
648 | 715 | ||
649 | OVERRIDES = "foo" | 716 | OVERRIDES = "foo" |
650 | A = "Y" | 717 | A = "Y" |
651 | A_foo_append = "Z" | 718 | A:foo:append = "Z" |
652 | A_foo_append = "X" | 719 | A:foo:append = "X" |
653 | 720 | ||
654 | For this case, before any overrides are resolved, | 721 | For this case, before any overrides are resolved, |
655 | ``A`` is set to "Y" using an immediate assignment. After this immediate | 722 | ``A`` is set to "Y" using an immediate assignment. After this immediate |
656 | assignment, ``A_foo`` is set to "Z", and then further appended with "X" | 723 | assignment, ``A:foo`` is set to "Z", and then further appended with "X" |
657 | leaving the variable set to "ZX". Finally, applying the override for | 724 | leaving the variable set to "ZX". Finally, applying the override for |
658 | "foo" results in the conditional variable ``A`` becoming "ZX" (i.e. | 725 | "foo" results in the conditional variable ``A`` becoming "ZX" (i.e. |
659 | ``A`` is replaced with ``A_foo``). | 726 | ``A`` is replaced with ``A:foo``). |
660 | 727 | ||
661 | This final example mixes in some varying operators: :: | 728 | This final example mixes in some varying operators:: |
662 | 729 | ||
663 | A = "1" | 730 | A = "1" |
664 | A_append = "2" | 731 | A:append = "2" |
665 | A_append = "3" | 732 | A:append = "3" |
666 | A += "4" | 733 | A += "4" |
667 | A .= "5" | 734 | A .= "5" |
668 | 735 | ||
@@ -670,7 +737,7 @@ For this case, the type of append | |||
670 | operators are affecting the order of assignments as BitBake passes | 737 | operators are affecting the order of assignments as BitBake passes |
671 | through the code multiple times. Initially, ``A`` is set to "1 45" | 738 | through the code multiple times. Initially, ``A`` is set to "1 45" |
672 | because of the three statements that use immediate operators. After | 739 | because of the three statements that use immediate operators. After |
673 | these assignments are made, BitBake applies the "_append" operations. | 740 | these assignments are made, BitBake applies the ":append" operations. |
674 | Those operations result in ``A`` becoming "1 4523". | 741 | Those operations result in ``A`` becoming "1 4523". |
675 | 742 | ||
676 | Sharing Functionality | 743 | Sharing Functionality |
@@ -686,7 +753,7 @@ share the task. | |||
686 | 753 | ||
687 | This section presents the mechanisms BitBake provides to allow you to | 754 | This section presents the mechanisms BitBake provides to allow you to |
688 | share functionality between recipes. Specifically, the mechanisms | 755 | share functionality between recipes. Specifically, the mechanisms |
689 | include ``include``, ``inherit``, ``INHERIT``, and ``require`` | 756 | include ``include``, ``inherit``, :term:`INHERIT`, and ``require`` |
690 | directives. | 757 | directives. |
691 | 758 | ||
692 | Locating Include and Class Files | 759 | Locating Include and Class Files |
@@ -702,7 +769,7 @@ current directory for ``include`` and ``require`` directives. | |||
702 | 769 | ||
703 | In order for include and class files to be found by BitBake, they need | 770 | In order for include and class files to be found by BitBake, they need |
704 | to be located in a "classes" subdirectory that can be found in | 771 | to be located in a "classes" subdirectory that can be found in |
705 | ``BBPATH``. | 772 | :term:`BBPATH`. |
706 | 773 | ||
707 | ``inherit`` Directive | 774 | ``inherit`` Directive |
708 | --------------------- | 775 | --------------------- |
@@ -720,12 +787,12 @@ file and then have your recipe inherit that class file. | |||
720 | 787 | ||
721 | As an example, your recipes could use the following directive to inherit | 788 | As an example, your recipes could use the following directive to inherit |
722 | an ``autotools.bbclass`` file. The class file would contain common | 789 | an ``autotools.bbclass`` file. The class file would contain common |
723 | functionality for using Autotools that could be shared across recipes: :: | 790 | functionality for using Autotools that could be shared across recipes:: |
724 | 791 | ||
725 | inherit autotools | 792 | inherit autotools |
726 | 793 | ||
727 | In this case, BitBake would search for the directory | 794 | In this case, BitBake would search for the directory |
728 | ``classes/autotools.bbclass`` in ``BBPATH``. | 795 | ``classes/autotools.bbclass`` in :term:`BBPATH`. |
729 | 796 | ||
730 | .. note:: | 797 | .. note:: |
731 | 798 | ||
@@ -734,7 +801,7 @@ In this case, BitBake would search for the directory | |||
734 | 801 | ||
735 | If you want to use the directive to inherit multiple classes, separate | 802 | If you want to use the directive to inherit multiple classes, separate |
736 | them with spaces. The following example shows how to inherit both the | 803 | them with spaces. The following example shows how to inherit both the |
737 | ``buildhistory`` and ``rm_work`` classes: :: | 804 | ``buildhistory`` and ``rm_work`` classes:: |
738 | 805 | ||
739 | inherit buildhistory rm_work | 806 | inherit buildhistory rm_work |
740 | 807 | ||
@@ -742,19 +809,19 @@ An advantage with the inherit directive as compared to both the | |||
742 | :ref:`include <bitbake-user-manual/bitbake-user-manual-metadata:\`\`include\`\` directive>` and :ref:`require <bitbake-user-manual/bitbake-user-manual-metadata:\`\`require\`\` directive>` | 809 | :ref:`include <bitbake-user-manual/bitbake-user-manual-metadata:\`\`include\`\` directive>` and :ref:`require <bitbake-user-manual/bitbake-user-manual-metadata:\`\`require\`\` directive>` |
743 | directives is that you can inherit class files conditionally. You can | 810 | directives is that you can inherit class files conditionally. You can |
744 | accomplish this by using a variable expression after the ``inherit`` | 811 | accomplish this by using a variable expression after the ``inherit`` |
745 | statement. Here is an example: :: | 812 | statement. Here is an example:: |
746 | 813 | ||
747 | inherit ${VARNAME} | 814 | inherit ${VARNAME} |
748 | 815 | ||
749 | If ``VARNAME`` is | 816 | If ``VARNAME`` is |
750 | going to be set, it needs to be set before the ``inherit`` statement is | 817 | going to be set, it needs to be set before the ``inherit`` statement is |
751 | parsed. One way to achieve a conditional inherit in this case is to use | 818 | parsed. One way to achieve a conditional inherit in this case is to use |
752 | overrides: :: | 819 | overrides:: |
753 | 820 | ||
754 | VARIABLE = "" | 821 | VARIABLE = "" |
755 | VARIABLE_someoverride = "myclass" | 822 | VARIABLE:someoverride = "myclass" |
756 | 823 | ||
757 | Another method is by using anonymous Python. Here is an example: :: | 824 | Another method is by using anonymous Python. Here is an example:: |
758 | 825 | ||
759 | python () { | 826 | python () { |
760 | if condition == value: | 827 | if condition == value: |
@@ -764,7 +831,7 @@ Another method is by using anonymous Python. Here is an example: :: | |||
764 | } | 831 | } |
765 | 832 | ||
766 | Alternatively, you could use an in-line Python expression in the | 833 | Alternatively, you could use an in-line Python expression in the |
767 | following form: :: | 834 | following form:: |
768 | 835 | ||
769 | inherit ${@'classname' if condition else ''} | 836 | inherit ${@'classname' if condition else ''} |
770 | inherit ${@functionname(params)} | 837 | inherit ${@functionname(params)} |
@@ -780,7 +847,7 @@ BitBake understands the ``include`` directive. This directive causes | |||
780 | BitBake to parse whatever file you specify, and to insert that file at | 847 | BitBake to parse whatever file you specify, and to insert that file at |
781 | that location. The directive is much like its equivalent in Make except | 848 | that location. The directive is much like its equivalent in Make except |
782 | that if the path specified on the include line is a relative path, | 849 | that if the path specified on the include line is a relative path, |
783 | BitBake locates the first file it can find within ``BBPATH``. | 850 | BitBake locates the first file it can find within :term:`BBPATH`. |
784 | 851 | ||
785 | The include directive is a more generic method of including | 852 | The include directive is a more generic method of including |
786 | functionality as compared to the :ref:`inherit <bitbake-user-manual/bitbake-user-manual-metadata:\`\`inherit\`\` directive>` | 853 | 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 | |||
790 | ``.bbclass`` file. | 857 | ``.bbclass`` file. |
791 | 858 | ||
792 | As an example, suppose you needed a recipe to include some self-test | 859 | As an example, suppose you needed a recipe to include some self-test |
793 | definitions: :: | 860 | definitions:: |
794 | 861 | ||
795 | include test_defs.inc | 862 | include test_defs.inc |
796 | 863 | ||
@@ -822,7 +889,7 @@ does not suit a ``.bbclass`` file. | |||
822 | 889 | ||
823 | Similar to how BitBake handles :ref:`include <bitbake-user-manual/bitbake-user-manual-metadata:\`\`include\`\` directive>`, if | 890 | Similar to how BitBake handles :ref:`include <bitbake-user-manual/bitbake-user-manual-metadata:\`\`include\`\` directive>`, if |
824 | the path specified on the require line is a relative path, BitBake | 891 | the path specified on the require line is a relative path, BitBake |
825 | locates the first file it can find within ``BBPATH``. | 892 | locates the first file it can find within :term:`BBPATH`. |
826 | 893 | ||
827 | As an example, suppose you have two versions of a recipe (e.g. | 894 | As an example, suppose you have two versions of a recipe (e.g. |
828 | ``foo_1.2.2.bb`` and ``foo_2.0.0.bb``) where each version contains some | 895 | ``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 | |||
831 | needed to build "foo". You need to be sure ``foo.inc`` is located in the | 898 | needed to build "foo". You need to be sure ``foo.inc`` is located in the |
832 | same directory as your two recipe files as well. Once these conditions | 899 | same directory as your two recipe files as well. Once these conditions |
833 | are set up, you can share the functionality using a ``require`` | 900 | are set up, you can share the functionality using a ``require`` |
834 | directive from within each recipe: :: | 901 | directive from within each recipe:: |
835 | 902 | ||
836 | require foo.inc | 903 | require foo.inc |
837 | 904 | ||
@@ -844,14 +911,14 @@ class. BitBake only supports this directive when used within a | |||
844 | configuration file. | 911 | configuration file. |
845 | 912 | ||
846 | As an example, suppose you needed to inherit a class file called | 913 | As an example, suppose you needed to inherit a class file called |
847 | ``abc.bbclass`` from a configuration file as follows: :: | 914 | ``abc.bbclass`` from a configuration file as follows:: |
848 | 915 | ||
849 | INHERIT += "abc" | 916 | INHERIT += "abc" |
850 | 917 | ||
851 | This configuration directive causes the named class to be inherited at | 918 | This configuration directive causes the named class to be inherited at |
852 | the point of the directive during parsing. As with the ``inherit`` | 919 | the point of the directive during parsing. As with the ``inherit`` |
853 | directive, the ``.bbclass`` file must be located in a "classes" | 920 | directive, the ``.bbclass`` file must be located in a "classes" |
854 | subdirectory in one of the directories specified in ``BBPATH``. | 921 | subdirectory in one of the directories specified in :term:`BBPATH`. |
855 | 922 | ||
856 | .. note:: | 923 | .. note:: |
857 | 924 | ||
@@ -862,7 +929,7 @@ subdirectory in one of the directories specified in ``BBPATH``. | |||
862 | If you want to use the directive to inherit multiple classes, you can | 929 | If you want to use the directive to inherit multiple classes, you can |
863 | provide them on the same line in the ``local.conf`` file. Use spaces to | 930 | provide them on the same line in the ``local.conf`` file. Use spaces to |
864 | separate the classes. The following example shows how to inherit both | 931 | separate the classes. The following example shows how to inherit both |
865 | the ``autotools`` and ``pkgconfig`` classes: :: | 932 | the ``autotools`` and ``pkgconfig`` classes:: |
866 | 933 | ||
867 | INHERIT += "autotools pkgconfig" | 934 | INHERIT += "autotools pkgconfig" |
868 | 935 | ||
@@ -893,9 +960,9 @@ Regardless of the type of function, you can only define them in class | |||
893 | Shell Functions | 960 | Shell Functions |
894 | --------------- | 961 | --------------- |
895 | 962 | ||
896 | Functions written in shell script and executed either directly as | 963 | Functions written in shell script are executed either directly as |
897 | functions, tasks, or both. They can also be called by other shell | 964 | functions, tasks, or both. They can also be called by other shell |
898 | functions. Here is an example shell function definition: :: | 965 | functions. Here is an example shell function definition:: |
899 | 966 | ||
900 | some_function () { | 967 | some_function () { |
901 | echo "Hello World" | 968 | echo "Hello World" |
@@ -907,19 +974,19 @@ rules. The scripts are executed by ``/bin/sh``, which may not be a bash | |||
907 | shell but might be something such as ``dash``. You should not use | 974 | shell but might be something such as ``dash``. You should not use |
908 | Bash-specific script (bashisms). | 975 | Bash-specific script (bashisms). |
909 | 976 | ||
910 | Overrides and override-style operators like ``_append`` and ``_prepend`` | 977 | Overrides and override-style operators like ``:append`` and ``:prepend`` |
911 | can also be applied to shell functions. Most commonly, this application | 978 | can also be applied to shell functions. Most commonly, this application |
912 | would be used in a ``.bbappend`` file to modify functions in the main | 979 | would be used in a ``.bbappend`` file to modify functions in the main |
913 | recipe. It can also be used to modify functions inherited from classes. | 980 | recipe. It can also be used to modify functions inherited from classes. |
914 | 981 | ||
915 | As an example, consider the following: :: | 982 | As an example, consider the following:: |
916 | 983 | ||
917 | do_foo() { | 984 | do_foo() { |
918 | bbplain first | 985 | bbplain first |
919 | fn | 986 | fn |
920 | } | 987 | } |
921 | 988 | ||
922 | fn_prepend() { | 989 | fn:prepend() { |
923 | bbplain second | 990 | bbplain second |
924 | } | 991 | } |
925 | 992 | ||
@@ -927,11 +994,11 @@ As an example, consider the following: :: | |||
927 | bbplain third | 994 | bbplain third |
928 | } | 995 | } |
929 | 996 | ||
930 | do_foo_append() { | 997 | do_foo:append() { |
931 | bbplain fourth | 998 | bbplain fourth |
932 | } | 999 | } |
933 | 1000 | ||
934 | Running ``do_foo`` prints the following: :: | 1001 | Running ``do_foo`` prints the following:: |
935 | 1002 | ||
936 | recipename do_foo: first | 1003 | recipename do_foo: first |
937 | recipename do_foo: second | 1004 | recipename do_foo: second |
@@ -943,7 +1010,7 @@ Running ``do_foo`` prints the following: :: | |||
943 | Overrides and override-style operators can be applied to any shell | 1010 | Overrides and override-style operators can be applied to any shell |
944 | function, not just :ref:`tasks <bitbake-user-manual/bitbake-user-manual-metadata:tasks>`. | 1011 | function, not just :ref:`tasks <bitbake-user-manual/bitbake-user-manual-metadata:tasks>`. |
945 | 1012 | ||
946 | You can use the ``bitbake -e`` recipename command to view the final | 1013 | You can use the ``bitbake -e recipename`` command to view the final |
947 | assembled function after all overrides have been applied. | 1014 | assembled function after all overrides have been applied. |
948 | 1015 | ||
949 | BitBake-Style Python Functions | 1016 | BitBake-Style Python Functions |
@@ -952,7 +1019,7 @@ BitBake-Style Python Functions | |||
952 | These functions are written in Python and executed by BitBake or other | 1019 | These functions are written in Python and executed by BitBake or other |
953 | Python functions using ``bb.build.exec_func()``. | 1020 | Python functions using ``bb.build.exec_func()``. |
954 | 1021 | ||
955 | An example BitBake function is: :: | 1022 | An example BitBake function is:: |
956 | 1023 | ||
957 | python some_python_function () { | 1024 | python some_python_function () { |
958 | d.setVar("TEXT", "Hello World") | 1025 | d.setVar("TEXT", "Hello World") |
@@ -975,9 +1042,9 @@ import these modules. Also in these types of functions, the datastore | |||
975 | Similar to shell functions, you can also apply overrides and | 1042 | Similar to shell functions, you can also apply overrides and |
976 | override-style operators to BitBake-style Python functions. | 1043 | override-style operators to BitBake-style Python functions. |
977 | 1044 | ||
978 | As an example, consider the following: :: | 1045 | As an example, consider the following:: |
979 | 1046 | ||
980 | python do_foo_prepend() { | 1047 | python do_foo:prepend() { |
981 | bb.plain("first") | 1048 | bb.plain("first") |
982 | } | 1049 | } |
983 | 1050 | ||
@@ -985,17 +1052,17 @@ As an example, consider the following: :: | |||
985 | bb.plain("second") | 1052 | bb.plain("second") |
986 | } | 1053 | } |
987 | 1054 | ||
988 | python do_foo_append() { | 1055 | python do_foo:append() { |
989 | bb.plain("third") | 1056 | bb.plain("third") |
990 | } | 1057 | } |
991 | 1058 | ||
992 | Running ``do_foo`` prints the following: :: | 1059 | Running ``do_foo`` prints the following:: |
993 | 1060 | ||
994 | recipename do_foo: first | 1061 | recipename do_foo: first |
995 | recipename do_foo: second | 1062 | recipename do_foo: second |
996 | recipename do_foo: third | 1063 | recipename do_foo: third |
997 | 1064 | ||
998 | You can use the ``bitbake -e`` recipename command to view | 1065 | You can use the ``bitbake -e recipename`` command to view |
999 | the final assembled function after all overrides have been applied. | 1066 | the final assembled function after all overrides have been applied. |
1000 | 1067 | ||
1001 | Python Functions | 1068 | Python Functions |
@@ -1004,7 +1071,7 @@ Python Functions | |||
1004 | These functions are written in Python and are executed by other Python | 1071 | These functions are written in Python and are executed by other Python |
1005 | code. Examples of Python functions are utility functions that you intend | 1072 | code. Examples of Python functions are utility functions that you intend |
1006 | to call from in-line Python or from within other Python functions. Here | 1073 | to call from in-line Python or from within other Python functions. Here |
1007 | is an example: :: | 1074 | is an example:: |
1008 | 1075 | ||
1009 | def get_depends(d): | 1076 | def get_depends(d): |
1010 | if d.getVar('SOMECONDITION'): | 1077 | if d.getVar('SOMECONDITION'): |
@@ -1015,7 +1082,7 @@ is an example: :: | |||
1015 | SOMECONDITION = "1" | 1082 | SOMECONDITION = "1" |
1016 | DEPENDS = "${@get_depends(d)}" | 1083 | DEPENDS = "${@get_depends(d)}" |
1017 | 1084 | ||
1018 | This would result in ``DEPENDS`` containing ``dependencywithcond``. | 1085 | This would result in :term:`DEPENDS` containing ``dependencywithcond``. |
1019 | 1086 | ||
1020 | Here are some things to know about Python functions: | 1087 | Here are some things to know about Python functions: |
1021 | 1088 | ||
@@ -1056,7 +1123,7 @@ functions and regular Python functions defined with "def": | |||
1056 | - Regular Python functions are called with the usual Python syntax. | 1123 | - Regular Python functions are called with the usual Python syntax. |
1057 | BitBake-style Python functions are usually tasks and are called | 1124 | BitBake-style Python functions are usually tasks and are called |
1058 | directly by BitBake, but can also be called manually from Python code | 1125 | directly by BitBake, but can also be called manually from Python code |
1059 | by using the ``bb.build.exec_func()`` function. Here is an example: :: | 1126 | by using the ``bb.build.exec_func()`` function. Here is an example:: |
1060 | 1127 | ||
1061 | bb.build.exec_func("my_bitbake_style_function", d) | 1128 | bb.build.exec_func("my_bitbake_style_function", d) |
1062 | 1129 | ||
@@ -1094,7 +1161,7 @@ Sometimes it is useful to set variables or perform other operations | |||
1094 | programmatically during parsing. To do this, you can define special | 1161 | programmatically during parsing. To do this, you can define special |
1095 | Python functions, called anonymous Python functions, that run at the end | 1162 | Python functions, called anonymous Python functions, that run at the end |
1096 | of parsing. For example, the following conditionally sets a variable | 1163 | of parsing. For example, the following conditionally sets a variable |
1097 | based on the value of another variable: :: | 1164 | based on the value of another variable:: |
1098 | 1165 | ||
1099 | python () { | 1166 | python () { |
1100 | if d.getVar('SOMEVAR') == 'value': | 1167 | if d.getVar('SOMEVAR') == 'value': |
@@ -1107,7 +1174,7 @@ the name "__anonymous", rather than no name. | |||
1107 | Anonymous Python functions always run at the end of parsing, regardless | 1174 | Anonymous Python functions always run at the end of parsing, regardless |
1108 | of where they are defined. If a recipe contains many anonymous | 1175 | of where they are defined. If a recipe contains many anonymous |
1109 | functions, they run in the same order as they are defined within the | 1176 | functions, they run in the same order as they are defined within the |
1110 | recipe. As an example, consider the following snippet: :: | 1177 | recipe. As an example, consider the following snippet:: |
1111 | 1178 | ||
1112 | python () { | 1179 | python () { |
1113 | d.setVar('FOO', 'foo 2') | 1180 | d.setVar('FOO', 'foo 2') |
@@ -1122,7 +1189,7 @@ recipe. As an example, consider the following snippet: :: | |||
1122 | BAR = "bar 1" | 1189 | BAR = "bar 1" |
1123 | 1190 | ||
1124 | The previous example is conceptually | 1191 | The previous example is conceptually |
1125 | equivalent to the following snippet: :: | 1192 | equivalent to the following snippet:: |
1126 | 1193 | ||
1127 | FOO = "foo 1" | 1194 | FOO = "foo 1" |
1128 | BAR = "bar 1" | 1195 | BAR = "bar 1" |
@@ -1134,12 +1201,12 @@ equivalent to the following snippet: :: | |||
1134 | values set for the variables within the anonymous functions become | 1201 | values set for the variables within the anonymous functions become |
1135 | available to tasks, which always run after parsing. | 1202 | available to tasks, which always run after parsing. |
1136 | 1203 | ||
1137 | Overrides and override-style operators such as "``_append``" are applied | 1204 | Overrides and override-style operators such as "``:append``" are applied |
1138 | before anonymous functions run. In the following example, ``FOO`` ends | 1205 | before anonymous functions run. In the following example, ``FOO`` ends |
1139 | up with the value "foo from anonymous": :: | 1206 | up with the value "foo from anonymous":: |
1140 | 1207 | ||
1141 | FOO = "foo" | 1208 | FOO = "foo" |
1142 | FOO_append = " from outside" | 1209 | FOO:append = " from outside" |
1143 | 1210 | ||
1144 | python () { | 1211 | python () { |
1145 | d.setVar("FOO", "foo from anonymous") | 1212 | d.setVar("FOO", "foo from anonymous") |
@@ -1164,7 +1231,7 @@ To understand the benefits of this feature, consider the basic scenario | |||
1164 | where a class defines a task function and your recipe inherits the | 1231 | where a class defines a task function and your recipe inherits the |
1165 | class. In this basic scenario, your recipe inherits the task function as | 1232 | class. In this basic scenario, your recipe inherits the task function as |
1166 | defined in the class. If desired, your recipe can add to the start and | 1233 | defined in the class. If desired, your recipe can add to the start and |
1167 | end of the function by using the "_prepend" or "_append" operations | 1234 | end of the function by using the ":prepend" or ":append" operations |
1168 | respectively, or it can redefine the function completely. However, if it | 1235 | respectively, or it can redefine the function completely. However, if it |
1169 | redefines the function, there is no means for it to call the class | 1236 | redefines the function, there is no means for it to call the class |
1170 | version of the function. ``EXPORT_FUNCTIONS`` provides a mechanism that | 1237 | version of the function. ``EXPORT_FUNCTIONS`` provides a mechanism that |
@@ -1173,24 +1240,24 @@ version of the function. | |||
1173 | 1240 | ||
1174 | To make use of this technique, you need the following things in place: | 1241 | To make use of this technique, you need the following things in place: |
1175 | 1242 | ||
1176 | - The class needs to define the function as follows: :: | 1243 | - The class needs to define the function as follows:: |
1177 | 1244 | ||
1178 | classname_functionname | 1245 | classname_functionname |
1179 | 1246 | ||
1180 | For example, if you have a class file | 1247 | For example, if you have a class file |
1181 | ``bar.bbclass`` and a function named ``do_foo``, the class must | 1248 | ``bar.bbclass`` and a function named ``do_foo``, the class must |
1182 | define the function as follows: :: | 1249 | define the function as follows:: |
1183 | 1250 | ||
1184 | bar_do_foo | 1251 | bar_do_foo |
1185 | 1252 | ||
1186 | - The class needs to contain the ``EXPORT_FUNCTIONS`` statement as | 1253 | - The class needs to contain the ``EXPORT_FUNCTIONS`` statement as |
1187 | follows: :: | 1254 | follows:: |
1188 | 1255 | ||
1189 | EXPORT_FUNCTIONS functionname | 1256 | EXPORT_FUNCTIONS functionname |
1190 | 1257 | ||
1191 | For example, continuing with | 1258 | For example, continuing with |
1192 | the same example, the statement in the ``bar.bbclass`` would be as | 1259 | the same example, the statement in the ``bar.bbclass`` would be as |
1193 | follows: :: | 1260 | follows:: |
1194 | 1261 | ||
1195 | EXPORT_FUNCTIONS do_foo | 1262 | EXPORT_FUNCTIONS do_foo |
1196 | 1263 | ||
@@ -1199,7 +1266,7 @@ To make use of this technique, you need the following things in place: | |||
1199 | class version of the function, it should call ``bar_do_foo``. | 1266 | class version of the function, it should call ``bar_do_foo``. |
1200 | Assuming ``do_foo`` was a shell function and ``EXPORT_FUNCTIONS`` was | 1267 | Assuming ``do_foo`` was a shell function and ``EXPORT_FUNCTIONS`` was |
1201 | used as above, the recipe's function could conditionally call the | 1268 | used as above, the recipe's function could conditionally call the |
1202 | class version of the function as follows: :: | 1269 | class version of the function as follows:: |
1203 | 1270 | ||
1204 | do_foo() { | 1271 | do_foo() { |
1205 | if [ somecondition ] ; then | 1272 | if [ somecondition ] ; then |
@@ -1233,7 +1300,7 @@ Tasks are either :ref:`shell functions <bitbake-user-manual/bitbake-user-manual- | |||
1233 | that have been promoted to tasks by using the ``addtask`` command. The | 1300 | that have been promoted to tasks by using the ``addtask`` command. The |
1234 | ``addtask`` command can also optionally describe dependencies between | 1301 | ``addtask`` command can also optionally describe dependencies between |
1235 | the task and other tasks. Here is an example that shows how to define a | 1302 | the task and other tasks. Here is an example that shows how to define a |
1236 | task and declare some dependencies: :: | 1303 | task and declare some dependencies:: |
1237 | 1304 | ||
1238 | python do_printdate () { | 1305 | python do_printdate () { |
1239 | import time | 1306 | import time |
@@ -1264,12 +1331,12 @@ Additionally, the ``do_printdate`` task becomes dependent upon the | |||
1264 | rerun for experimentation purposes, you can make BitBake always | 1331 | rerun for experimentation purposes, you can make BitBake always |
1265 | consider the task "out-of-date" by using the | 1332 | consider the task "out-of-date" by using the |
1266 | :ref:`[nostamp] <bitbake-user-manual/bitbake-user-manual-metadata:Variable Flags>` | 1333 | :ref:`[nostamp] <bitbake-user-manual/bitbake-user-manual-metadata:Variable Flags>` |
1267 | variable flag, as follows: :: | 1334 | variable flag, as follows:: |
1268 | 1335 | ||
1269 | do_printdate[nostamp] = "1" | 1336 | do_printdate[nostamp] = "1" |
1270 | 1337 | ||
1271 | You can also explicitly run the task and provide the | 1338 | You can also explicitly run the task and provide the |
1272 | -f option as follows: :: | 1339 | -f option as follows:: |
1273 | 1340 | ||
1274 | $ bitbake recipe -c printdate -f | 1341 | $ bitbake recipe -c printdate -f |
1275 | 1342 | ||
@@ -1278,7 +1345,7 @@ Additionally, the ``do_printdate`` task becomes dependent upon the | |||
1278 | name. | 1345 | name. |
1279 | 1346 | ||
1280 | You might wonder about the practical effects of using ``addtask`` | 1347 | You might wonder about the practical effects of using ``addtask`` |
1281 | without specifying any dependencies as is done in the following example: :: | 1348 | without specifying any dependencies as is done in the following example:: |
1282 | 1349 | ||
1283 | addtask printdate | 1350 | addtask printdate |
1284 | 1351 | ||
@@ -1286,7 +1353,7 @@ In this example, assuming dependencies have not been | |||
1286 | added through some other means, the only way to run the task is by | 1353 | added through some other means, the only way to run the task is by |
1287 | explicitly selecting it with ``bitbake`` recipe ``-c printdate``. You | 1354 | explicitly selecting it with ``bitbake`` recipe ``-c printdate``. You |
1288 | can use the ``do_listtasks`` task to list all tasks defined in a recipe | 1355 | can use the ``do_listtasks`` task to list all tasks defined in a recipe |
1289 | as shown in the following example: :: | 1356 | as shown in the following example:: |
1290 | 1357 | ||
1291 | $ bitbake recipe -c listtasks | 1358 | $ bitbake recipe -c listtasks |
1292 | 1359 | ||
@@ -1296,12 +1363,23 @@ For more information on task dependencies, see the | |||
1296 | See the ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:variable flags`" section for information | 1363 | See the ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:variable flags`" section for information |
1297 | on variable flags you can use with tasks. | 1364 | on variable flags you can use with tasks. |
1298 | 1365 | ||
1366 | .. note:: | ||
1367 | |||
1368 | While it's infrequent, it's possible to define multiple tasks as | ||
1369 | dependencies when calling ``addtask``. For example, here's a snippet | ||
1370 | from the OpenEmbedded class file ``package_tar.bbclass``:: | ||
1371 | |||
1372 | addtask package_write_tar before do_build after do_packagedata do_package | ||
1373 | |||
1374 | Note how the ``package_write_tar`` task has to wait until both of | ||
1375 | ``do_packagedata`` and ``do_package`` complete. | ||
1376 | |||
1299 | Deleting a Task | 1377 | Deleting a Task |
1300 | --------------- | 1378 | --------------- |
1301 | 1379 | ||
1302 | As well as being able to add tasks, you can delete them. Simply use the | 1380 | As well as being able to add tasks, you can delete them. Simply use the |
1303 | ``deltask`` command to delete a task. For example, to delete the example | 1381 | ``deltask`` command to delete a task. For example, to delete the example |
1304 | task used in the previous sections, you would use: :: | 1382 | task used in the previous sections, you would use:: |
1305 | 1383 | ||
1306 | deltask printdate | 1384 | deltask printdate |
1307 | 1385 | ||
@@ -1317,7 +1395,7 @@ to run before ``do_a``. | |||
1317 | 1395 | ||
1318 | If you want dependencies such as these to remain intact, use the | 1396 | If you want dependencies such as these to remain intact, use the |
1319 | ``[noexec]`` varflag to disable the task instead of using the | 1397 | ``[noexec]`` varflag to disable the task instead of using the |
1320 | ``deltask`` command to delete it: :: | 1398 | ``deltask`` command to delete it:: |
1321 | 1399 | ||
1322 | do_b[noexec] = "1" | 1400 | do_b[noexec] = "1" |
1323 | 1401 | ||
@@ -1331,8 +1409,8 @@ the build machine cannot influence the build. | |||
1331 | .. note:: | 1409 | .. note:: |
1332 | 1410 | ||
1333 | By default, BitBake cleans the environment to include only those | 1411 | By default, BitBake cleans the environment to include only those |
1334 | things exported or listed in its whitelist to ensure that the build | 1412 | things exported or listed in its passthrough list to ensure that the |
1335 | environment is reproducible and consistent. You can prevent this | 1413 | build environment is reproducible and consistent. You can prevent this |
1336 | "cleaning" by setting the :term:`BB_PRESERVE_ENV` variable. | 1414 | "cleaning" by setting the :term:`BB_PRESERVE_ENV` variable. |
1337 | 1415 | ||
1338 | Consequently, if you do want something to get passed into the build task | 1416 | Consequently, if you do want something to get passed into the build task |
@@ -1340,14 +1418,14 @@ environment, you must take these two steps: | |||
1340 | 1418 | ||
1341 | #. Tell BitBake to load what you want from the environment into the | 1419 | #. Tell BitBake to load what you want from the environment into the |
1342 | datastore. You can do so through the | 1420 | datastore. You can do so through the |
1343 | :term:`BB_ENV_WHITELIST` and | 1421 | :term:`BB_ENV_PASSTHROUGH` and |
1344 | :term:`BB_ENV_EXTRAWHITE` variables. For | 1422 | :term:`BB_ENV_PASSTHROUGH_ADDITIONS` variables. For |
1345 | example, assume you want to prevent the build system from accessing | 1423 | example, assume you want to prevent the build system from accessing |
1346 | your ``$HOME/.ccache`` directory. The following command "whitelists" | 1424 | your ``$HOME/.ccache`` directory. The following command adds the |
1347 | the environment variable ``CCACHE_DIR`` causing BitBake to allow that | 1425 | the environment variable ``CCACHE_DIR`` to BitBake's passthrough |
1348 | variable into the datastore: :: | 1426 | list to allow that variable into the datastore:: |
1349 | 1427 | ||
1350 | export BB_ENV_EXTRAWHITE="$BB_ENV_EXTRAWHITE CCACHE_DIR" | 1428 | export BB_ENV_PASSTHROUGH_ADDITIONS="$BB_ENV_PASSTHROUGH_ADDITIONS CCACHE_DIR" |
1351 | 1429 | ||
1352 | #. Tell BitBake to export what you have loaded into the datastore to the | 1430 | #. Tell BitBake to export what you have loaded into the datastore to the |
1353 | task environment of every running task. Loading something from the | 1431 | task environment of every running task. Loading something from the |
@@ -1355,7 +1433,7 @@ environment, you must take these two steps: | |||
1355 | available in the datastore. To export it to the task environment of | 1433 | available in the datastore. To export it to the task environment of |
1356 | every running task, use a command similar to the following in your | 1434 | every running task, use a command similar to the following in your |
1357 | local configuration file ``local.conf`` or your distribution | 1435 | local configuration file ``local.conf`` or your distribution |
1358 | configuration file: :: | 1436 | configuration file:: |
1359 | 1437 | ||
1360 | export CCACHE_DIR | 1438 | export CCACHE_DIR |
1361 | 1439 | ||
@@ -1364,17 +1442,17 @@ environment, you must take these two steps: | |||
1364 | A side effect of the previous steps is that BitBake records the | 1442 | A side effect of the previous steps is that BitBake records the |
1365 | variable as a dependency of the build process in things like the | 1443 | variable as a dependency of the build process in things like the |
1366 | setscene checksums. If doing so results in unnecessary rebuilds of | 1444 | setscene checksums. If doing so results in unnecessary rebuilds of |
1367 | tasks, you can whitelist the variable so that the setscene code | 1445 | tasks, you can also flag the variable so that the setscene code |
1368 | ignores the dependency when it creates checksums. | 1446 | ignores the dependency when it creates checksums. |
1369 | 1447 | ||
1370 | Sometimes, it is useful to be able to obtain information from the | 1448 | Sometimes, it is useful to be able to obtain information from the |
1371 | original execution environment. BitBake saves a copy of the original | 1449 | original execution environment. BitBake saves a copy of the original |
1372 | environment into a special variable named :term:`BB_ORIGENV`. | 1450 | environment into a special variable named :term:`BB_ORIGENV`. |
1373 | 1451 | ||
1374 | The ``BB_ORIGENV`` variable returns a datastore object that can be | 1452 | The :term:`BB_ORIGENV` variable returns a datastore object that can be |
1375 | queried using the standard datastore operators such as | 1453 | queried using the standard datastore operators such as |
1376 | ``getVar(, False)``. The datastore object is useful, for example, to | 1454 | ``getVar(, False)``. The datastore object is useful, for example, to |
1377 | find the original ``DISPLAY`` variable. Here is an example: :: | 1455 | find the original ``DISPLAY`` variable. Here is an example:: |
1378 | 1456 | ||
1379 | origenv = d.getVar("BB_ORIGENV", False) | 1457 | origenv = d.getVar("BB_ORIGENV", False) |
1380 | bar = origenv.getVar("BAR", False) | 1458 | bar = origenv.getVar("BAR", False) |
@@ -1387,7 +1465,7 @@ Variable Flags | |||
1387 | 1465 | ||
1388 | Variable flags (varflags) help control a task's functionality and | 1466 | Variable flags (varflags) help control a task's functionality and |
1389 | dependencies. BitBake reads and writes varflags to the datastore using | 1467 | dependencies. BitBake reads and writes varflags to the datastore using |
1390 | the following command forms: :: | 1468 | the following command forms:: |
1391 | 1469 | ||
1392 | variable = d.getVarFlags("variable") | 1470 | variable = d.getVarFlags("variable") |
1393 | self.d.setVarFlags("FOO", {"func": True}) | 1471 | self.d.setVarFlags("FOO", {"func": True}) |
@@ -1418,12 +1496,35 @@ functionality of the task: | |||
1418 | directory listed is used as the current working directory for the | 1496 | directory listed is used as the current working directory for the |
1419 | task. | 1497 | task. |
1420 | 1498 | ||
1499 | - ``[file-checksums]``: Controls the file dependencies for a task. The | ||
1500 | baseline file list is the set of files associated with | ||
1501 | :term:`SRC_URI`. May be used to set additional dependencies on | ||
1502 | files not associated with :term:`SRC_URI`. | ||
1503 | |||
1504 | The value set to the list is a file-boolean pair where the first | ||
1505 | value is the file name and the second is whether or not it | ||
1506 | physically exists on the filesystem. :: | ||
1507 | |||
1508 | do_configure[file-checksums] += "${MY_DIRPATH}/my-file.txt:True" | ||
1509 | |||
1510 | It is important to record any paths which the task looked at and | ||
1511 | which didn't exist. This means that if these do exist at a later | ||
1512 | time, the task can be rerun with the new additional files. The | ||
1513 | "exists" True or False value after the path allows this to be | ||
1514 | handled. | ||
1515 | |||
1421 | - ``[lockfiles]``: Specifies one or more lockfiles to lock while the | 1516 | - ``[lockfiles]``: Specifies one or more lockfiles to lock while the |
1422 | task executes. Only one task may hold a lockfile, and any task that | 1517 | task executes. Only one task may hold a lockfile, and any task that |
1423 | attempts to lock an already locked file will block until the lock is | 1518 | attempts to lock an already locked file will block until the lock is |
1424 | released. You can use this variable flag to accomplish mutual | 1519 | released. You can use this variable flag to accomplish mutual |
1425 | exclusion. | 1520 | exclusion. |
1426 | 1521 | ||
1522 | - ``[network]``: When set to "1", allows a task to access the network. By | ||
1523 | default, only the ``do_fetch`` task is granted network access. Recipes | ||
1524 | shouldn't access the network outside of ``do_fetch`` as it usually | ||
1525 | undermines fetcher source mirroring, image and licence manifests, software | ||
1526 | auditing and supply chain security. | ||
1527 | |||
1427 | - ``[noexec]``: When set to "1", marks the task as being empty, with | 1528 | - ``[noexec]``: When set to "1", marks the task as being empty, with |
1428 | no execution required. You can use the ``[noexec]`` flag to set up | 1529 | no execution required. You can use the ``[noexec]`` flag to set up |
1429 | tasks as dependency placeholders, or to disable tasks defined | 1530 | tasks as dependency placeholders, or to disable tasks defined |
@@ -1456,7 +1557,7 @@ functionality of the task: | |||
1456 | can result in unpredictable behavior. | 1557 | can result in unpredictable behavior. |
1457 | 1558 | ||
1458 | - Setting the varflag to a value greater than the value used in | 1559 | - Setting the varflag to a value greater than the value used in |
1459 | the ``BB_NUMBER_THREADS`` variable causes ``number_threads`` to | 1560 | the :term:`BB_NUMBER_THREADS` variable causes ``number_threads`` to |
1460 | have no effect. | 1561 | have no effect. |
1461 | 1562 | ||
1462 | - ``[postfuncs]``: List of functions to call after the completion of | 1563 | - ``[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 | |||
1526 | failures. | 1627 | failures. |
1527 | 1628 | ||
1528 | Following is an example event handler that prints the name of the event | 1629 | Following is an example event handler that prints the name of the event |
1529 | and the content of the ``FILE`` variable: :: | 1630 | and the content of the :term:`FILE` variable:: |
1530 | 1631 | ||
1531 | addhandler myclass_eventhandler | 1632 | addhandler myclass_eventhandler |
1532 | python myclass_eventhandler() { | 1633 | python myclass_eventhandler() { |
@@ -1565,11 +1666,11 @@ might have an interest in viewing: | |||
1565 | 1666 | ||
1566 | - ``bb.event.ConfigParsed()``: Fired when the base configuration; which | 1667 | - ``bb.event.ConfigParsed()``: Fired when the base configuration; which |
1567 | consists of ``bitbake.conf``, ``base.bbclass`` and any global | 1668 | consists of ``bitbake.conf``, ``base.bbclass`` and any global |
1568 | ``INHERIT`` statements; has been parsed. You can see multiple such | 1669 | :term:`INHERIT` statements; has been parsed. You can see multiple such |
1569 | events when each of the workers parse the base configuration or if | 1670 | events when each of the workers parse the base configuration or if |
1570 | the server changes configuration and reparses. Any given datastore | 1671 | the server changes configuration and reparses. Any given datastore |
1571 | only has one such event executed against it, however. If | 1672 | only has one such event executed against it, however. If |
1572 | ```BB_INVALIDCONF`` <#>`__ is set in the datastore by the event | 1673 | :term:`BB_INVALIDCONF` is set in the datastore by the event |
1573 | handler, the configuration is reparsed and a new event triggered, | 1674 | handler, the configuration is reparsed and a new event triggered, |
1574 | allowing the metadata to update configuration. | 1675 | allowing the metadata to update configuration. |
1575 | 1676 | ||
@@ -1636,13 +1737,18 @@ user interfaces: | |||
1636 | 1737 | ||
1637 | .. _variants-class-extension-mechanism: | 1738 | .. _variants-class-extension-mechanism: |
1638 | 1739 | ||
1639 | Variants - Class Extension Mechanism | 1740 | Variants --- Class Extension Mechanism |
1640 | ==================================== | 1741 | ====================================== |
1641 | 1742 | ||
1642 | BitBake supports two features that facilitate creating from a single | 1743 | BitBake supports multiple incarnations of a recipe file via the |
1643 | recipe file multiple incarnations of that recipe file where all | 1744 | :term:`BBCLASSEXTEND` variable. |
1644 | incarnations are buildable. These features are enabled through the | 1745 | |
1645 | :term:`BBCLASSEXTEND` and :term:`BBVERSIONS` variables. | 1746 | The :term:`BBCLASSEXTEND` variable is a space separated list of classes used |
1747 | to "extend" the recipe for each variant. Here is an example that results in a | ||
1748 | second incarnation of the current recipe being available. This second | ||
1749 | incarnation will have the "native" class inherited. :: | ||
1750 | |||
1751 | BBCLASSEXTEND = "native" | ||
1646 | 1752 | ||
1647 | .. note:: | 1753 | .. note:: |
1648 | 1754 | ||
@@ -1652,34 +1758,6 @@ incarnations are buildable. These features are enabled through the | |||
1652 | class. For specific examples, see the OE-Core native , nativesdk , and | 1758 | class. For specific examples, see the OE-Core native , nativesdk , and |
1653 | multilib classes. | 1759 | multilib classes. |
1654 | 1760 | ||
1655 | - ``BBCLASSEXTEND``: This variable is a space separated list of | ||
1656 | classes used to "extend" the recipe for each variant. Here is an | ||
1657 | example that results in a second incarnation of the current recipe | ||
1658 | being available. This second incarnation will have the "native" class | ||
1659 | inherited. :: | ||
1660 | |||
1661 | BBCLASSEXTEND = "native" | ||
1662 | |||
1663 | - ``BBVERSIONS``: This variable allows a single recipe to build | ||
1664 | multiple versions of a project from a single recipe file. You can | ||
1665 | also specify conditional metadata (using the | ||
1666 | :term:`OVERRIDES` mechanism) for a single | ||
1667 | version, or an optionally named range of versions. Here is an | ||
1668 | example: :: | ||
1669 | |||
1670 | BBVERSIONS = "1.0 2.0 git" | ||
1671 | SRC_URI_git = "git://someurl/somepath.git" | ||
1672 | |||
1673 | BBVERSIONS = "1.0.[0-6]:1.0.0+ 1.0.[7-9]:1.0.7+" | ||
1674 | SRC_URI_append_1.0.7+ = "file://some_patch_which_the_new_versions_need.patch;patch=1" | ||
1675 | |||
1676 | The name of the range defaults to the original version of the recipe. For | ||
1677 | example, in OpenEmbedded, the recipe file ``foo_1.0.0+.bb`` creates a default | ||
1678 | name range of ``1.0.0+``. This is useful because the range name is not only | ||
1679 | placed into overrides, but it is also made available for the metadata to use | ||
1680 | in the variable that defines the base recipe versions for use in ``file://`` | ||
1681 | search paths (:term:`FILESPATH`). | ||
1682 | |||
1683 | Dependencies | 1761 | Dependencies |
1684 | ============ | 1762 | ============ |
1685 | 1763 | ||
@@ -1708,7 +1786,7 @@ Dependencies Internal to the ``.bb`` File | |||
1708 | BitBake uses the ``addtask`` directive to manage dependencies that are | 1786 | BitBake uses the ``addtask`` directive to manage dependencies that are |
1709 | internal to a given recipe file. You can use the ``addtask`` directive | 1787 | internal to a given recipe file. You can use the ``addtask`` directive |
1710 | to indicate when a task is dependent on other tasks or when other tasks | 1788 | to indicate when a task is dependent on other tasks or when other tasks |
1711 | depend on that recipe. Here is an example: :: | 1789 | depend on that recipe. Here is an example:: |
1712 | 1790 | ||
1713 | addtask printdate after do_fetch before do_build | 1791 | addtask printdate after do_fetch before do_build |
1714 | 1792 | ||
@@ -1732,7 +1810,7 @@ task depends on the completion of the ``do_printdate`` task. | |||
1732 | 1810 | ||
1733 | - The directive ``addtask mytask after do_configure`` by itself | 1811 | - The directive ``addtask mytask after do_configure`` by itself |
1734 | never causes ``do_mytask`` to run. ``do_mytask`` can still be run | 1812 | never causes ``do_mytask`` to run. ``do_mytask`` can still be run |
1735 | manually as follows: :: | 1813 | manually as follows:: |
1736 | 1814 | ||
1737 | $ bitbake recipe -c mytask | 1815 | $ bitbake recipe -c mytask |
1738 | 1816 | ||
@@ -1745,13 +1823,13 @@ Build Dependencies | |||
1745 | 1823 | ||
1746 | BitBake uses the :term:`DEPENDS` variable to manage | 1824 | BitBake uses the :term:`DEPENDS` variable to manage |
1747 | build time dependencies. The ``[deptask]`` varflag for tasks signifies | 1825 | build time dependencies. The ``[deptask]`` varflag for tasks signifies |
1748 | the task of each item listed in ``DEPENDS`` that must complete before | 1826 | the task of each item listed in :term:`DEPENDS` that must complete before |
1749 | that task can be executed. Here is an example: :: | 1827 | that task can be executed. Here is an example:: |
1750 | 1828 | ||
1751 | do_configure[deptask] = "do_populate_sysroot" | 1829 | do_configure[deptask] = "do_populate_sysroot" |
1752 | 1830 | ||
1753 | In this example, the ``do_populate_sysroot`` task | 1831 | In this example, the ``do_populate_sysroot`` task |
1754 | of each item in ``DEPENDS`` must complete before ``do_configure`` can | 1832 | of each item in :term:`DEPENDS` must complete before ``do_configure`` can |
1755 | execute. | 1833 | execute. |
1756 | 1834 | ||
1757 | Runtime Dependencies | 1835 | Runtime Dependencies |
@@ -1760,8 +1838,8 @@ Runtime Dependencies | |||
1760 | BitBake uses the :term:`PACKAGES`, :term:`RDEPENDS`, and :term:`RRECOMMENDS` | 1838 | BitBake uses the :term:`PACKAGES`, :term:`RDEPENDS`, and :term:`RRECOMMENDS` |
1761 | variables to manage runtime dependencies. | 1839 | variables to manage runtime dependencies. |
1762 | 1840 | ||
1763 | The ``PACKAGES`` variable lists runtime packages. Each of those packages | 1841 | The :term:`PACKAGES` variable lists runtime packages. Each of those packages |
1764 | can have ``RDEPENDS`` and ``RRECOMMENDS`` runtime dependencies. The | 1842 | can have :term:`RDEPENDS` and :term:`RRECOMMENDS` runtime dependencies. The |
1765 | ``[rdeptask]`` flag for tasks is used to signify the task of each item | 1843 | ``[rdeptask]`` flag for tasks is used to signify the task of each item |
1766 | runtime dependency which must have completed before that task can be | 1844 | runtime dependency which must have completed before that task can be |
1767 | executed. :: | 1845 | executed. :: |
@@ -1769,9 +1847,9 @@ executed. :: | |||
1769 | do_package_qa[rdeptask] = "do_packagedata" | 1847 | do_package_qa[rdeptask] = "do_packagedata" |
1770 | 1848 | ||
1771 | In the previous | 1849 | In the previous |
1772 | example, the ``do_packagedata`` task of each item in ``RDEPENDS`` must | 1850 | example, the ``do_packagedata`` task of each item in :term:`RDEPENDS` must |
1773 | have completed before ``do_package_qa`` can execute. | 1851 | have completed before ``do_package_qa`` can execute. |
1774 | Although ``RDEPENDS`` contains entries from the | 1852 | Although :term:`RDEPENDS` contains entries from the |
1775 | runtime dependency namespace, BitBake knows how to map them back | 1853 | runtime dependency namespace, BitBake knows how to map them back |
1776 | to the build-time dependency namespace, in which the tasks are defined. | 1854 | to the build-time dependency namespace, in which the tasks are defined. |
1777 | 1855 | ||
@@ -1788,7 +1866,7 @@ dependencies are discovered and added. | |||
1788 | 1866 | ||
1789 | The ``[recrdeptask]`` flag is most commonly used in high-level recipes | 1867 | The ``[recrdeptask]`` flag is most commonly used in high-level recipes |
1790 | that need to wait for some task to finish "globally". For example, | 1868 | that need to wait for some task to finish "globally". For example, |
1791 | ``image.bbclass`` has the following: :: | 1869 | ``image.bbclass`` has the following:: |
1792 | 1870 | ||
1793 | do_rootfs[recrdeptask] += "do_packagedata" | 1871 | do_rootfs[recrdeptask] += "do_packagedata" |
1794 | 1872 | ||
@@ -1797,7 +1875,7 @@ the current recipe and all recipes reachable (by way of dependencies) | |||
1797 | from the image recipe must run before the ``do_rootfs`` task can run. | 1875 | from the image recipe must run before the ``do_rootfs`` task can run. |
1798 | 1876 | ||
1799 | BitBake allows a task to recursively depend on itself by | 1877 | BitBake allows a task to recursively depend on itself by |
1800 | referencing itself in the task list: :: | 1878 | referencing itself in the task list:: |
1801 | 1879 | ||
1802 | do_a[recrdeptask] = "do_a do_b" | 1880 | do_a[recrdeptask] = "do_a do_b" |
1803 | 1881 | ||
@@ -1814,7 +1892,7 @@ Inter-Task Dependencies | |||
1814 | BitBake uses the ``[depends]`` flag in a more generic form to manage | 1892 | BitBake uses the ``[depends]`` flag in a more generic form to manage |
1815 | inter-task dependencies. This more generic form allows for | 1893 | inter-task dependencies. This more generic form allows for |
1816 | inter-dependency checks for specific tasks rather than checks for the | 1894 | inter-dependency checks for specific tasks rather than checks for the |
1817 | data in ``DEPENDS``. Here is an example: :: | 1895 | data in :term:`DEPENDS`. Here is an example:: |
1818 | 1896 | ||
1819 | do_patch[depends] = "quilt-native:do_populate_sysroot" | 1897 | do_patch[depends] = "quilt-native:do_populate_sysroot" |
1820 | 1898 | ||
@@ -1900,6 +1978,33 @@ looking at the source code of the ``bb`` module, which is in | |||
1900 | the commonly used functions ``bb.utils.contains()`` and | 1978 | the commonly used functions ``bb.utils.contains()`` and |
1901 | ``bb.utils.mkdirhier()``, which come with docstrings. | 1979 | ``bb.utils.mkdirhier()``, which come with docstrings. |
1902 | 1980 | ||
1981 | Extending Python Library Code | ||
1982 | ----------------------------- | ||
1983 | |||
1984 | If you wish to add your own Python library code (e.g. to provide | ||
1985 | functions/classes you can use from Python functions in the metadata) | ||
1986 | you can do so from any layer using the ``addpylib`` directive. | ||
1987 | This directive is typically added to your layer configuration ( | ||
1988 | ``conf/layer.conf``) although it will be handled in any ``.conf`` file. | ||
1989 | |||
1990 | Usage is of the form:: | ||
1991 | |||
1992 | addpylib <directory> <namespace> | ||
1993 | |||
1994 | Where <directory> specifies the directory to add to the library path. | ||
1995 | The specified <namespace> is imported automatically, and if the imported | ||
1996 | module specifies an attribute named ``BBIMPORTS``, that list of | ||
1997 | sub-modules is iterated and imported too. | ||
1998 | |||
1999 | Testing and Debugging BitBake Python code | ||
2000 | ----------------------------------------- | ||
2001 | |||
2002 | The OpenEmbedded build system implements a convenient ``pydevshell`` target which | ||
2003 | you can use to access the BitBake datastore and experiment with your own Python | ||
2004 | code. See :yocto_docs:`Using a Python Development Shell | ||
2005 | </dev-manual/python-development-shell.html#using-a-python-development-shell>` in the Yocto | ||
2006 | Project manual for details. | ||
2007 | |||
1903 | Task Checksums and Setscene | 2008 | Task Checksums and Setscene |
1904 | =========================== | 2009 | =========================== |
1905 | 2010 | ||
@@ -1909,7 +2014,7 @@ To help understand how BitBake does this, the section assumes an | |||
1909 | OpenEmbedded metadata-based example. | 2014 | OpenEmbedded metadata-based example. |
1910 | 2015 | ||
1911 | These checksums are stored in :term:`STAMP`. You can | 2016 | These checksums are stored in :term:`STAMP`. You can |
1912 | examine the checksums using the following BitBake command: :: | 2017 | examine the checksums using the following BitBake command:: |
1913 | 2018 | ||
1914 | $ bitbake-dumpsigs | 2019 | $ bitbake-dumpsigs |
1915 | 2020 | ||
@@ -1932,16 +2037,6 @@ The following list describes related variables: | |||
1932 | Specifies a function BitBake calls that determines whether BitBake | 2037 | Specifies a function BitBake calls that determines whether BitBake |
1933 | requires a setscene dependency to be met. | 2038 | requires a setscene dependency to be met. |
1934 | 2039 | ||
1935 | - :term:`BB_SETSCENE_VERIFY_FUNCTION2`: | ||
1936 | Specifies a function to call that verifies the list of planned task | ||
1937 | execution before the main task execution happens. | ||
1938 | |||
1939 | - :term:`BB_STAMP_POLICY`: Defines the mode | ||
1940 | for comparing timestamps of stamp files. | ||
1941 | |||
1942 | - :term:`BB_STAMP_WHITELIST`: Lists stamp | ||
1943 | files that are looked at when the stamp policy is "whitelist". | ||
1944 | |||
1945 | - :term:`BB_TASKHASH`: Within an executing task, | 2040 | - :term:`BB_TASKHASH`: Within an executing task, |
1946 | this variable holds the hash of the task as returned by the currently | 2041 | this variable holds the hash of the task as returned by the currently |
1947 | enabled signature generator. | 2042 | enabled signature generator. |
@@ -1956,7 +2051,7 @@ Wildcard Support in Variables | |||
1956 | ============================= | 2051 | ============================= |
1957 | 2052 | ||
1958 | Support for wildcard use in variables varies depending on the context in | 2053 | Support for wildcard use in variables varies depending on the context in |
1959 | which it is used. For example, some variables and file names allow | 2054 | which it is used. For example, some variables and filenames allow |
1960 | limited use of wildcards through the "``%``" and "``*``" characters. | 2055 | limited use of wildcards through the "``%``" and "``*``" characters. |
1961 | Other variables or names support Python's | 2056 | Other variables or names support Python's |
1962 | `glob <https://docs.python.org/3/library/glob.html>`_ syntax, | 2057 | `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 @@ | |||
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``. | ||
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 6469f9d1a4..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. | |||
23 | systems extend the functionality of the variable as it is | 23 | systems extend the functionality of the variable as it is |
24 | described here in this glossary. | 24 | described here in this glossary. |
25 | 25 | ||
26 | - Finally, there are variables mentioned in this glossary that do | ||
27 | not appear in the BitBake glossary. These other variables are | ||
28 | variables used in systems that use BitBake. | ||
29 | |||
30 | .. glossary:: | 26 | .. glossary:: |
27 | :sorted: | ||
31 | 28 | ||
32 | :term:`ASSUME_PROVIDED` | 29 | :term:`ASSUME_PROVIDED` |
33 | Lists recipe names (:term:`PN` values) BitBake does not | 30 | Lists recipe names (:term:`PN` values) BitBake does not |
34 | attempt to build. Instead, BitBake assumes these recipes have already | 31 | attempt to build. Instead, BitBake assumes these recipes have already |
35 | been built. | 32 | been built. |
36 | 33 | ||
37 | In OpenEmbedded-Core, ``ASSUME_PROVIDED`` mostly specifies native | 34 | In OpenEmbedded-Core, :term:`ASSUME_PROVIDED` mostly specifies native |
38 | tools that should not be built. An example is ``git-native``, which | 35 | tools that should not be built. An example is ``git-native``, which |
39 | when specified allows for the Git binary from the host to be used | 36 | when specified allows for the Git binary from the host to be used |
40 | rather than building ``git-native``. | 37 | rather than building ``git-native``. |
41 | 38 | ||
39 | :term:`AZ_SAS` | ||
40 | Azure Storage Shared Access Signature, when using the | ||
41 | :ref:`Azure Storage fetcher <bitbake-user-manual/bitbake-user-manual-fetching:fetchers>` | ||
42 | This variable can be defined to be used by the fetcher to authenticate | ||
43 | and gain access to non-public artifacts:: | ||
44 | |||
45 | AZ_SAS = ""se=2021-01-01&sp=r&sv=2018-11-09&sr=c&skoid=<skoid>&sig=<signature>"" | ||
46 | |||
47 | For more information see Microsoft's Azure Storage documentation at | ||
48 | https://docs.microsoft.com/en-us/azure/storage/common/storage-sas-overview | ||
49 | |||
50 | |||
42 | :term:`B` | 51 | :term:`B` |
43 | The directory in which BitBake executes functions during a recipe's | 52 | The directory in which BitBake executes functions during a recipe's |
44 | build process. | 53 | build process. |
@@ -74,14 +83,41 @@ overview of their function and contents. | |||
74 | 83 | ||
75 | - Attempts to access networks not in the host list cause a failure. | 84 | - Attempts to access networks not in the host list cause a failure. |
76 | 85 | ||
77 | Using ``BB_ALLOWED_NETWORKS`` in conjunction with | 86 | Using :term:`BB_ALLOWED_NETWORKS` in conjunction with |
78 | :term:`PREMIRRORS` is very useful. Adding the | 87 | :term:`PREMIRRORS` is very useful. Adding the |
79 | host you want to use to ``PREMIRRORS`` results in the source code | 88 | host you want to use to :term:`PREMIRRORS` results in the source code |
80 | being fetched from an allowed location and avoids raising an error | 89 | being fetched from an allowed location and avoids raising an error |
81 | when a host that is not allowed is in a | 90 | when a host that is not allowed is in a |
82 | :term:`SRC_URI` statement. This is because the | 91 | :term:`SRC_URI` statement. This is because the |
83 | fetcher does not attempt to use the host listed in ``SRC_URI`` after | 92 | fetcher does not attempt to use the host listed in :term:`SRC_URI` after |
84 | a successful fetch from the ``PREMIRRORS`` occurs. | 93 | a successful fetch from the :term:`PREMIRRORS` occurs. |
94 | |||
95 | :term:`BB_BASEHASH_IGNORE_VARS` | ||
96 | Lists variables that are excluded from checksum and dependency data. | ||
97 | Variables that are excluded can therefore change without affecting | ||
98 | the checksum mechanism. A common example would be the variable for | ||
99 | the path of the build. BitBake's output should not (and usually does | ||
100 | not) depend on the directory in which it was built. | ||
101 | |||
102 | :term:`BB_CACHEDIR` | ||
103 | Specifies the code parser cache directory (distinct from :term:`CACHE` | ||
104 | and :term:`PERSISTENT_DIR` although they can be set to the same value | ||
105 | if desired). The default value is "${TOPDIR}/cache". | ||
106 | |||
107 | :term:`BB_CHECK_SSL_CERTS` | ||
108 | Specifies if SSL certificates should be checked when fetching. The default | ||
109 | value is ``1`` and certificates are not checked if the value is set to ``0``. | ||
110 | |||
111 | :term:`BB_HASH_CODEPARSER_VALS` | ||
112 | Specifies values for variables to use when populating the codeparser cache. | ||
113 | This can be used selectively to set dummy values for variables to avoid | ||
114 | the codeparser cache growing on every parse. Variables that would typically | ||
115 | be included are those where the value is not significant for where the | ||
116 | codeparser cache is used (i.e. when calculating variable dependencies for | ||
117 | code fragments.) The value is space-separated without quoting values, for | ||
118 | example:: | ||
119 | |||
120 | BB_HASH_CODEPARSER_VALS = "T=/ WORKDIR=/ DATE=1234 TIME=1234" | ||
85 | 121 | ||
86 | :term:`BB_CONSOLELOG` | 122 | :term:`BB_CONSOLELOG` |
87 | Specifies the path to a log file into which BitBake's user interface | 123 | Specifies the path to a log file into which BitBake's user interface |
@@ -117,14 +153,14 @@ overview of their function and contents. | |||
117 | you to control the build based on these parameters. | 153 | you to control the build based on these parameters. |
118 | 154 | ||
119 | Disk space monitoring is disabled by default. When setting this | 155 | Disk space monitoring is disabled by default. When setting this |
120 | variable, use the following form: :: | 156 | variable, use the following form:: |
121 | 157 | ||
122 | BB_DISKMON_DIRS = "<action>,<dir>,<threshold> [...]" | 158 | BB_DISKMON_DIRS = "<action>,<dir>,<threshold> [...]" |
123 | 159 | ||
124 | where: | 160 | where: |
125 | 161 | ||
126 | <action> is: | 162 | <action> is: |
127 | ABORT: Immediately abort the build when | 163 | HALT: Immediately halt the build when |
128 | a threshold is broken. | 164 | a threshold is broken. |
129 | STOPTASKS: Stop the build after the currently | 165 | STOPTASKS: Stop the build after the currently |
130 | executing tasks have finished when | 166 | executing tasks have finished when |
@@ -153,48 +189,48 @@ overview of their function and contents. | |||
153 | not specify G, M, or K, Kbytes is assumed by | 189 | not specify G, M, or K, Kbytes is assumed by |
154 | default. Do not use GB, MB, or KB. | 190 | default. Do not use GB, MB, or KB. |
155 | 191 | ||
156 | Here are some examples: :: | 192 | Here are some examples:: |
157 | 193 | ||
158 | BB_DISKMON_DIRS = "ABORT,${TMPDIR},1G,100K WARN,${SSTATE_DIR},1G,100K" | 194 | BB_DISKMON_DIRS = "HALT,${TMPDIR},1G,100K WARN,${SSTATE_DIR},1G,100K" |
159 | BB_DISKMON_DIRS = "STOPTASKS,${TMPDIR},1G" | 195 | BB_DISKMON_DIRS = "STOPTASKS,${TMPDIR},1G" |
160 | BB_DISKMON_DIRS = "ABORT,${TMPDIR},,100K" | 196 | BB_DISKMON_DIRS = "HALT,${TMPDIR},,100K" |
161 | 197 | ||
162 | The first example works only if you also set the | 198 | The first example works only if you also set the |
163 | :term:`BB_DISKMON_WARNINTERVAL` | 199 | :term:`BB_DISKMON_WARNINTERVAL` |
164 | variable. This example causes the build system to immediately abort | 200 | variable. This example causes the build system to immediately halt |
165 | when either the disk space in ``${TMPDIR}`` drops below 1 Gbyte or | 201 | when either the disk space in ``${TMPDIR}`` drops below 1 Gbyte or |
166 | the available free inodes drops below 100 Kbytes. Because two | 202 | the available free inodes drops below 100 Kbytes. Because two |
167 | directories are provided with the variable, the build system also | 203 | directories are provided with the variable, the build system also |
168 | issues a warning when the disk space in the ``${SSTATE_DIR}`` | 204 | issues a warning when the disk space in the ``${SSTATE_DIR}`` |
169 | directory drops below 1 Gbyte or the number of free inodes drops | 205 | directory drops below 1 Gbyte or the number of free inodes drops |
170 | below 100 Kbytes. Subsequent warnings are issued during intervals as | 206 | below 100 Kbytes. Subsequent warnings are issued during intervals as |
171 | defined by the ``BB_DISKMON_WARNINTERVAL`` variable. | 207 | defined by the :term:`BB_DISKMON_WARNINTERVAL` variable. |
172 | 208 | ||
173 | The second example stops the build after all currently executing | 209 | The second example stops the build after all currently executing |
174 | tasks complete when the minimum disk space in the ``${TMPDIR}`` | 210 | tasks complete when the minimum disk space in the ``${TMPDIR}`` |
175 | directory drops below 1 Gbyte. No disk monitoring occurs for the free | 211 | directory drops below 1 Gbyte. No disk monitoring occurs for the free |
176 | inodes in this case. | 212 | inodes in this case. |
177 | 213 | ||
178 | The final example immediately aborts the build when the number of | 214 | The final example immediately halts the build when the number of |
179 | free inodes in the ``${TMPDIR}`` directory drops below 100 Kbytes. No | 215 | free inodes in the ``${TMPDIR}`` directory drops below 100 Kbytes. No |
180 | disk space monitoring for the directory itself occurs in this case. | 216 | disk space monitoring for the directory itself occurs in this case. |
181 | 217 | ||
182 | :term:`BB_DISKMON_WARNINTERVAL` | 218 | :term:`BB_DISKMON_WARNINTERVAL` |
183 | Defines the disk space and free inode warning intervals. | 219 | Defines the disk space and free inode warning intervals. |
184 | 220 | ||
185 | If you are going to use the ``BB_DISKMON_WARNINTERVAL`` variable, you | 221 | If you are going to use the :term:`BB_DISKMON_WARNINTERVAL` variable, you |
186 | must also use the :term:`BB_DISKMON_DIRS` | 222 | must also use the :term:`BB_DISKMON_DIRS` |
187 | variable and define its action as "WARN". During the build, | 223 | variable and define its action as "WARN". During the build, |
188 | subsequent warnings are issued each time disk space or number of free | 224 | subsequent warnings are issued each time disk space or number of free |
189 | inodes further reduces by the respective interval. | 225 | inodes further reduces by the respective interval. |
190 | 226 | ||
191 | If you do not provide a ``BB_DISKMON_WARNINTERVAL`` variable and you | 227 | If you do not provide a :term:`BB_DISKMON_WARNINTERVAL` variable and you |
192 | do use ``BB_DISKMON_DIRS`` with the "WARN" action, the disk | 228 | do use :term:`BB_DISKMON_DIRS` with the "WARN" action, the disk |
193 | monitoring interval defaults to the following: | 229 | monitoring interval defaults to the following: |
194 | BB_DISKMON_WARNINTERVAL = "50M,5K" | 230 | BB_DISKMON_WARNINTERVAL = "50M,5K" |
195 | 231 | ||
196 | When specifying the variable in your configuration file, use the | 232 | When specifying the variable in your configuration file, use the |
197 | following form: :: | 233 | following form:: |
198 | 234 | ||
199 | BB_DISKMON_WARNINTERVAL = "<disk_space_interval>,<disk_inode_interval>" | 235 | BB_DISKMON_WARNINTERVAL = "<disk_space_interval>,<disk_inode_interval>" |
200 | 236 | ||
@@ -210,7 +246,7 @@ overview of their function and contents. | |||
210 | G, M, or K for Gbytes, Mbytes, or Kbytes, | 246 | G, M, or K for Gbytes, Mbytes, or Kbytes, |
211 | respectively. You cannot use GB, MB, or KB. | 247 | respectively. You cannot use GB, MB, or KB. |
212 | 248 | ||
213 | Here is an example: :: | 249 | Here is an example:: |
214 | 250 | ||
215 | BB_DISKMON_DIRS = "WARN,${SSTATE_DIR},1G,100K" | 251 | BB_DISKMON_DIRS = "WARN,${SSTATE_DIR},1G,100K" |
216 | BB_DISKMON_WARNINTERVAL = "50M,5K" | 252 | BB_DISKMON_WARNINTERVAL = "50M,5K" |
@@ -222,23 +258,23 @@ overview of their function and contents. | |||
222 | based on the interval occur each time a respective interval is | 258 | based on the interval occur each time a respective interval is |
223 | reached beyond the initial warning (i.e. 1 Gbytes and 100 Kbytes). | 259 | reached beyond the initial warning (i.e. 1 Gbytes and 100 Kbytes). |
224 | 260 | ||
225 | :term:`BB_ENV_WHITELIST` | 261 | :term:`BB_ENV_PASSTHROUGH` |
226 | Specifies the internal whitelist of variables to allow through from | 262 | Specifies the internal list of variables to allow through from |
227 | the external environment into BitBake's datastore. If the value of | 263 | the external environment into BitBake's datastore. If the value of |
228 | this variable is not specified (which is the default), the following | 264 | this variable is not specified (which is the default), the following |
229 | list is used: :term:`BBPATH`, :term:`BB_PRESERVE_ENV`, | 265 | list is used: :term:`BBPATH`, :term:`BB_PRESERVE_ENV`, |
230 | :term:`BB_ENV_WHITELIST`, and :term:`BB_ENV_EXTRAWHITE`. | 266 | :term:`BB_ENV_PASSTHROUGH`, and :term:`BB_ENV_PASSTHROUGH_ADDITIONS`. |
231 | 267 | ||
232 | .. note:: | 268 | .. note:: |
233 | 269 | ||
234 | You must set this variable in the external environment in order | 270 | You must set this variable in the external environment in order |
235 | for it to work. | 271 | for it to work. |
236 | 272 | ||
237 | :term:`BB_ENV_EXTRAWHITE` | 273 | :term:`BB_ENV_PASSTHROUGH_ADDITIONS` |
238 | Specifies an additional set of variables to allow through (whitelist) | 274 | Specifies an additional set of variables to allow through from the |
239 | from the external environment into BitBake's datastore. This list of | 275 | external environment into BitBake's datastore. This list of variables |
240 | variables are on top of the internal list set in | 276 | are on top of the internal list set in |
241 | :term:`BB_ENV_WHITELIST`. | 277 | :term:`BB_ENV_PASSTHROUGH`. |
242 | 278 | ||
243 | .. note:: | 279 | .. note:: |
244 | 280 | ||
@@ -254,76 +290,82 @@ overview of their function and contents. | |||
254 | :term:`BB_FILENAME` | 290 | :term:`BB_FILENAME` |
255 | Contains the filename of the recipe that owns the currently running | 291 | Contains the filename of the recipe that owns the currently running |
256 | task. For example, if the ``do_fetch`` task that resides in the | 292 | task. For example, if the ``do_fetch`` task that resides in the |
257 | ``my-recipe.bb`` is executing, the ``BB_FILENAME`` variable contains | 293 | ``my-recipe.bb`` is executing, the :term:`BB_FILENAME` variable contains |
258 | "/foo/path/my-recipe.bb". | 294 | "/foo/path/my-recipe.bb". |
259 | 295 | ||
260 | :term:`BBFILES_DYNAMIC` | 296 | :term:`BB_GENERATE_MIRROR_TARBALLS` |
261 | Activates content depending on presence of identified layers. You | 297 | Causes tarballs of the Git repositories, including the Git metadata, |
262 | identify the layers by the collections that the layers define. | 298 | to be placed in the :term:`DL_DIR` directory. Anyone |
299 | wishing to create a source mirror would want to enable this variable. | ||
263 | 300 | ||
264 | Use the ``BBFILES_DYNAMIC`` variable to avoid ``.bbappend`` files whose | 301 | For performance reasons, creating and placing tarballs of the Git |
265 | corresponding ``.bb`` file is in a layer that attempts to modify other | 302 | repositories is not the default action by BitBake. :: |
266 | layers through ``.bbappend`` but does not want to introduce a hard | ||
267 | dependency on those other layers. | ||
268 | 303 | ||
269 | Additionally you can prefix the rule with "!" to add ``.bbappend`` and | 304 | BB_GENERATE_MIRROR_TARBALLS = "1" |
270 | ``.bb`` files in case a layer is not present. Use this avoid hard | ||
271 | dependency on those other layers. | ||
272 | 305 | ||
273 | Use the following form for ``BBFILES_DYNAMIC``: :: | 306 | :term:`BB_GENERATE_SHALLOW_TARBALLS` |
307 | Setting this variable to "1" when :term:`BB_GIT_SHALLOW` is also set to | ||
308 | "1" causes bitbake to generate shallow mirror tarballs when fetching git | ||
309 | repositories. The number of commits included in the shallow mirror | ||
310 | tarballs is controlled by :term:`BB_GIT_SHALLOW_DEPTH`. | ||
274 | 311 | ||
275 | collection_name:filename_pattern | 312 | If both :term:`BB_GIT_SHALLOW` and :term:`BB_GENERATE_MIRROR_TARBALLS` are |
313 | enabled, bitbake will generate shallow mirror tarballs by default for git | ||
314 | repositories. This separate variable exists so that shallow tarball | ||
315 | generation can be enabled without needing to also enable normal mirror | ||
316 | generation if it is not desired. | ||
276 | 317 | ||
277 | The following example identifies two collection names and two filename | 318 | For example usage, see :term:`BB_GIT_SHALLOW`. |
278 | patterns: :: | ||
279 | 319 | ||
280 | BBFILES_DYNAMIC += "\ | 320 | :term:`BB_GIT_SHALLOW` |
281 | clang-layer:${LAYERDIR}/bbappends/meta-clang/*/*/*.bbappend \ | 321 | Setting this variable to "1" enables the support for fetching, using and |
282 | core:${LAYERDIR}/bbappends/openembedded-core/meta/*/*/*.bbappend \ | 322 | generating mirror tarballs of `shallow git repositories <https://riptutorial.com/git/example/4584/shallow-clone>`_. |
283 | " | 323 | The external `git-make-shallow <https://git.openembedded.org/bitbake/tree/bin/git-make-shallow>`_ |
324 | script is used for shallow mirror tarball creation. | ||
284 | 325 | ||
285 | When the collection name is prefixed with "!" it will add the file pattern in case | 326 | When :term:`BB_GIT_SHALLOW` is enabled, bitbake will attempt to fetch a shallow |
286 | the layer is absent: :: | 327 | mirror tarball. If the shallow mirror tarball cannot be fetched, it will |
328 | try to fetch the full mirror tarball and use that. | ||
287 | 329 | ||
288 | BBFILES_DYNAMIC += "\ | 330 | When a mirror tarball is not available, a full git clone will be performed |
289 | !clang-layer:${LAYERDIR}/backfill/meta-clang/*/*/*.bb \ | 331 | regardless of whether this variable is set or not. Support for shallow |
290 | " | 332 | clones is not currently implemented as git does not directly support |
333 | shallow cloning a particular git commit hash (it only supports cloning | ||
334 | from a tag or branch reference). | ||
291 | 335 | ||
292 | This next example shows an error message that occurs because invalid | 336 | See also :term:`BB_GIT_SHALLOW_DEPTH` and |
293 | entries are found, which cause parsing to abort: :: | 337 | :term:`BB_GENERATE_SHALLOW_TARBALLS`. |
294 | 338 | ||
295 | ERROR: BBFILES_DYNAMIC entries must be of the form {!}<collection name>:<filename pattern>, not: | 339 | Example usage:: |
296 | /work/my-layer/bbappends/meta-security-isafw/*/*/*.bbappend | ||
297 | /work/my-layer/bbappends/openembedded-core/meta/*/*/*.bbappend | ||
298 | 340 | ||
299 | :term:`BB_GENERATE_MIRROR_TARBALLS` | 341 | BB_GIT_SHALLOW ?= "1" |
300 | Causes tarballs of the Git repositories, including the Git metadata, | ||
301 | to be placed in the :term:`DL_DIR` directory. Anyone | ||
302 | wishing to create a source mirror would want to enable this variable. | ||
303 | 342 | ||
304 | For performance reasons, creating and placing tarballs of the Git | 343 | # Keep only the top commit |
305 | repositories is not the default action by BitBake. :: | 344 | BB_GIT_SHALLOW_DEPTH ?= "1" |
306 | 345 | ||
307 | BB_GENERATE_MIRROR_TARBALLS = "1" | 346 | # This defaults to enabled if both BB_GIT_SHALLOW and |
347 | # BB_GENERATE_MIRROR_TARBALLS are enabled | ||
348 | BB_GENERATE_SHALLOW_TARBALLS ?= "1" | ||
308 | 349 | ||
309 | :term:`BB_HASHCONFIG_WHITELIST` | 350 | :term:`BB_GIT_SHALLOW_DEPTH` |
310 | Lists variables that are excluded from base configuration checksum, | 351 | When used with :term:`BB_GENERATE_SHALLOW_TARBALLS`, this variable sets |
311 | which is used to determine if the cache can be reused. | 352 | the number of commits to include in generated shallow mirror tarballs. |
353 | With a depth of 1, only the commit referenced in :term:`SRCREV` is | ||
354 | included in the shallow mirror tarball. Increasing the depth includes | ||
355 | additional parent commits, working back through the commit history. | ||
312 | 356 | ||
313 | One of the ways BitBake determines whether to re-parse the main | 357 | If this variable is unset, bitbake will default to a depth of 1 when |
314 | metadata is through checksums of the variables in the datastore of | 358 | generating shallow mirror tarballs. |
315 | the base configuration data. There are variables that you typically | ||
316 | want to exclude when checking whether or not to re-parse and thus | ||
317 | rebuild the cache. As an example, you would usually exclude ``TIME`` | ||
318 | and ``DATE`` because these variables are always changing. If you did | ||
319 | not exclude them, BitBake would never reuse the cache. | ||
320 | 359 | ||
321 | :term:`BB_HASHBASE_WHITELIST` | 360 | For example usage, see :term:`BB_GIT_SHALLOW`. |
322 | Lists variables that are excluded from checksum and dependency data. | 361 | |
323 | Variables that are excluded can therefore change without affecting | 362 | :term:`BB_GLOBAL_PYMODULES` |
324 | the checksum mechanism. A common example would be the variable for | 363 | Specifies the list of Python modules to place in the global namespace. |
325 | the path of the build. BitBake's output should not (and usually does | 364 | It is intended that only the core layer should set this and it is meant |
326 | not) depend on the directory in which it was built. | 365 | to be a very small list, typically just ``os`` and ``sys``. |
366 | :term:`BB_GLOBAL_PYMODULES` is expected to be set before the first | ||
367 | ``addpylib`` directive. | ||
368 | See also ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:extending python library code`". | ||
327 | 369 | ||
328 | :term:`BB_HASHCHECK_FUNCTION` | 370 | :term:`BB_HASHCHECK_FUNCTION` |
329 | Specifies the name of the function to call during the "setscene" part | 371 | Specifies the name of the function to call during the "setscene" part |
@@ -339,12 +381,66 @@ overview of their function and contents. | |||
339 | However, the more accurate the data returned, the more efficient the | 381 | However, the more accurate the data returned, the more efficient the |
340 | build will be. | 382 | build will be. |
341 | 383 | ||
384 | :term:`BB_HASHCONFIG_IGNORE_VARS` | ||
385 | Lists variables that are excluded from base configuration checksum, | ||
386 | which is used to determine if the cache can be reused. | ||
387 | |||
388 | One of the ways BitBake determines whether to re-parse the main | ||
389 | metadata is through checksums of the variables in the datastore of | ||
390 | the base configuration data. There are variables that you typically | ||
391 | want to exclude when checking whether or not to re-parse and thus | ||
392 | rebuild the cache. As an example, you would usually exclude ``TIME`` | ||
393 | and ``DATE`` because these variables are always changing. If you did | ||
394 | not exclude them, BitBake would never reuse the cache. | ||
395 | |||
396 | :term:`BB_HASHSERVE` | ||
397 | Specifies the Hash Equivalence server to use. | ||
398 | |||
399 | If set to ``auto``, BitBake automatically starts its own server | ||
400 | over a UNIX domain socket. An option is to connect this server | ||
401 | to an upstream one, by setting :term:`BB_HASHSERVE_UPSTREAM`. | ||
402 | |||
403 | If set to ``unix://path``, BitBake will connect to an existing | ||
404 | hash server available over a UNIX domain socket. | ||
405 | |||
406 | If set to ``host:port``, BitBake will connect to a remote server on the | ||
407 | specified host. This allows multiple clients to share the same | ||
408 | hash equivalence data. | ||
409 | |||
410 | The remote server can be started manually through | ||
411 | the ``bin/bitbake-hashserv`` script provided by BitBake, | ||
412 | which supports UNIX domain sockets too. This script also allows | ||
413 | to start the server in read-only mode, to avoid accepting | ||
414 | equivalences that correspond to Share State caches that are | ||
415 | only available on specific clients. | ||
416 | |||
417 | :term:`BB_HASHSERVE_UPSTREAM` | ||
418 | Specifies an upstream Hash Equivalence server. | ||
419 | |||
420 | This optional setting is only useful when a local Hash Equivalence | ||
421 | server is started (setting :term:`BB_HASHSERVE` to ``auto``), | ||
422 | and you wish the local server to query an upstream server for | ||
423 | Hash Equivalence data. | ||
424 | |||
425 | Example usage:: | ||
426 | |||
427 | BB_HASHSERVE_UPSTREAM = "hashserv.yocto.io:8687" | ||
428 | |||
342 | :term:`BB_INVALIDCONF` | 429 | :term:`BB_INVALIDCONF` |
343 | Used in combination with the ``ConfigParsed`` event to trigger | 430 | Used in combination with the ``ConfigParsed`` event to trigger |
344 | re-parsing the base metadata (i.e. all the recipes). The | 431 | re-parsing the base metadata (i.e. all the recipes). The |
345 | ``ConfigParsed`` event can set the variable to trigger the re-parse. | 432 | ``ConfigParsed`` event can set the variable to trigger the re-parse. |
346 | You must be careful to avoid recursive loops with this functionality. | 433 | You must be careful to avoid recursive loops with this functionality. |
347 | 434 | ||
435 | :term:`BB_LOADFACTOR_MAX` | ||
436 | Setting this to a value will cause BitBake to check the system load | ||
437 | average before executing new tasks. If the load average is above the | ||
438 | the number of CPUs multipled by this factor, no new task will be started | ||
439 | unless there is no task executing. A value of "1.5" has been found to | ||
440 | work reasonably. This is helpful for systems which don't have pressure | ||
441 | regulation enabled, which is more granular. Pressure values take | ||
442 | precedence over loadfactor. | ||
443 | |||
348 | :term:`BB_LOGCONFIG` | 444 | :term:`BB_LOGCONFIG` |
349 | Specifies the name of a config file that contains the user logging | 445 | Specifies the name of a config file that contains the user logging |
350 | configuration. See | 446 | configuration. See |
@@ -353,15 +449,28 @@ overview of their function and contents. | |||
353 | 449 | ||
354 | :term:`BB_LOGFMT` | 450 | :term:`BB_LOGFMT` |
355 | Specifies the name of the log files saved into | 451 | Specifies the name of the log files saved into |
356 | ``${``\ :term:`T`\ ``}``. By default, the ``BB_LOGFMT`` | 452 | ``${``\ :term:`T`\ ``}``. By default, the :term:`BB_LOGFMT` |
357 | variable is undefined and the log file names get created using the | 453 | variable is undefined and the log filenames get created using the |
358 | following form: :: | 454 | following form:: |
359 | 455 | ||
360 | log.{task}.{pid} | 456 | log.{task}.{pid} |
361 | 457 | ||
362 | If you want to force log files to take a specific name, you can set this | 458 | If you want to force log files to take a specific name, you can set this |
363 | variable in a configuration file. | 459 | variable in a configuration file. |
364 | 460 | ||
461 | :term:`BB_MULTI_PROVIDER_ALLOWED` | ||
462 | Allows you to suppress BitBake warnings caused when building two | ||
463 | separate recipes that provide the same output. | ||
464 | |||
465 | BitBake normally issues a warning when building two different recipes | ||
466 | where each provides the same output. This scenario is usually | ||
467 | something the user does not want. However, cases do exist where it | ||
468 | makes sense, particularly in the ``virtual/*`` namespace. You can use | ||
469 | this variable to suppress BitBake's warnings. | ||
470 | |||
471 | To use the variable, list provider names (e.g. recipe names, | ||
472 | ``virtual/kernel``, and so forth). | ||
473 | |||
365 | :term:`BB_NICE_LEVEL` | 474 | :term:`BB_NICE_LEVEL` |
366 | Allows BitBake to run at a specific priority (i.e. nice level). | 475 | Allows BitBake to run at a specific priority (i.e. nice level). |
367 | System permissions usually mean that BitBake can reduce its priority | 476 | System permissions usually mean that BitBake can reduce its priority |
@@ -377,19 +486,20 @@ overview of their function and contents. | |||
377 | running builds when not connected to the Internet, and when operating | 486 | running builds when not connected to the Internet, and when operating |
378 | in certain kinds of firewall environments. | 487 | in certain kinds of firewall environments. |
379 | 488 | ||
489 | :term:`BB_NUMBER_PARSE_THREADS` | ||
490 | Sets the number of threads BitBake uses when parsing. By default, the | ||
491 | number of threads is equal to the number of cores on the system. | ||
492 | |||
380 | :term:`BB_NUMBER_THREADS` | 493 | :term:`BB_NUMBER_THREADS` |
381 | The maximum number of tasks BitBake should run in parallel at any one | 494 | The maximum number of tasks BitBake should run in parallel at any one |
382 | time. If your host development system supports multiple cores, a good | 495 | time. If your host development system supports multiple cores, a good |
383 | rule of thumb is to set this variable to twice the number of cores. | 496 | rule of thumb is to set this variable to twice the number of cores. |
384 | 497 | ||
385 | :term:`BB_NUMBER_PARSE_THREADS` | ||
386 | Sets the number of threads BitBake uses when parsing. By default, the | ||
387 | number of threads is equal to the number of cores on the system. | ||
388 | |||
389 | :term:`BB_ORIGENV` | 498 | :term:`BB_ORIGENV` |
390 | Contains a copy of the original external environment in which BitBake | 499 | Contains a copy of the original external environment in which BitBake |
391 | was run. The copy is taken before any whitelisted variable values are | 500 | was run. The copy is taken before any variable values configured to |
392 | filtered into BitBake's datastore. | 501 | pass through from the external environment are filtered into BitBake's |
502 | datastore. | ||
393 | 503 | ||
394 | .. note:: | 504 | .. note:: |
395 | 505 | ||
@@ -397,21 +507,72 @@ overview of their function and contents. | |||
397 | queried using the normal datastore operations. | 507 | queried using the normal datastore operations. |
398 | 508 | ||
399 | :term:`BB_PRESERVE_ENV` | 509 | :term:`BB_PRESERVE_ENV` |
400 | Disables whitelisting and instead allows all variables through from | 510 | Disables environment filtering and instead allows all variables through |
401 | the external environment into BitBake's datastore. | 511 | from the external environment into BitBake's datastore. |
402 | 512 | ||
403 | .. note:: | 513 | .. note:: |
404 | 514 | ||
405 | You must set this variable in the external environment in order | 515 | You must set this variable in the external environment in order |
406 | for it to work. | 516 | for it to work. |
407 | 517 | ||
518 | :term:`BB_PRESSURE_MAX_CPU` | ||
519 | Specifies a maximum CPU pressure threshold, above which BitBake's | ||
520 | scheduler will not start new tasks (providing there is at least | ||
521 | one active task). If no value is set, CPU pressure is not | ||
522 | monitored when starting tasks. | ||
523 | |||
524 | The pressure data is calculated based upon what Linux kernels since | ||
525 | version 4.20 expose under ``/proc/pressure``. The threshold represents | ||
526 | the difference in "total" pressure from the previous second. The | ||
527 | minimum value is 1.0 (extremely slow builds) and the maximum is | ||
528 | 1000000 (a pressure value unlikely to ever be reached). | ||
529 | |||
530 | This threshold can be set in ``conf/local.conf`` as:: | ||
531 | |||
532 | BB_PRESSURE_MAX_CPU = "500" | ||
533 | |||
534 | :term:`BB_PRESSURE_MAX_IO` | ||
535 | Specifies a maximum I/O pressure threshold, above which BitBake's | ||
536 | scheduler will not start new tasks (providing there is at least | ||
537 | one active task). If no value is set, I/O pressure is not | ||
538 | monitored when starting tasks. | ||
539 | |||
540 | The pressure data is calculated based upon what Linux kernels since | ||
541 | version 4.20 expose under ``/proc/pressure``. The threshold represents | ||
542 | the difference in "total" pressure from the previous second. The | ||
543 | minimum value is 1.0 (extremely slow builds) and the maximum is | ||
544 | 1000000 (a pressure value unlikely to ever be reached). | ||
545 | |||
546 | At this point in time, experiments show that IO pressure tends to | ||
547 | be short-lived and regulating just the CPU with | ||
548 | :term:`BB_PRESSURE_MAX_CPU` can help to reduce it. | ||
549 | |||
550 | :term:`BB_PRESSURE_MAX_MEMORY` | ||
551 | |||
552 | Specifies a maximum memory pressure threshold, above which BitBake's | ||
553 | scheduler will not start new tasks (providing there is at least | ||
554 | one active task). If no value is set, memory pressure is not | ||
555 | monitored when starting tasks. | ||
556 | |||
557 | The pressure data is calculated based upon what Linux kernels since | ||
558 | version 4.20 expose under ``/proc/pressure``. The threshold represents | ||
559 | the difference in "total" pressure from the previous second. The | ||
560 | minimum value is 1.0 (extremely slow builds) and the maximum is | ||
561 | 1000000 (a pressure value unlikely to ever be reached). | ||
562 | |||
563 | Memory pressure is experienced when time is spent swapping, | ||
564 | refaulting pages from the page cache or performing direct reclaim. | ||
565 | This is why memory pressure is rarely seen, but setting this variable | ||
566 | might be useful as a last resort to prevent OOM errors if they are | ||
567 | occurring during builds. | ||
568 | |||
408 | :term:`BB_RUNFMT` | 569 | :term:`BB_RUNFMT` |
409 | Specifies the name of the executable script files (i.e. run files) | 570 | Specifies the name of the executable script files (i.e. run files) |
410 | saved into ``${``\ :term:`T`\ ``}``. By default, the | 571 | saved into ``${``\ :term:`T`\ ``}``. By default, the |
411 | ``BB_RUNFMT`` variable is undefined and the run file names get | 572 | :term:`BB_RUNFMT` variable is undefined and the run filenames get |
412 | created using the following form: :: | 573 | created using the following form:: |
413 | 574 | ||
414 | run.{task}.{pid} | 575 | run.{func}.{pid} |
415 | 576 | ||
416 | If you want to force run files to take a specific name, you can set this | 577 | If you want to force run files to take a specific name, you can set this |
417 | variable in a configuration file. | 578 | variable in a configuration file. |
@@ -425,14 +586,14 @@ overview of their function and contents. | |||
425 | Selects the name of the scheduler to use for the scheduling of | 586 | Selects the name of the scheduler to use for the scheduling of |
426 | BitBake tasks. Three options exist: | 587 | BitBake tasks. Three options exist: |
427 | 588 | ||
428 | - *basic* - The basic framework from which everything derives. Using | 589 | - *basic* --- the basic framework from which everything derives. Using |
429 | this option causes tasks to be ordered numerically as they are | 590 | this option causes tasks to be ordered numerically as they are |
430 | parsed. | 591 | parsed. |
431 | 592 | ||
432 | - *speed* - Executes tasks first that have more tasks depending on | 593 | - *speed* --- executes tasks first that have more tasks depending on |
433 | them. The "speed" option is the default. | 594 | them. The "speed" option is the default. |
434 | 595 | ||
435 | - *completion* - Causes the scheduler to try to complete a given | 596 | - *completion* --- causes the scheduler to try to complete a given |
436 | recipe once its build has started. | 597 | recipe once its build has started. |
437 | 598 | ||
438 | :term:`BB_SCHEDULERS` | 599 | :term:`BB_SCHEDULERS` |
@@ -452,17 +613,6 @@ overview of their function and contents. | |||
452 | The function specified by this variable returns a "True" or "False" | 613 | The function specified by this variable returns a "True" or "False" |
453 | depending on whether the dependency needs to be met. | 614 | depending on whether the dependency needs to be met. |
454 | 615 | ||
455 | :term:`BB_SETSCENE_VERIFY_FUNCTION2` | ||
456 | Specifies a function to call that verifies the list of planned task | ||
457 | execution before the main task execution happens. The function is | ||
458 | called once BitBake has a list of setscene tasks that have run and | ||
459 | either succeeded or failed. | ||
460 | |||
461 | The function allows for a task list check to see if they make sense. | ||
462 | Even if BitBake was planning to skip a task, the returned value of | ||
463 | the function can force BitBake to run the task, which is necessary | ||
464 | under certain metadata defined circumstances. | ||
465 | |||
466 | :term:`BB_SIGNATURE_EXCLUDE_FLAGS` | 616 | :term:`BB_SIGNATURE_EXCLUDE_FLAGS` |
467 | Lists variable flags (varflags) that can be safely excluded from | 617 | Lists variable flags (varflags) that can be safely excluded from |
468 | checksum and dependency data for keys in the datastore. When | 618 | checksum and dependency data for keys in the datastore. When |
@@ -485,40 +635,17 @@ overview of their function and contents. | |||
485 | :term:`BB_SRCREV_POLICY` | 635 | :term:`BB_SRCREV_POLICY` |
486 | Defines the behavior of the fetcher when it interacts with source | 636 | Defines the behavior of the fetcher when it interacts with source |
487 | control systems and dynamic source revisions. The | 637 | control systems and dynamic source revisions. The |
488 | ``BB_SRCREV_POLICY`` variable is useful when working without a | 638 | :term:`BB_SRCREV_POLICY` variable is useful when working without a |
489 | network. | 639 | network. |
490 | 640 | ||
491 | The variable can be set using one of two policies: | 641 | The variable can be set using one of two policies: |
492 | 642 | ||
493 | - *cache* - Retains the value the system obtained previously rather | 643 | - *cache* --- retains the value the system obtained previously rather |
494 | than querying the source control system each time. | 644 | than querying the source control system each time. |
495 | 645 | ||
496 | - *clear* - Queries the source controls system every time. With this | 646 | - *clear* --- queries the source controls system every time. With this |
497 | policy, there is no cache. The "clear" policy is the default. | 647 | policy, there is no cache. The "clear" policy is the default. |
498 | 648 | ||
499 | :term:`BB_STAMP_POLICY` | ||
500 | Defines the mode used for how timestamps of stamp files are compared. | ||
501 | You can set the variable to one of the following modes: | ||
502 | |||
503 | - *perfile* - Timestamp comparisons are only made between timestamps | ||
504 | of a specific recipe. This is the default mode. | ||
505 | |||
506 | - *full* - Timestamp comparisons are made for all dependencies. | ||
507 | |||
508 | - *whitelist* - Identical to "full" mode except timestamp | ||
509 | comparisons are made for recipes listed in the | ||
510 | :term:`BB_STAMP_WHITELIST` variable. | ||
511 | |||
512 | .. note:: | ||
513 | |||
514 | Stamp policies are largely obsolete with the introduction of | ||
515 | setscene tasks. | ||
516 | |||
517 | :term:`BB_STAMP_WHITELIST` | ||
518 | Lists files whose stamp file timestamps are compared when the stamp | ||
519 | policy mode is set to "whitelist". For information on stamp policies, | ||
520 | see the :term:`BB_STAMP_POLICY` variable. | ||
521 | |||
522 | :term:`BB_STRICT_CHECKSUM` | 649 | :term:`BB_STRICT_CHECKSUM` |
523 | Sets a more strict checksum mechanism for non-local URLs. Setting | 650 | Sets a more strict checksum mechanism for non-local URLs. Setting |
524 | this variable to a value causes BitBake to report an error if it | 651 | this variable to a value causes BitBake to report an error if it |
@@ -529,7 +656,7 @@ overview of their function and contents. | |||
529 | Allows adjustment of a task's Input/Output priority. During | 656 | Allows adjustment of a task's Input/Output priority. During |
530 | Autobuilder testing, random failures can occur for tasks due to I/O | 657 | Autobuilder testing, random failures can occur for tasks due to I/O |
531 | starvation. These failures occur during various QEMU runtime | 658 | starvation. These failures occur during various QEMU runtime |
532 | timeouts. You can use the ``BB_TASK_IONICE_LEVEL`` variable to adjust | 659 | timeouts. You can use the :term:`BB_TASK_IONICE_LEVEL` variable to adjust |
533 | the I/O priority of these tasks. | 660 | the I/O priority of these tasks. |
534 | 661 | ||
535 | .. note:: | 662 | .. note:: |
@@ -537,7 +664,7 @@ overview of their function and contents. | |||
537 | This variable works similarly to the :term:`BB_TASK_NICE_LEVEL` | 664 | This variable works similarly to the :term:`BB_TASK_NICE_LEVEL` |
538 | variable except with a task's I/O priorities. | 665 | variable except with a task's I/O priorities. |
539 | 666 | ||
540 | Set the variable as follows: :: | 667 | Set the variable as follows:: |
541 | 668 | ||
542 | BB_TASK_IONICE_LEVEL = "class.prio" | 669 | BB_TASK_IONICE_LEVEL = "class.prio" |
543 | 670 | ||
@@ -555,7 +682,7 @@ overview of their function and contents. | |||
555 | In order for your I/O priority settings to take effect, you need the | 682 | In order for your I/O priority settings to take effect, you need the |
556 | Completely Fair Queuing (CFQ) Scheduler selected for the backing block | 683 | Completely Fair Queuing (CFQ) Scheduler selected for the backing block |
557 | device. To select the scheduler, use the following command form where | 684 | device. To select the scheduler, use the following command form where |
558 | device is the device (e.g. sda, sdb, and so forth): :: | 685 | device is the device (e.g. sda, sdb, and so forth):: |
559 | 686 | ||
560 | $ sudo sh -c "echo cfq > /sys/block/device/queu/scheduler" | 687 | $ sudo sh -c "echo cfq > /sys/block/device/queu/scheduler" |
561 | 688 | ||
@@ -564,7 +691,7 @@ overview of their function and contents. | |||
564 | 691 | ||
565 | You can use this variable in combination with task overrides to raise | 692 | You can use this variable in combination with task overrides to raise |
566 | or lower priorities of specific tasks. For example, on the `Yocto | 693 | or lower priorities of specific tasks. For example, on the `Yocto |
567 | Project <http://www.yoctoproject.org>`__ autobuilder, QEMU emulation | 694 | Project <https://www.yoctoproject.org>`__ autobuilder, QEMU emulation |
568 | in images is given a higher priority as compared to build tasks to | 695 | in images is given a higher priority as compared to build tasks to |
569 | ensure that images do not suffer timeouts on loaded systems. | 696 | ensure that images do not suffer timeouts on loaded systems. |
570 | 697 | ||
@@ -596,20 +723,20 @@ overview of their function and contents. | |||
596 | To build a different variant of the recipe with a minimal amount of | 723 | To build a different variant of the recipe with a minimal amount of |
597 | code, it usually is as simple as adding the variable to your recipe. | 724 | code, it usually is as simple as adding the variable to your recipe. |
598 | Here are two examples. The "native" variants are from the | 725 | Here are two examples. The "native" variants are from the |
599 | OpenEmbedded-Core metadata: :: | 726 | OpenEmbedded-Core metadata:: |
600 | 727 | ||
601 | BBCLASSEXTEND =+ "native nativesdk" | 728 | BBCLASSEXTEND =+ "native nativesdk" |
602 | BBCLASSEXTEND =+ "multilib:multilib_name" | 729 | BBCLASSEXTEND =+ "multilib:multilib_name" |
603 | 730 | ||
604 | .. note:: | 731 | .. note:: |
605 | 732 | ||
606 | Internally, the ``BBCLASSEXTEND`` mechanism generates recipe | 733 | Internally, the :term:`BBCLASSEXTEND` mechanism generates recipe |
607 | variants by rewriting variable values and applying overrides such | 734 | variants by rewriting variable values and applying overrides such |
608 | as ``_class-native``. For example, to generate a native version of | 735 | as ``_class-native``. For example, to generate a native version of |
609 | a recipe, a :term:`DEPENDS` on "foo" is | 736 | a recipe, a :term:`DEPENDS` on "foo" is |
610 | rewritten to a ``DEPENDS`` on "foo-native". | 737 | rewritten to a :term:`DEPENDS` on "foo-native". |
611 | 738 | ||
612 | Even when using ``BBCLASSEXTEND``, the recipe is only parsed once. | 739 | Even when using :term:`BBCLASSEXTEND`, the recipe is only parsed once. |
613 | Parsing once adds some limitations. For example, it is not | 740 | Parsing once adds some limitations. For example, it is not |
614 | possible to include a different file depending on the variant, | 741 | possible to include a different file depending on the variant, |
615 | since ``include`` statements are processed when the recipe is | 742 | since ``include`` statements are processed when the recipe is |
@@ -642,17 +769,17 @@ overview of their function and contents. | |||
642 | This variable is useful in situations where the same recipe appears | 769 | This variable is useful in situations where the same recipe appears |
643 | in more than one layer. Setting this variable allows you to | 770 | in more than one layer. Setting this variable allows you to |
644 | prioritize a layer against other layers that contain the same recipe | 771 | prioritize a layer against other layers that contain the same recipe |
645 | - effectively letting you control the precedence for the multiple | 772 | --- effectively letting you control the precedence for the multiple |
646 | layers. The precedence established through this variable stands | 773 | layers. The precedence established through this variable stands |
647 | regardless of a recipe's version (:term:`PV` variable). | 774 | regardless of a recipe's version (:term:`PV` variable). |
648 | For example, a layer that has a recipe with a higher ``PV`` value but | 775 | For example, a layer that has a recipe with a higher :term:`PV` value but |
649 | for which the ``BBFILE_PRIORITY`` is set to have a lower precedence | 776 | for which the :term:`BBFILE_PRIORITY` is set to have a lower precedence |
650 | still has a lower precedence. | 777 | still has a lower precedence. |
651 | 778 | ||
652 | A larger value for the ``BBFILE_PRIORITY`` variable results in a | 779 | A larger value for the :term:`BBFILE_PRIORITY` variable results in a |
653 | higher precedence. For example, the value 6 has a higher precedence | 780 | higher precedence. For example, the value 6 has a higher precedence |
654 | than the value 5. If not specified, the ``BBFILE_PRIORITY`` variable | 781 | than the value 5. If not specified, the :term:`BBFILE_PRIORITY` variable |
655 | is set based on layer dependencies (see the ``LAYERDEPENDS`` variable | 782 | is set based on layer dependencies (see the :term:`LAYERDEPENDS` variable |
656 | for more information. The default priority, if unspecified for a | 783 | for more information. The default priority, if unspecified for a |
657 | layer with no dependencies, is the lowest defined priority + 1 (or 1 | 784 | layer with no dependencies, is the lowest defined priority + 1 (or 1 |
658 | if no priorities are defined). | 785 | if no priorities are defined). |
@@ -671,6 +798,45 @@ overview of their function and contents. | |||
671 | For details on the syntax, see the documentation by following the | 798 | For details on the syntax, see the documentation by following the |
672 | previous link. | 799 | previous link. |
673 | 800 | ||
801 | :term:`BBFILES_DYNAMIC` | ||
802 | Activates content depending on presence of identified layers. You | ||
803 | identify the layers by the collections that the layers define. | ||
804 | |||
805 | Use the :term:`BBFILES_DYNAMIC` variable to avoid ``.bbappend`` files whose | ||
806 | corresponding ``.bb`` file is in a layer that attempts to modify other | ||
807 | layers through ``.bbappend`` but does not want to introduce a hard | ||
808 | dependency on those other layers. | ||
809 | |||
810 | Additionally you can prefix the rule with "!" to add ``.bbappend`` and | ||
811 | ``.bb`` files in case a layer is not present. Use this avoid hard | ||
812 | dependency on those other layers. | ||
813 | |||
814 | Use the following form for :term:`BBFILES_DYNAMIC`:: | ||
815 | |||
816 | collection_name:filename_pattern | ||
817 | |||
818 | The following example identifies two collection names and two filename | ||
819 | patterns:: | ||
820 | |||
821 | BBFILES_DYNAMIC += "\ | ||
822 | clang-layer:${LAYERDIR}/bbappends/meta-clang/*/*/*.bbappend \ | ||
823 | core:${LAYERDIR}/bbappends/openembedded-core/meta/*/*/*.bbappend \ | ||
824 | " | ||
825 | |||
826 | When the collection name is prefixed with "!" it will add the file pattern in case | ||
827 | the layer is absent:: | ||
828 | |||
829 | BBFILES_DYNAMIC += "\ | ||
830 | !clang-layer:${LAYERDIR}/backfill/meta-clang/*/*/*.bb \ | ||
831 | " | ||
832 | |||
833 | This next example shows an error message that occurs because invalid | ||
834 | entries are found, which cause parsing to fail:: | ||
835 | |||
836 | ERROR: BBFILES_DYNAMIC entries must be of the form {!}<collection name>:<filename pattern>, not: | ||
837 | /work/my-layer/bbappends/meta-security-isafw/*/*/*.bbappend | ||
838 | /work/my-layer/bbappends/openembedded-core/meta/*/*/*.bbappend | ||
839 | |||
674 | :term:`BBINCLUDED` | 840 | :term:`BBINCLUDED` |
675 | Contains a space-separated list of all of all files that BitBake's | 841 | Contains a space-separated list of all of all files that BitBake's |
676 | parser included during parsing of the current file. | 842 | parser included during parsing of the current file. |
@@ -682,13 +848,13 @@ overview of their function and contents. | |||
682 | :term:`BBINCLUDELOGS_LINES` | 848 | :term:`BBINCLUDELOGS_LINES` |
683 | If :term:`BBINCLUDELOGS` is set, specifies | 849 | If :term:`BBINCLUDELOGS` is set, specifies |
684 | the maximum number of lines from the task log file to print when | 850 | the maximum number of lines from the task log file to print when |
685 | reporting a failed task. If you do not set ``BBINCLUDELOGS_LINES``, | 851 | reporting a failed task. If you do not set :term:`BBINCLUDELOGS_LINES`, |
686 | the entire log is printed. | 852 | the entire log is printed. |
687 | 853 | ||
688 | :term:`BBLAYERS` | 854 | :term:`BBLAYERS` |
689 | Lists the layers to enable during the build. This variable is defined | 855 | Lists the layers to enable during the build. This variable is defined |
690 | in the ``bblayers.conf`` configuration file in the build directory. | 856 | in the ``bblayers.conf`` configuration file in the build directory. |
691 | Here is an example: :: | 857 | Here is an example:: |
692 | 858 | ||
693 | BBLAYERS = " \ | 859 | BBLAYERS = " \ |
694 | /home/scottrif/poky/meta \ | 860 | /home/scottrif/poky/meta \ |
@@ -708,7 +874,7 @@ overview of their function and contents. | |||
708 | :term:`BBMASK` | 874 | :term:`BBMASK` |
709 | Prevents BitBake from processing recipes and recipe append files. | 875 | Prevents BitBake from processing recipes and recipe append files. |
710 | 876 | ||
711 | You can use the ``BBMASK`` variable to "hide" these ``.bb`` and | 877 | You can use the :term:`BBMASK` variable to "hide" these ``.bb`` and |
712 | ``.bbappend`` files. BitBake ignores any recipe or recipe append | 878 | ``.bbappend`` files. BitBake ignores any recipe or recipe append |
713 | files that match any of the expressions. It is as if BitBake does not | 879 | files that match any of the expressions. It is as if BitBake does not |
714 | see them at all. Consequently, matching files are not parsed or | 880 | see them at all. Consequently, matching files are not parsed or |
@@ -722,13 +888,13 @@ overview of their function and contents. | |||
722 | 888 | ||
723 | The following example uses a complete regular expression to tell | 889 | The following example uses a complete regular expression to tell |
724 | BitBake to ignore all recipe and recipe append files in the | 890 | BitBake to ignore all recipe and recipe append files in the |
725 | ``meta-ti/recipes-misc/`` directory: :: | 891 | ``meta-ti/recipes-misc/`` directory:: |
726 | 892 | ||
727 | BBMASK = "meta-ti/recipes-misc/" | 893 | BBMASK = "meta-ti/recipes-misc/" |
728 | 894 | ||
729 | If you want to mask out multiple directories or recipes, you can | 895 | If you want to mask out multiple directories or recipes, you can |
730 | specify multiple regular expression fragments. This next example | 896 | specify multiple regular expression fragments. This next example |
731 | masks out multiple directories and individual recipes: :: | 897 | masks out multiple directories and individual recipes:: |
732 | 898 | ||
733 | BBMASK += "/meta-ti/recipes-misc/ meta-ti/recipes-ti/packagegroup/" | 899 | BBMASK += "/meta-ti/recipes-misc/ meta-ti/recipes-ti/packagegroup/" |
734 | BBMASK += "/meta-oe/recipes-support/" | 900 | BBMASK += "/meta-oe/recipes-support/" |
@@ -745,11 +911,11 @@ overview of their function and contents. | |||
745 | Enables BitBake to perform multiple configuration builds and lists | 911 | Enables BitBake to perform multiple configuration builds and lists |
746 | each separate configuration (multiconfig). You can use this variable | 912 | each separate configuration (multiconfig). You can use this variable |
747 | to cause BitBake to build multiple targets where each target has a | 913 | to cause BitBake to build multiple targets where each target has a |
748 | separate configuration. Define ``BBMULTICONFIG`` in your | 914 | separate configuration. Define :term:`BBMULTICONFIG` in your |
749 | ``conf/local.conf`` configuration file. | 915 | ``conf/local.conf`` configuration file. |
750 | 916 | ||
751 | As an example, the following line specifies three multiconfigs, each | 917 | As an example, the following line specifies three multiconfigs, each |
752 | having a separate configuration file: :: | 918 | having a separate configuration file:: |
753 | 919 | ||
754 | BBMULTIFONFIG = "configA configB configC" | 920 | BBMULTIFONFIG = "configA configB configC" |
755 | 921 | ||
@@ -757,20 +923,20 @@ overview of their function and contents. | |||
757 | build directory within a directory named ``conf/multiconfig`` (e.g. | 923 | build directory within a directory named ``conf/multiconfig`` (e.g. |
758 | build_directory\ ``/conf/multiconfig/configA.conf``). | 924 | build_directory\ ``/conf/multiconfig/configA.conf``). |
759 | 925 | ||
760 | For information on how to use ``BBMULTICONFIG`` in an environment | 926 | For information on how to use :term:`BBMULTICONFIG` in an environment |
761 | that supports building targets with multiple configurations, see the | 927 | that supports building targets with multiple configurations, see the |
762 | ":ref:`bitbake-user-manual/bitbake-user-manual-intro:executing a multiple configuration build`" | 928 | ":ref:`bitbake-user-manual/bitbake-user-manual-intro:executing a multiple configuration build`" |
763 | section. | 929 | section. |
764 | 930 | ||
765 | :term:`BBPATH` | 931 | :term:`BBPATH` |
766 | Used by BitBake to locate class (``.bbclass``) and configuration | 932 | A colon-separated list used by BitBake to locate class (``.bbclass``) |
767 | (``.conf``) files. This variable is analogous to the ``PATH`` | 933 | and configuration (``.conf``) files. This variable is analogous to the |
768 | variable. | 934 | ``PATH`` variable. |
769 | 935 | ||
770 | If you run BitBake from a directory outside of the build directory, | 936 | If you run BitBake from a directory outside of the build directory, |
771 | you must be sure to set ``BBPATH`` to point to the build directory. | 937 | you must be sure to set :term:`BBPATH` to point to the build directory. |
772 | Set the variable as you would any environment variable and then run | 938 | Set the variable as you would any environment variable and then run |
773 | BitBake: :: | 939 | BitBake:: |
774 | 940 | ||
775 | $ BBPATH="build_directory" | 941 | $ BBPATH="build_directory" |
776 | $ export BBPATH | 942 | $ export BBPATH |
@@ -784,16 +950,6 @@ overview of their function and contents. | |||
784 | Allows you to use a configuration file to add to the list of | 950 | Allows you to use a configuration file to add to the list of |
785 | command-line target recipes you want to build. | 951 | command-line target recipes you want to build. |
786 | 952 | ||
787 | :term:`BBVERSIONS` | ||
788 | Allows a single recipe to build multiple versions of a project from a | ||
789 | single recipe file. You also able to specify conditional metadata | ||
790 | using the :term:`OVERRIDES` mechanism for a | ||
791 | single version or for an optionally named range of versions. | ||
792 | |||
793 | For more information on ``BBVERSIONS``, see the | ||
794 | ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:variants - class extension mechanism`" | ||
795 | section. | ||
796 | |||
797 | :term:`BITBAKE_UI` | 953 | :term:`BITBAKE_UI` |
798 | Used to specify the UI module to use when running BitBake. Using this | 954 | Used to specify the UI module to use when running BitBake. Using this |
799 | variable is equivalent to using the ``-u`` command-line option. | 955 | variable is equivalent to using the ``-u`` command-line option. |
@@ -825,7 +981,7 @@ overview of their function and contents. | |||
825 | The most common usage of this is variable is to set it to "-1" within | 981 | The most common usage of this is variable is to set it to "-1" within |
826 | a recipe for a development version of a piece of software. Using the | 982 | a recipe for a development version of a piece of software. Using the |
827 | variable in this way causes the stable version of the recipe to build | 983 | variable in this way causes the stable version of the recipe to build |
828 | by default in the absence of ``PREFERRED_VERSION`` being used to | 984 | by default in the absence of :term:`PREFERRED_VERSION` being used to |
829 | build the development version. | 985 | build the development version. |
830 | 986 | ||
831 | .. note:: | 987 | .. note:: |
@@ -838,8 +994,8 @@ overview of their function and contents. | |||
838 | Lists a recipe's build-time dependencies (i.e. other recipe files). | 994 | Lists a recipe's build-time dependencies (i.e. other recipe files). |
839 | 995 | ||
840 | Consider this simple example for two recipes named "a" and "b" that | 996 | Consider this simple example for two recipes named "a" and "b" that |
841 | produce similarly named packages. In this example, the ``DEPENDS`` | 997 | produce similarly named packages. In this example, the :term:`DEPENDS` |
842 | statement appears in the "a" recipe: :: | 998 | statement appears in the "a" recipe:: |
843 | 999 | ||
844 | DEPENDS = "b" | 1000 | DEPENDS = "b" |
845 | 1001 | ||
@@ -856,7 +1012,7 @@ overview of their function and contents. | |||
856 | 1012 | ||
857 | :term:`DL_DIR` | 1013 | :term:`DL_DIR` |
858 | The central download directory used by the build process to store | 1014 | The central download directory used by the build process to store |
859 | downloads. By default, ``DL_DIR`` gets files suitable for mirroring for | 1015 | downloads. By default, :term:`DL_DIR` gets files suitable for mirroring for |
860 | everything except Git repositories. If you want tarballs of Git | 1016 | everything except Git repositories. If you want tarballs of Git |
861 | repositories, use the :term:`BB_GENERATE_MIRROR_TARBALLS` variable. | 1017 | repositories, use the :term:`BB_GENERATE_MIRROR_TARBALLS` variable. |
862 | 1018 | ||
@@ -867,18 +1023,18 @@ overview of their function and contents. | |||
867 | ``bblayers.conf`` configuration file. | 1023 | ``bblayers.conf`` configuration file. |
868 | 1024 | ||
869 | To exclude a recipe from a world build using this variable, set the | 1025 | To exclude a recipe from a world build using this variable, set the |
870 | variable to "1" in the recipe. | 1026 | variable to "1" in the recipe. Set it to "0" to add it back to world build. |
871 | 1027 | ||
872 | .. note:: | 1028 | .. note:: |
873 | 1029 | ||
874 | Recipes added to ``EXCLUDE_FROM_WORLD`` may still be built during a world | 1030 | Recipes added to :term:`EXCLUDE_FROM_WORLD` may still be built during a world |
875 | build in order to satisfy dependencies of other recipes. Adding a | 1031 | build in order to satisfy dependencies of other recipes. Adding a |
876 | recipe to ``EXCLUDE_FROM_WORLD`` only ensures that the recipe is not | 1032 | recipe to :term:`EXCLUDE_FROM_WORLD` only ensures that the recipe is not |
877 | explicitly added to the list of build targets in a world build. | 1033 | explicitly added to the list of build targets in a world build. |
878 | 1034 | ||
879 | :term:`FAKEROOT` | 1035 | :term:`FAKEROOT` |
880 | Contains the command to use when running a shell script in a fakeroot | 1036 | Contains the command to use when running a shell script in a fakeroot |
881 | environment. The ``FAKEROOT`` variable is obsolete and has been | 1037 | environment. The :term:`FAKEROOT` variable is obsolete and has been |
882 | replaced by the other ``FAKEROOT*`` variables. See these entries in | 1038 | replaced by the other ``FAKEROOT*`` variables. See these entries in |
883 | the glossary for more information. | 1039 | the glossary for more information. |
884 | 1040 | ||
@@ -925,6 +1081,11 @@ overview of their function and contents. | |||
925 | environment variable. The value is a colon-separated list of | 1081 | environment variable. The value is a colon-separated list of |
926 | directories that are searched left-to-right in order. | 1082 | directories that are searched left-to-right in order. |
927 | 1083 | ||
1084 | :term:`FILE_LAYERNAME` | ||
1085 | During parsing and task execution, this is set to the name of the | ||
1086 | layer containing the recipe file. Code can use this to identify which | ||
1087 | layer a recipe is from. | ||
1088 | |||
928 | :term:`GITDIR` | 1089 | :term:`GITDIR` |
929 | The directory in which a local copy of a Git repository is stored | 1090 | The directory in which a local copy of a Git repository is stored |
930 | when it is cloned. | 1091 | when it is cloned. |
@@ -941,9 +1102,9 @@ overview of their function and contents. | |||
941 | Causes the named class or classes to be inherited globally. Anonymous | 1102 | Causes the named class or classes to be inherited globally. Anonymous |
942 | functions in the class or classes are not executed for the base | 1103 | functions in the class or classes are not executed for the base |
943 | configuration and in each individual recipe. The OpenEmbedded build | 1104 | configuration and in each individual recipe. The OpenEmbedded build |
944 | system ignores changes to ``INHERIT`` in individual recipes. | 1105 | system ignores changes to :term:`INHERIT` in individual recipes. |
945 | 1106 | ||
946 | For more information on ``INHERIT``, see the | 1107 | For more information on :term:`INHERIT`, see the |
947 | ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:\`\`inherit\`\` configuration directive`" | 1108 | ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:\`\`inherit\`\` configuration directive`" |
948 | section. | 1109 | section. |
949 | 1110 | ||
@@ -973,6 +1134,29 @@ overview of their function and contents. | |||
973 | variable is not available outside of ``layer.conf`` and references | 1134 | variable is not available outside of ``layer.conf`` and references |
974 | are expanded immediately when parsing of the file completes. | 1135 | are expanded immediately when parsing of the file completes. |
975 | 1136 | ||
1137 | :term:`LAYERSERIES_COMPAT` | ||
1138 | Lists the versions of the OpenEmbedded-Core (OE-Core) for which | ||
1139 | a layer is compatible. Using the :term:`LAYERSERIES_COMPAT` variable | ||
1140 | allows the layer maintainer to indicate which combinations of the | ||
1141 | layer and OE-Core can be expected to work. The variable gives the | ||
1142 | system a way to detect when a layer has not been tested with new | ||
1143 | releases of OE-Core (e.g. the layer is not maintained). | ||
1144 | |||
1145 | To specify the OE-Core versions for which a layer is compatible, use | ||
1146 | this variable in your layer's ``conf/layer.conf`` configuration file. | ||
1147 | For the list, use the Yocto Project release name (e.g. "kirkstone", | ||
1148 | "mickledore"). To specify multiple OE-Core versions for the layer, use | ||
1149 | a space-separated list:: | ||
1150 | |||
1151 | LAYERSERIES_COMPAT_layer_root_name = "kirkstone mickledore" | ||
1152 | |||
1153 | .. note:: | ||
1154 | |||
1155 | Setting :term:`LAYERSERIES_COMPAT` is required by the Yocto Project | ||
1156 | Compatible version 2 standard. | ||
1157 | The OpenEmbedded build system produces a warning if the variable | ||
1158 | is not set for any given layer. | ||
1159 | |||
976 | :term:`LAYERVERSION` | 1160 | :term:`LAYERVERSION` |
977 | Optionally specifies the version of a layer as a single number. You | 1161 | Optionally specifies the version of a layer as a single number. You |
978 | can use this variable within | 1162 | can use this variable within |
@@ -991,29 +1175,16 @@ overview of their function and contents. | |||
991 | the build system searches for source code, it first tries the local | 1175 | the build system searches for source code, it first tries the local |
992 | download directory. If that location fails, the build system tries | 1176 | download directory. If that location fails, the build system tries |
993 | locations defined by :term:`PREMIRRORS`, the | 1177 | locations defined by :term:`PREMIRRORS`, the |
994 | upstream source, and then locations specified by ``MIRRORS`` in that | 1178 | upstream source, and then locations specified by :term:`MIRRORS` in that |
995 | order. | 1179 | order. |
996 | 1180 | ||
997 | :term:`MULTI_PROVIDER_WHITELIST` | ||
998 | Allows you to suppress BitBake warnings caused when building two | ||
999 | separate recipes that provide the same output. | ||
1000 | |||
1001 | BitBake normally issues a warning when building two different recipes | ||
1002 | where each provides the same output. This scenario is usually | ||
1003 | something the user does not want. However, cases do exist where it | ||
1004 | makes sense, particularly in the ``virtual/*`` namespace. You can use | ||
1005 | this variable to suppress BitBake's warnings. | ||
1006 | |||
1007 | To use the variable, list provider names (e.g. recipe names, | ||
1008 | ``virtual/kernel``, and so forth). | ||
1009 | |||
1010 | :term:`OVERRIDES` | 1181 | :term:`OVERRIDES` |
1011 | BitBake uses ``OVERRIDES`` to control what variables are overridden | 1182 | A colon-separated list that BitBake uses to control what variables are |
1012 | after BitBake parses recipes and configuration files. | 1183 | overridden after BitBake parses recipes and configuration files. |
1013 | 1184 | ||
1014 | Following is a simple example that uses an overrides list based on | 1185 | Following is a simple example that uses an overrides list based on |
1015 | machine architectures: OVERRIDES = "arm:x86:mips:powerpc" You can | 1186 | machine architectures: OVERRIDES = "arm:x86:mips:powerpc" You can |
1016 | find information on how to use ``OVERRIDES`` in the | 1187 | find information on how to use :term:`OVERRIDES` in the |
1017 | ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:conditional syntax | 1188 | ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:conditional syntax |
1018 | (overrides)`" section. | 1189 | (overrides)`" section. |
1019 | 1190 | ||
@@ -1027,11 +1198,11 @@ overview of their function and contents. | |||
1027 | :term:`PACKAGES_DYNAMIC` | 1198 | :term:`PACKAGES_DYNAMIC` |
1028 | A promise that your recipe satisfies runtime dependencies for | 1199 | A promise that your recipe satisfies runtime dependencies for |
1029 | optional modules that are found in other recipes. | 1200 | optional modules that are found in other recipes. |
1030 | ``PACKAGES_DYNAMIC`` does not actually satisfy the dependencies, it | 1201 | :term:`PACKAGES_DYNAMIC` does not actually satisfy the dependencies, it |
1031 | only states that they should be satisfied. For example, if a hard, | 1202 | only states that they should be satisfied. For example, if a hard, |
1032 | runtime dependency (:term:`RDEPENDS`) of another | 1203 | runtime dependency (:term:`RDEPENDS`) of another |
1033 | package is satisfied during the build through the | 1204 | package is satisfied during the build through the |
1034 | ``PACKAGES_DYNAMIC`` variable, but a package with the module name is | 1205 | :term:`PACKAGES_DYNAMIC` variable, but a package with the module name is |
1035 | never actually produced, then the other package will be broken. | 1206 | never actually produced, then the other package will be broken. |
1036 | 1207 | ||
1037 | :term:`PE` | 1208 | :term:`PE` |
@@ -1061,7 +1232,7 @@ overview of their function and contents. | |||
1061 | recipes provide the same item. You should always suffix the variable | 1232 | recipes provide the same item. You should always suffix the variable |
1062 | with the name of the provided item, and you should set it to the | 1233 | with the name of the provided item, and you should set it to the |
1063 | :term:`PN` of the recipe to which you want to give | 1234 | :term:`PN` of the recipe to which you want to give |
1064 | precedence. Some examples: :: | 1235 | precedence. Some examples:: |
1065 | 1236 | ||
1066 | PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto" | 1237 | PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto" |
1067 | PREFERRED_PROVIDER_virtual/xserver = "xserver-xf86" | 1238 | PREFERRED_PROVIDER_virtual/xserver = "xserver-xf86" |
@@ -1070,30 +1241,30 @@ overview of their function and contents. | |||
1070 | :term:`PREFERRED_PROVIDERS` | 1241 | :term:`PREFERRED_PROVIDERS` |
1071 | Determines which recipe should be given preference for cases where | 1242 | Determines which recipe should be given preference for cases where |
1072 | multiple recipes provide the same item. Functionally, | 1243 | multiple recipes provide the same item. Functionally, |
1073 | ``PREFERRED_PROVIDERS`` is identical to | 1244 | :term:`PREFERRED_PROVIDERS` is identical to |
1074 | :term:`PREFERRED_PROVIDER`. However, the ``PREFERRED_PROVIDERS`` variable | 1245 | :term:`PREFERRED_PROVIDER`. However, the :term:`PREFERRED_PROVIDERS` variable |
1075 | lets you define preferences for multiple situations using the following | 1246 | lets you define preferences for multiple situations using the following |
1076 | form: :: | 1247 | form:: |
1077 | 1248 | ||
1078 | PREFERRED_PROVIDERS = "xxx:yyy aaa:bbb ..." | 1249 | PREFERRED_PROVIDERS = "xxx:yyy aaa:bbb ..." |
1079 | 1250 | ||
1080 | This form is a convenient replacement for the following: :: | 1251 | This form is a convenient replacement for the following:: |
1081 | 1252 | ||
1082 | PREFERRED_PROVIDER_xxx = "yyy" | 1253 | PREFERRED_PROVIDER_xxx = "yyy" |
1083 | PREFERRED_PROVIDER_aaa = "bbb" | 1254 | PREFERRED_PROVIDER_aaa = "bbb" |
1084 | 1255 | ||
1085 | :term:`PREFERRED_VERSION` | 1256 | :term:`PREFERRED_VERSION` |
1086 | If there are multiple versions of recipes available, this variable | 1257 | If there are multiple versions of a recipe available, this variable |
1087 | determines which recipe should be given preference. You must always | 1258 | determines which version should be given preference. You must always |
1088 | suffix the variable with the :term:`PN` you want to | 1259 | suffix the variable with the :term:`PN` you want to |
1089 | select, and you should set :term:`PV` accordingly for | 1260 | select, and you should set :term:`PV` accordingly for |
1090 | precedence. | 1261 | precedence. |
1091 | 1262 | ||
1092 | The ``PREFERRED_VERSION`` variable supports limited wildcard use | 1263 | The :term:`PREFERRED_VERSION` variable supports limited wildcard use |
1093 | through the "``%``" character. You can use the character to match any | 1264 | through the "``%``" character. You can use the character to match any |
1094 | number of characters, which can be useful when specifying versions | 1265 | number of characters, which can be useful when specifying versions |
1095 | that contain long revision numbers that potentially change. Here are | 1266 | that contain long revision numbers that potentially change. Here are |
1096 | two examples: :: | 1267 | two examples:: |
1097 | 1268 | ||
1098 | PREFERRED_VERSION_python = "2.7.3" | 1269 | PREFERRED_VERSION_python = "2.7.3" |
1099 | PREFERRED_VERSION_linux-yocto = "4.12%" | 1270 | PREFERRED_VERSION_linux-yocto = "4.12%" |
@@ -1104,22 +1275,26 @@ overview of their function and contents. | |||
1104 | end of the string. You cannot use the wildcard character in any other | 1275 | end of the string. You cannot use the wildcard character in any other |
1105 | location of the string. | 1276 | location of the string. |
1106 | 1277 | ||
1278 | If a recipe with the specified version is not available, a warning | ||
1279 | message will be shown. See :term:`REQUIRED_VERSION` if you want this | ||
1280 | to be an error instead. | ||
1281 | |||
1107 | :term:`PREMIRRORS` | 1282 | :term:`PREMIRRORS` |
1108 | Specifies additional paths from which BitBake gets source code. When | 1283 | Specifies additional paths from which BitBake gets source code. When |
1109 | the build system searches for source code, it first tries the local | 1284 | the build system searches for source code, it first tries the local |
1110 | download directory. If that location fails, the build system tries | 1285 | download directory. If that location fails, the build system tries |
1111 | locations defined by ``PREMIRRORS``, the upstream source, and then | 1286 | locations defined by :term:`PREMIRRORS`, the upstream source, and then |
1112 | locations specified by :term:`MIRRORS` in that order. | 1287 | locations specified by :term:`MIRRORS` in that order. |
1113 | 1288 | ||
1114 | Typically, you would add a specific server for the build system to | 1289 | Typically, you would add a specific server for the build system to |
1115 | attempt before any others by adding something like the following to | 1290 | attempt before any others by adding something like the following to |
1116 | your configuration: :: | 1291 | your configuration:: |
1117 | 1292 | ||
1118 | PREMIRRORS_prepend = "\ | 1293 | PREMIRRORS:prepend = "\ |
1119 | git://.*/.* http://www.yoctoproject.org/sources/ \n \ | 1294 | git://.*/.* http://downloads.yoctoproject.org/mirror/sources/ \ |
1120 | ftp://.*/.* http://www.yoctoproject.org/sources/ \n \ | 1295 | ftp://.*/.* http://downloads.yoctoproject.org/mirror/sources/ \ |
1121 | http://.*/.* http://www.yoctoproject.org/sources/ \n \ | 1296 | http://.*/.* http://downloads.yoctoproject.org/mirror/sources/ \ |
1122 | https://.*/.* http://www.yoctoproject.org/sources/ \n" | 1297 | https://.*/.* http://downloads.yoctoproject.org/mirror/sources/" |
1123 | 1298 | ||
1124 | These changes cause the build system to intercept Git, FTP, HTTP, and | 1299 | These changes cause the build system to intercept Git, FTP, HTTP, and |
1125 | HTTPS requests and direct them to the ``http://`` sources mirror. You can | 1300 | HTTPS requests and direct them to the ``http://`` sources mirror. You can |
@@ -1128,25 +1303,25 @@ overview of their function and contents. | |||
1128 | 1303 | ||
1129 | :term:`PROVIDES` | 1304 | :term:`PROVIDES` |
1130 | A list of aliases by which a particular recipe can be known. By | 1305 | A list of aliases by which a particular recipe can be known. By |
1131 | default, a recipe's own ``PN`` is implicitly already in its | 1306 | default, a recipe's own :term:`PN` is implicitly already in its |
1132 | ``PROVIDES`` list. If a recipe uses ``PROVIDES``, the additional | 1307 | :term:`PROVIDES` list. If a recipe uses :term:`PROVIDES`, the additional |
1133 | aliases are synonyms for the recipe and can be useful satisfying | 1308 | aliases are synonyms for the recipe and can be useful satisfying |
1134 | dependencies of other recipes during the build as specified by | 1309 | dependencies of other recipes during the build as specified by |
1135 | ``DEPENDS``. | 1310 | :term:`DEPENDS`. |
1136 | 1311 | ||
1137 | Consider the following example ``PROVIDES`` statement from a recipe | 1312 | Consider the following example :term:`PROVIDES` statement from a recipe |
1138 | file ``libav_0.8.11.bb``: :: | 1313 | file ``libav_0.8.11.bb``:: |
1139 | 1314 | ||
1140 | PROVIDES += "libpostproc" | 1315 | PROVIDES += "libpostproc" |
1141 | 1316 | ||
1142 | The ``PROVIDES`` statement results in the "libav" recipe also being known | 1317 | The :term:`PROVIDES` statement results in the "libav" recipe also being known |
1143 | as "libpostproc". | 1318 | as "libpostproc". |
1144 | 1319 | ||
1145 | In addition to providing recipes under alternate names, the | 1320 | In addition to providing recipes under alternate names, the |
1146 | ``PROVIDES`` mechanism is also used to implement virtual targets. A | 1321 | :term:`PROVIDES` mechanism is also used to implement virtual targets. A |
1147 | virtual target is a name that corresponds to some particular | 1322 | virtual target is a name that corresponds to some particular |
1148 | functionality (e.g. a Linux kernel). Recipes that provide the | 1323 | functionality (e.g. a Linux kernel). Recipes that provide the |
1149 | functionality in question list the virtual target in ``PROVIDES``. | 1324 | functionality in question list the virtual target in :term:`PROVIDES`. |
1150 | Recipes that depend on the functionality in question can include the | 1325 | Recipes that depend on the functionality in question can include the |
1151 | virtual target in :term:`DEPENDS` to leave the | 1326 | virtual target in :term:`DEPENDS` to leave the |
1152 | choice of provider open. | 1327 | choice of provider open. |
@@ -1158,12 +1333,12 @@ overview of their function and contents. | |||
1158 | :term:`PRSERV_HOST` | 1333 | :term:`PRSERV_HOST` |
1159 | The network based :term:`PR` service host and port. | 1334 | The network based :term:`PR` service host and port. |
1160 | 1335 | ||
1161 | Following is an example of how the ``PRSERV_HOST`` variable is set: :: | 1336 | Following is an example of how the :term:`PRSERV_HOST` variable is set:: |
1162 | 1337 | ||
1163 | PRSERV_HOST = "localhost:0" | 1338 | PRSERV_HOST = "localhost:0" |
1164 | 1339 | ||
1165 | You must set the variable if you want to automatically start a local PR | 1340 | You must set the variable if you want to automatically start a local PR |
1166 | service. You can set ``PRSERV_HOST`` to other values to use a remote PR | 1341 | service. You can set :term:`PRSERV_HOST` to other values to use a remote PR |
1167 | service. | 1342 | service. |
1168 | 1343 | ||
1169 | :term:`PV` | 1344 | :term:`PV` |
@@ -1175,26 +1350,26 @@ overview of their function and contents. | |||
1175 | a package in this list cannot be found during the build, you will get | 1350 | a package in this list cannot be found during the build, you will get |
1176 | a build error. | 1351 | a build error. |
1177 | 1352 | ||
1178 | Because the ``RDEPENDS`` variable applies to packages being built, | 1353 | Because the :term:`RDEPENDS` variable applies to packages being built, |
1179 | you should always use the variable in a form with an attached package | 1354 | you should always use the variable in a form with an attached package |
1180 | name. For example, suppose you are building a development package | 1355 | name. For example, suppose you are building a development package |
1181 | that depends on the ``perl`` package. In this case, you would use the | 1356 | that depends on the ``perl`` package. In this case, you would use the |
1182 | following ``RDEPENDS`` statement: :: | 1357 | following :term:`RDEPENDS` statement:: |
1183 | 1358 | ||
1184 | RDEPENDS_${PN}-dev += "perl" | 1359 | RDEPENDS:${PN}-dev += "perl" |
1185 | 1360 | ||
1186 | In the example, the development package depends on the ``perl`` package. | 1361 | In the example, the development package depends on the ``perl`` package. |
1187 | Thus, the ``RDEPENDS`` variable has the ``${PN}-dev`` package name as part | 1362 | Thus, the :term:`RDEPENDS` variable has the ``${PN}-dev`` package name as part |
1188 | of the variable. | 1363 | of the variable. |
1189 | 1364 | ||
1190 | BitBake supports specifying versioned dependencies. Although the | 1365 | BitBake supports specifying versioned dependencies. Although the |
1191 | syntax varies depending on the packaging format, BitBake hides these | 1366 | syntax varies depending on the packaging format, BitBake hides these |
1192 | differences from you. Here is the general syntax to specify versions | 1367 | differences from you. Here is the general syntax to specify versions |
1193 | with the ``RDEPENDS`` variable: :: | 1368 | with the :term:`RDEPENDS` variable:: |
1194 | 1369 | ||
1195 | RDEPENDS_${PN} = "package (operator version)" | 1370 | RDEPENDS:${PN} = "package (operator version)" |
1196 | 1371 | ||
1197 | For ``operator``, you can specify the following: :: | 1372 | For ``operator``, you can specify the following:: |
1198 | 1373 | ||
1199 | = | 1374 | = |
1200 | < | 1375 | < |
@@ -1203,9 +1378,9 @@ overview of their function and contents. | |||
1203 | >= | 1378 | >= |
1204 | 1379 | ||
1205 | For example, the following sets up a dependency on version 1.2 or | 1380 | For example, the following sets up a dependency on version 1.2 or |
1206 | greater of the package ``foo``: :: | 1381 | greater of the package ``foo``:: |
1207 | 1382 | ||
1208 | RDEPENDS_${PN} = "foo (>= 1.2)" | 1383 | RDEPENDS:${PN} = "foo (>= 1.2)" |
1209 | 1384 | ||
1210 | For information on build-time dependencies, see the :term:`DEPENDS` | 1385 | For information on build-time dependencies, see the :term:`DEPENDS` |
1211 | variable. | 1386 | variable. |
@@ -1214,33 +1389,43 @@ overview of their function and contents. | |||
1214 | The directory in which a local copy of a ``google-repo`` directory is | 1389 | The directory in which a local copy of a ``google-repo`` directory is |
1215 | stored when it is synced. | 1390 | stored when it is synced. |
1216 | 1391 | ||
1392 | :term:`REQUIRED_VERSION` | ||
1393 | If there are multiple versions of a recipe available, this variable | ||
1394 | determines which version should be given preference. :term:`REQUIRED_VERSION` | ||
1395 | works in exactly the same manner as :term:`PREFERRED_VERSION`, except | ||
1396 | that if the specified version is not available then an error message | ||
1397 | is shown and the build fails immediately. | ||
1398 | |||
1399 | If both :term:`REQUIRED_VERSION` and :term:`PREFERRED_VERSION` are set for | ||
1400 | the same recipe, the :term:`REQUIRED_VERSION` value applies. | ||
1401 | |||
1217 | :term:`RPROVIDES` | 1402 | :term:`RPROVIDES` |
1218 | A list of package name aliases that a package also provides. These | 1403 | A list of package name aliases that a package also provides. These |
1219 | aliases are useful for satisfying runtime dependencies of other | 1404 | aliases are useful for satisfying runtime dependencies of other |
1220 | packages both during the build and on the target (as specified by | 1405 | packages both during the build and on the target (as specified by |
1221 | ``RDEPENDS``). | 1406 | :term:`RDEPENDS`). |
1222 | 1407 | ||
1223 | As with all package-controlling variables, you must always use the | 1408 | As with all package-controlling variables, you must always use the |
1224 | variable in conjunction with a package name override. Here is an | 1409 | variable in conjunction with a package name override. Here is an |
1225 | example: :: | 1410 | example:: |
1226 | 1411 | ||
1227 | RPROVIDES_${PN} = "widget-abi-2" | 1412 | RPROVIDES:${PN} = "widget-abi-2" |
1228 | 1413 | ||
1229 | :term:`RRECOMMENDS` | 1414 | :term:`RRECOMMENDS` |
1230 | A list of packages that extends the usability of a package being | 1415 | A list of packages that extends the usability of a package being |
1231 | built. The package being built does not depend on this list of | 1416 | built. The package being built does not depend on this list of |
1232 | packages in order to successfully build, but needs them for the | 1417 | packages in order to successfully build, but needs them for the |
1233 | extended usability. To specify runtime dependencies for packages, see | 1418 | extended usability. To specify runtime dependencies for packages, see |
1234 | the ``RDEPENDS`` variable. | 1419 | the :term:`RDEPENDS` variable. |
1235 | 1420 | ||
1236 | BitBake supports specifying versioned recommends. Although the syntax | 1421 | BitBake supports specifying versioned recommends. Although the syntax |
1237 | varies depending on the packaging format, BitBake hides these | 1422 | varies depending on the packaging format, BitBake hides these |
1238 | differences from you. Here is the general syntax to specify versions | 1423 | differences from you. Here is the general syntax to specify versions |
1239 | with the ``RRECOMMENDS`` variable: :: | 1424 | with the :term:`RRECOMMENDS` variable:: |
1240 | 1425 | ||
1241 | RRECOMMENDS_${PN} = "package (operator version)" | 1426 | RRECOMMENDS:${PN} = "package (operator version)" |
1242 | 1427 | ||
1243 | For ``operator``, you can specify the following: :: | 1428 | For ``operator``, you can specify the following:: |
1244 | 1429 | ||
1245 | = | 1430 | = |
1246 | < | 1431 | < |
@@ -1249,76 +1434,114 @@ overview of their function and contents. | |||
1249 | >= | 1434 | >= |
1250 | 1435 | ||
1251 | For example, the following sets up a recommend on version | 1436 | For example, the following sets up a recommend on version |
1252 | 1.2 or greater of the package ``foo``: :: | 1437 | 1.2 or greater of the package ``foo``:: |
1253 | 1438 | ||
1254 | RRECOMMENDS_${PN} = "foo (>= 1.2)" | 1439 | RRECOMMENDS:${PN} = "foo (>= 1.2)" |
1255 | 1440 | ||
1256 | :term:`SECTION` | 1441 | :term:`SECTION` |
1257 | The section in which packages should be categorized. | 1442 | The section in which packages should be categorized. |
1258 | 1443 | ||
1259 | :term:`SRC_URI` | 1444 | :term:`SRC_URI` |
1260 | The list of source files - local or remote. This variable tells | 1445 | The list of source files --- local or remote. This variable tells |
1261 | BitBake which bits to pull for the build and how to pull them. For | 1446 | BitBake which bits to pull for the build and how to pull them. For |
1262 | example, if the recipe or append file needs to fetch a single tarball | 1447 | example, if the recipe or append file needs to fetch a single tarball |
1263 | from the Internet, the recipe or append file uses a ``SRC_URI`` entry | 1448 | from the Internet, the recipe or append file uses a :term:`SRC_URI` |
1264 | that specifies that tarball. On the other hand, if the recipe or | 1449 | entry that specifies that tarball. On the other hand, if the recipe or |
1265 | append file needs to fetch a tarball and include a custom file, the | 1450 | append file needs to fetch a tarball, apply two patches, and include |
1266 | recipe or append file needs an ``SRC_URI`` variable that specifies | 1451 | a custom file, the recipe or append file needs an :term:`SRC_URI` |
1267 | all those sources. | 1452 | variable that specifies all those sources. |
1268 | 1453 | ||
1269 | The following list explains the available URI protocols: | 1454 | The following list explains the available URI protocols. URI |
1455 | protocols are highly dependent on particular BitBake Fetcher | ||
1456 | submodules. Depending on the fetcher BitBake uses, various URL | ||
1457 | parameters are employed. For specifics on the supported Fetchers, see | ||
1458 | the :ref:`bitbake-user-manual/bitbake-user-manual-fetching:fetchers` | ||
1459 | section. | ||
1270 | 1460 | ||
1271 | - ``file://`` : Fetches files, which are usually files shipped | 1461 | - ``az://``: Fetches files from an Azure Storage account using HTTPS. |
1272 | with the metadata, from the local machine. The path is relative to | ||
1273 | the :term:`FILESPATH` variable. | ||
1274 | 1462 | ||
1275 | - ``bzr://`` : Fetches files from a Bazaar revision control | 1463 | - ``bzr://``: Fetches files from a Bazaar revision control |
1276 | repository. | 1464 | repository. |
1277 | 1465 | ||
1278 | - ``git://`` : Fetches files from a Git revision control | 1466 | - ``ccrc://``: Fetches files from a ClearCase repository. |
1467 | |||
1468 | - ``cvs://``: Fetches files from a CVS revision control | ||
1279 | repository. | 1469 | repository. |
1280 | 1470 | ||
1281 | - ``osc://`` : Fetches files from an OSC (OpenSUSE Build service) | 1471 | - ``file://``: Fetches files, which are usually files shipped |
1282 | revision control repository. | 1472 | with the Metadata, from the local machine. |
1473 | The path is relative to the :term:`FILESPATH` | ||
1474 | variable. Thus, the build system searches, in order, from the | ||
1475 | following directories, which are assumed to be a subdirectories of | ||
1476 | the directory in which the recipe file (``.bb``) or append file | ||
1477 | (``.bbappend``) resides: | ||
1283 | 1478 | ||
1284 | - ``repo://`` : Fetches files from a repo (Git) repository. | 1479 | - ``${BPN}``: the base recipe name without any special suffix |
1480 | or version numbers. | ||
1285 | 1481 | ||
1286 | - ``http://`` : Fetches files from the Internet using HTTP. | 1482 | - ``${BP}`` - ``${BPN}-${PV}``: the base recipe name and |
1483 | version but without any special package name suffix. | ||
1287 | 1484 | ||
1288 | - ``https://`` : Fetches files from the Internet using HTTPS. | 1485 | - ``files``: files within a directory, which is named ``files`` |
1486 | and is also alongside the recipe or append file. | ||
1289 | 1487 | ||
1290 | - ``ftp://`` : Fetches files from the Internet using FTP. | 1488 | - ``ftp://``: Fetches files from the Internet using FTP. |
1291 | 1489 | ||
1292 | - ``cvs://`` : Fetches files from a CVS revision control | 1490 | - ``git://``: Fetches files from a Git revision control |
1293 | repository. | 1491 | repository. |
1294 | 1492 | ||
1295 | - ``hg://`` : Fetches files from a Mercurial (``hg``) revision | 1493 | - ``gitsm://``: Fetches submodules from a Git revision control |
1494 | repository. | ||
1495 | |||
1496 | - ``hg://``: Fetches files from a Mercurial (``hg``) revision | ||
1296 | control repository. | 1497 | control repository. |
1297 | 1498 | ||
1298 | - ``p4://`` : Fetches files from a Perforce (``p4``) revision | 1499 | - ``http://``: Fetches files from the Internet using HTTP. |
1500 | |||
1501 | - ``https://``: Fetches files from the Internet using HTTPS. | ||
1502 | |||
1503 | - ``npm://``: Fetches JavaScript modules from a registry. | ||
1504 | |||
1505 | - ``osc://``: Fetches files from an OSC (OpenSUSE Build service) | ||
1506 | revision control repository. | ||
1507 | |||
1508 | - ``p4://``: Fetches files from a Perforce (``p4``) revision | ||
1299 | control repository. | 1509 | control repository. |
1300 | 1510 | ||
1301 | - ``ssh://`` : Fetches files from a secure shell. | 1511 | - ``repo://``: Fetches files from a repo (Git) repository. |
1512 | |||
1513 | - ``ssh://``: Fetches files from a secure shell. | ||
1302 | 1514 | ||
1303 | - ``svn://`` : Fetches files from a Subversion (``svn``) revision | 1515 | - ``svn://``: Fetches files from a Subversion (``svn``) revision |
1304 | control repository. | 1516 | control repository. |
1305 | 1517 | ||
1306 | Here are some additional options worth mentioning: | 1518 | Here are some additional options worth mentioning: |
1307 | 1519 | ||
1308 | - ``unpack`` : Controls whether or not to unpack the file if it is | 1520 | - ``downloadfilename``: Specifies the filename used when storing |
1309 | an archive. The default action is to unpack the file. | 1521 | the downloaded file. |
1522 | |||
1523 | - ``name``: Specifies a name to be used for association with | ||
1524 | :term:`SRC_URI` checksums or :term:`SRCREV` when you have more than one | ||
1525 | file or git repository specified in :term:`SRC_URI`. For example:: | ||
1526 | |||
1527 | SRC_URI = "git://example.com/foo.git;branch=main;name=first \ | ||
1528 | git://example.com/bar.git;branch=main;name=second \ | ||
1529 | http://example.com/file.tar.gz;name=third" | ||
1310 | 1530 | ||
1311 | - ``subdir`` : Places the file (or extracts its contents) into the | 1531 | SRCREV_first = "f1d2d2f924e986ac86fdf7b36c94bcdf32beec15" |
1532 | SRCREV_second = "e242ed3bffccdf271b7fbaf34ed72d089537b42f" | ||
1533 | SRC_URI[third.sha256sum] = "13550350a8681c84c861aac2e5b440161c2b33a3e4f302ac680ca5b686de48de" | ||
1534 | |||
1535 | - ``subdir``: Places the file (or extracts its contents) into the | ||
1312 | specified subdirectory. This option is useful for unusual tarballs | 1536 | specified subdirectory. This option is useful for unusual tarballs |
1313 | or other archives that do not have their files already in a | 1537 | or other archives that do not have their files already in a |
1314 | subdirectory within the archive. | 1538 | subdirectory within the archive. |
1315 | 1539 | ||
1316 | - ``name`` : Specifies a name to be used for association with | 1540 | - ``subpath``: Limits the checkout to a specific subpath of the |
1317 | ``SRC_URI`` checksums when you have more than one file specified | 1541 | tree when using the Git fetcher is used. |
1318 | in ``SRC_URI``. | ||
1319 | 1542 | ||
1320 | - ``downloadfilename`` : Specifies the filename used when storing | 1543 | - ``unpack``: Controls whether or not to unpack the file if it is |
1321 | the downloaded file. | 1544 | an archive. The default action is to unpack the file. |
1322 | 1545 | ||
1323 | :term:`SRCDATE` | 1546 | :term:`SRCDATE` |
1324 | The date of the source code used to build the package. This variable | 1547 | The date of the source code used to build the package. This variable |
@@ -1330,7 +1553,7 @@ overview of their function and contents. | |||
1330 | variable applies only when using Subversion, Git, Mercurial and | 1553 | variable applies only when using Subversion, Git, Mercurial and |
1331 | Bazaar. If you want to build a fixed revision and you want to avoid | 1554 | Bazaar. If you want to build a fixed revision and you want to avoid |
1332 | performing a query on the remote repository every time BitBake parses | 1555 | performing a query on the remote repository every time BitBake parses |
1333 | your recipe, you should specify a ``SRCREV`` that is a full revision | 1556 | your recipe, you should specify a :term:`SRCREV` that is a full revision |
1334 | identifier and not just a tag. | 1557 | identifier and not just a tag. |
1335 | 1558 | ||
1336 | :term:`SRCREV_FORMAT` | 1559 | :term:`SRCREV_FORMAT` |
@@ -1339,10 +1562,10 @@ overview of their function and contents. | |||
1339 | :term:`SRC_URI`. | 1562 | :term:`SRC_URI`. |
1340 | 1563 | ||
1341 | The system needs help constructing these values under these | 1564 | The system needs help constructing these values under these |
1342 | circumstances. Each component in the ``SRC_URI`` is assigned a name | 1565 | circumstances. Each component in the :term:`SRC_URI` is assigned a name |
1343 | and these are referenced in the ``SRCREV_FORMAT`` variable. Consider | 1566 | and these are referenced in the :term:`SRCREV_FORMAT` variable. Consider |
1344 | an example with URLs named "machine" and "meta". In this case, | 1567 | an example with URLs named "machine" and "meta". In this case, |
1345 | ``SRCREV_FORMAT`` could look like "machine_meta" and those names | 1568 | :term:`SRCREV_FORMAT` could look like "machine_meta" and those names |
1346 | would have the SCM versions substituted into each position. Only one | 1569 | would have the SCM versions substituted into each position. Only one |
1347 | ``AUTOINC`` placeholder is added and if needed. And, this placeholder | 1570 | ``AUTOINC`` placeholder is added and if needed. And, this placeholder |
1348 | is placed at the start of the returned string. | 1571 | is placed at the start of the returned string. |
@@ -1354,7 +1577,7 @@ overview of their function and contents. | |||
1354 | 1577 | ||
1355 | :term:`STAMPCLEAN` | 1578 | :term:`STAMPCLEAN` |
1356 | Specifies the base path used to create recipe stamp files. Unlike the | 1579 | Specifies the base path used to create recipe stamp files. Unlike the |
1357 | :term:`STAMP` variable, ``STAMPCLEAN`` can contain | 1580 | :term:`STAMP` variable, :term:`STAMPCLEAN` can contain |
1358 | wildcards to match the range of files a clean operation should | 1581 | wildcards to match the range of files a clean operation should |
1359 | remove. BitBake uses a clean operation to remove any other stamps it | 1582 | remove. BitBake uses a clean operation to remove any other stamps it |
1360 | should be removing when creating a new stamp. | 1583 | should be removing when creating a new stamp. |