diff options
6 files changed, 151 insertions, 151 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 84d65fa9c3..a6ef90db12 100644 --- a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-execution.rst +++ b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-execution.rst | |||
@@ -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. |
@@ -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,7 +135,7 @@ 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 |
@@ -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,7 +201,7 @@ 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 |
@@ -212,7 +212,7 @@ are used to set the variables :term:`PN` and | |||
212 | PV = "${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE', False),d)[1] or '1.0'}" | 212 | PV = "${@bb.parse.BBHandler.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 |
@@ -260,21 +260,21 @@ Providers | |||
260 | 260 | ||
261 | 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 |
262 | 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 |
263 | build the target. BitBake looks through the ``PROVIDES`` list for each | 263 | build the target. BitBake looks through the :term:`PROVIDES` list for each |
264 | 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 |
265 | recipe can be known. Each recipe's ``PROVIDES`` list is created | 265 | recipe can be known. Each recipe's :term:`PROVIDES` list is created |
266 | implicitly through the recipe's :term:`PN` variable and | 266 | implicitly through the recipe's :term:`PN` variable and |
267 | explicitly through the recipe's :term:`PROVIDES` | 267 | explicitly through the recipe's :term:`PROVIDES` |
268 | variable, which is optional. | 268 | variable, which is optional. |
269 | 269 | ||
270 | When a recipe uses ``PROVIDES``, that recipe's functionality can be | 270 | When a recipe uses :term:`PROVIDES`, that recipe's functionality can be |
271 | 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` |
272 | 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`` |
273 | contained the following:: | 273 | contained the following:: |
274 | 274 | ||
275 | PROVIDES += "fullkeyboard" | 275 | PROVIDES += "fullkeyboard" |
276 | 276 | ||
277 | The ``PROVIDES`` | 277 | The :term:`PROVIDES` |
278 | list for this recipe becomes "keyboard", which is implicit, and | 278 | list for this recipe becomes "keyboard", which is implicit, and |
279 | "fullkeyboard", which is explicit. Consequently, the functionality found | 279 | "fullkeyboard", which is explicit. Consequently, the functionality found |
280 | 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. |
@@ -284,12 +284,12 @@ in ``keyboard_1.0.bb`` can be found under two different names. | |||
284 | Preferences | 284 | Preferences |
285 | =========== | 285 | =========== |
286 | 286 | ||
287 | 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 |
288 | target's recipes. Because targets might have multiple providers, BitBake | 288 | target's recipes. Because targets might have multiple providers, BitBake |
289 | needs to prioritize providers by determining provider preferences. | 289 | needs to prioritize providers by determining provider preferences. |
290 | 290 | ||
291 | A common example in which a target has multiple providers is | 291 | A common example in which a target has multiple providers is |
292 | "virtual/kernel", which is on the ``PROVIDES`` list for each kernel | 292 | "virtual/kernel", which is on the :term:`PROVIDES` list for each kernel |
293 | 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 |
294 | line similar to the following in the machine configuration file:: | 294 | line similar to the following in the machine configuration file:: |
295 | 295 | ||
@@ -309,10 +309,10 @@ specify a particular version. You can influence the order by using the | |||
309 | :term:`DEFAULT_PREFERENCE` variable. | 309 | :term:`DEFAULT_PREFERENCE` variable. |
310 | 310 | ||
311 | By default, files have a preference of "0". Setting | 311 | By default, files have a preference of "0". Setting |
312 | ``DEFAULT_PREFERENCE`` to "-1" makes the recipe unlikely to be used | 312 | :term:`DEFAULT_PREFERENCE` to "-1" makes the recipe unlikely to be used |
313 | unless it is explicitly referenced. Setting ``DEFAULT_PREFERENCE`` to | 313 | unless it is explicitly referenced. Setting :term:`DEFAULT_PREFERENCE` to |
314 | "1" makes it likely the recipe is used. ``PREFERRED_VERSION`` overrides | 314 | "1" makes it likely the recipe is used. :term:`PREFERRED_VERSION` overrides |
315 | any ``DEFAULT_PREFERENCE`` setting. ``DEFAULT_PREFERENCE`` is often used | 315 | any :term:`DEFAULT_PREFERENCE` setting. :term:`DEFAULT_PREFERENCE` is often used |
316 | to mark newer and more experimental recipe versions until they have | 316 | to mark newer and more experimental recipe versions until they have |
317 | undergone sufficient testing to be considered stable. | 317 | undergone sufficient testing to be considered stable. |
318 | 318 | ||
@@ -394,7 +394,7 @@ ready to run, those tasks have all their dependencies met, and the | |||
394 | thread threshold has not been exceeded. | 394 | thread threshold has not been exceeded. |
395 | 395 | ||
396 | 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 |
397 | properly setting the ``BB_NUMBER_THREADS`` variable. | 397 | properly setting the :term:`BB_NUMBER_THREADS` variable. |
398 | 398 | ||
399 | As each task completes, a timestamp is written to the directory | 399 | As each task completes, a timestamp is written to the directory |
400 | specified by the :term:`STAMP` variable. On subsequent | 400 | specified by the :term:`STAMP` variable. On subsequent |
@@ -561,7 +561,7 @@ behavior is unchanged from previous versions. ``OE-Core`` uses the | |||
561 | 561 | ||
562 | BB_SIGNATURE_HANDLER ?= "OEBasicHash" | 562 | BB_SIGNATURE_HANDLER ?= "OEBasicHash" |
563 | 563 | ||
564 | The "OEBasicHash" ``BB_SIGNATURE_HANDLER`` is the same as the "OEBasic" | 564 | The "OEBasicHash" :term:`BB_SIGNATURE_HANDLER` is the same as the "OEBasic" |
565 | version but adds the task hash to the stamp files. This results in any | 565 | version but adds the task hash to the stamp files. This results in any |
566 | metadata change that changes the task hash, automatically causing the | 566 | metadata change that changes the task hash, automatically causing the |
567 | task to be run again. This removes the need to bump | 567 | task to be run again. This removes the need to bump |
@@ -581,7 +581,7 @@ the build. This information includes: | |||
581 | - ``BBHASHDEPS_``\ *filename:taskname*: The task dependencies for | 581 | - ``BBHASHDEPS_``\ *filename:taskname*: The task dependencies for |
582 | each task. | 582 | each task. |
583 | 583 | ||
584 | - ``BB_TASKHASH``: The hash of the currently running task. | 584 | - :term:`BB_TASKHASH`: The hash of the currently running task. |
585 | 585 | ||
586 | It is worth noting that BitBake's "-S" option lets you debug BitBake's | 586 | It is worth noting that BitBake's "-S" option lets you debug BitBake's |
587 | processing of signatures. The options passed to -S allow different | 587 | processing of signatures. The options passed to -S allow different |
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 bd1fb4fc74..593de61f24 100644 --- a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-fetching.rst +++ b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-fetching.rst | |||
@@ -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,14 +64,14 @@ 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 | http://git.yoctoproject.org/git/poky;protocol=git |
@@ -110,14 +110,14 @@ 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 | ||
@@ -129,7 +129,7 @@ shows how you name the URIs:: | |||
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 | ||
@@ -438,7 +438,7 @@ Here are some example URLs:: | |||
438 | .. note:: | 438 | .. note:: |
439 | 439 | ||
440 | Specifying passwords directly in ``git://`` urls is not supported. | 440 | Specifying passwords directly in ``git://`` urls is not supported. |
441 | There are several reasons: ``SRC_URI`` is often written out to logs and | 441 | There are several reasons: :term:`SRC_URI` is often written out to logs and |
442 | other places, and that could easily leak passwords; it is also all too | 442 | other places, and that could easily leak passwords; it is also all too |
443 | easy to share metadata without removing passwords. SSH keys, ``~/.netrc`` | 443 | easy to share metadata without removing passwords. SSH keys, ``~/.netrc`` |
444 | and ``~/.ssh/config`` files can be used as alternatives. | 444 | and ``~/.ssh/config`` files can be used as alternatives. |
@@ -487,7 +487,7 @@ To use this fetcher, make sure your recipe has proper | |||
487 | The fetcher uses the ``rcleartool`` or | 487 | The fetcher uses the ``rcleartool`` or |
488 | ``cleartool`` remote client, depending on which one is available. | 488 | ``cleartool`` remote client, depending on which one is available. |
489 | 489 | ||
490 | Following are options for the ``SRC_URI`` statement: | 490 | Following are options for the :term:`SRC_URI` statement: |
491 | 491 | ||
492 | - *vob*: The name, which must include the prepending "/" character, | 492 | - *vob*: The name, which must include the prepending "/" character, |
493 | of the ClearCase VOB. This option is required. | 493 | of the ClearCase VOB. This option is required. |
@@ -549,7 +549,7 @@ password if you do not wish to keep those values in a recipe itself. If | |||
549 | you choose not to use ``P4CONFIG``, or to explicitly set variables that | 549 | you choose not to use ``P4CONFIG``, or to explicitly set variables that |
550 | ``P4CONFIG`` can contain, you can specify the ``P4PORT`` value, which is | 550 | ``P4CONFIG`` can contain, you can specify the ``P4PORT`` value, which is |
551 | the server's URL and port number, and you can specify a username and | 551 | the server's URL and port number, and you can specify a username and |
552 | password directly in your recipe within ``SRC_URI``. | 552 | password directly in your recipe within :term:`SRC_URI`. |
553 | 553 | ||
554 | Here is an example that relies on ``P4CONFIG`` to specify the server URL | 554 | Here is an example that relies on ``P4CONFIG`` to specify the server URL |
555 | and port, username, and password, and fetches the Head Revision:: | 555 | and port, username, and password, and fetches the Head Revision:: |
@@ -680,4 +680,4 @@ submodules. However, you might find the code helpful and readable. | |||
680 | Auto Revisions | 680 | Auto Revisions |
681 | ============== | 681 | ============== |
682 | 682 | ||
683 | We need to document ``AUTOREV`` and ``SRCREV_FORMAT`` here. | 683 | 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 a9c33709ab..c5a4ce60bf 100644 --- a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-hello.rst +++ b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-hello.rst | |||
@@ -145,23 +145,23 @@ Following is the complete "Hello World" example. | |||
145 | 145 | ||
146 | The majority of this output is specific to environment variables that | 146 | The majority of this output is specific to environment variables that |
147 | are not directly relevant to BitBake. However, the very first | 147 | are not directly relevant to BitBake. However, the very first |
148 | message regarding the ``BBPATH`` variable and the | 148 | message regarding the :term:`BBPATH` variable and the |
149 | ``conf/bblayers.conf`` file is relevant. | 149 | ``conf/bblayers.conf`` file is relevant. |
150 | 150 | ||
151 | When you run BitBake, it begins looking for metadata files. The | 151 | When you run BitBake, it begins looking for metadata files. The |
152 | :term:`BBPATH` variable is what tells BitBake where | 152 | :term:`BBPATH` variable is what tells BitBake where |
153 | to look for those files. ``BBPATH`` is not set and you need to set | 153 | 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 | 154 | it. Without :term:`BBPATH`, BitBake cannot find any configuration files |
155 | (``.conf``) or recipe files (``.bb``) at all. BitBake also cannot | 155 | (``.conf``) or recipe files (``.bb``) at all. BitBake also cannot |
156 | find the ``bitbake.conf`` file. | 156 | find the ``bitbake.conf`` file. |
157 | 157 | ||
158 | #. **Setting BBPATH:** For this example, you can set ``BBPATH`` in | 158 | #. **Setting BBPATH:** For this example, you can set :term:`BBPATH` in |
159 | the same manner that you set ``PATH`` earlier in the appendix. You | 159 | 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 | 160 | should realize, though, that it is much more flexible to set the |
161 | ``BBPATH`` variable up in a configuration file for each project. | 161 | :term:`BBPATH` variable up in a configuration file for each project. |
162 | 162 | ||
163 | From your shell, enter the following commands to set and export the | 163 | From your shell, enter the following commands to set and export the |
164 | ``BBPATH`` variable:: | 164 | :term:`BBPATH` variable:: |
165 | 165 | ||
166 | $ BBPATH="projectdirectory" | 166 | $ BBPATH="projectdirectory" |
167 | $ export BBPATH | 167 | $ export BBPATH |
@@ -175,7 +175,7 @@ Following is the complete "Hello World" example. | |||
175 | ("~") character as BitBake does not expand that character as the | 175 | ("~") character as BitBake does not expand that character as the |
176 | shell would. | 176 | shell would. |
177 | 177 | ||
178 | #. **Run BitBake:** Now that you have ``BBPATH`` defined, run the | 178 | #. **Run BitBake:** Now that you have :term:`BBPATH` defined, run the |
179 | ``bitbake`` command again:: | 179 | ``bitbake`` command again:: |
180 | 180 | ||
181 | $ bitbake | 181 | $ bitbake |
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 b3cea61fff..eb1406652a 100644 --- a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-intro.rst +++ b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-intro.rst | |||
@@ -537,7 +537,7 @@ current working directory: | |||
537 | To stop depending on common depends, use the "-I" depend option and | 537 | To stop depending on common depends, use the "-I" depend option and |
538 | BitBake omits them from the graph. Leaving this information out can | 538 | BitBake omits them from the graph. Leaving this information out can |
539 | produce more readable graphs. This way, you can remove from the graph | 539 | produce more readable graphs. This way, you can remove from the graph |
540 | ``DEPENDS`` from inherited classes such as ``base.bbclass``. | 540 | :term:`DEPENDS` from inherited classes such as ``base.bbclass``. |
541 | 541 | ||
542 | Here are two examples that create dependency graphs. The second example | 542 | Here are two examples that create dependency graphs. The second example |
543 | omits depends common in OpenEmbedded from the graph:: | 543 | omits depends common in OpenEmbedded from the graph:: |
@@ -564,7 +564,7 @@ for two separate targets: | |||
564 | .. image:: figures/bb_multiconfig_files.png | 564 | .. image:: figures/bb_multiconfig_files.png |
565 | :align: center | 565 | :align: center |
566 | 566 | ||
567 | The reason for this required file hierarchy is because the ``BBPATH`` | 567 | The reason for this required file hierarchy is because the :term:`BBPATH` |
568 | variable is not constructed until the layers are parsed. Consequently, | 568 | variable is not constructed until the layers are parsed. Consequently, |
569 | using the configuration file as a pre-configuration file is not possible | 569 | using the configuration file as a pre-configuration file is not possible |
570 | unless it is located in the current working directory. | 570 | unless it is located in the current working directory. |
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 20c330e6ac..3e14163ebe 100644 --- a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst +++ b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst | |||
@@ -225,7 +225,7 @@ immediately, rather than when the variable is actually used:: | |||
225 | C := "${C}append" | 225 | C := "${C}append" |
226 | 226 | ||
227 | In this example, ``A`` contains "test 123", even though the final value | 227 | 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 | 228 | of :term:`T` is "456". The variable :term:`B` will end up containing "456 |
229 | cvalappend". This is because references to undefined variables are | 229 | cvalappend". This is because references to undefined variables are |
230 | preserved as is during (immediate)expansion. This is in contrast to GNU | 230 | preserved as is during (immediate)expansion. This is in contrast to GNU |
231 | Make, where undefined variables expand to nothing. The variable ``C`` | 231 | Make, where undefined variables expand to nothing. The variable ``C`` |
@@ -248,7 +248,7 @@ examples:: | |||
248 | C = "cval" | 248 | C = "cval" |
249 | C =+ "test" | 249 | C =+ "test" |
250 | 250 | ||
251 | The variable ``B`` contains "bval additionaldata" and ``C`` contains "test | 251 | The variable :term:`B` contains "bval additionaldata" and ``C`` contains "test |
252 | cval". | 252 | cval". |
253 | 253 | ||
254 | .. _appending-and-prepending-without-spaces: | 254 | .. _appending-and-prepending-without-spaces: |
@@ -267,7 +267,7 @@ examples:: | |||
267 | C = "cval" | 267 | C = "cval" |
268 | C =. "test" | 268 | C =. "test" |
269 | 269 | ||
270 | The variable ``B`` contains "bvaladditionaldata" and ``C`` contains | 270 | The variable :term:`B` contains "bvaladditionaldata" and ``C`` contains |
271 | "testcval". | 271 | "testcval". |
272 | 272 | ||
273 | Appending and Prepending (Override Style Syntax) | 273 | Appending and Prepending (Override Style Syntax) |
@@ -287,7 +287,7 @@ rather than being immediately applied. Here are some examples:: | |||
287 | D = "dval" | 287 | D = "dval" |
288 | D_append = "additional data" | 288 | D_append = "additional data" |
289 | 289 | ||
290 | The variable ``B`` | 290 | The variable :term:`B` |
291 | becomes "bval additional data" and ``C`` becomes "additional data cval". | 291 | becomes "bval additional data" and ``C`` becomes "additional data cval". |
292 | The variable ``D`` becomes "dvaladditional data". | 292 | The variable ``D`` becomes "dvaladditional data". |
293 | 293 | ||
@@ -496,14 +496,14 @@ Conditional Syntax (Overrides) | |||
496 | 496 | ||
497 | BitBake uses :term:`OVERRIDES` to control what | 497 | BitBake uses :term:`OVERRIDES` to control what |
498 | variables are overridden after BitBake parses recipes and configuration | 498 | variables are overridden after BitBake parses recipes and configuration |
499 | files. This section describes how you can use ``OVERRIDES`` as | 499 | files. This section describes how you can use :term:`OVERRIDES` as |
500 | conditional metadata, talks about key expansion in relationship to | 500 | conditional metadata, talks about key expansion in relationship to |
501 | ``OVERRIDES``, and provides some examples to help with understanding. | 501 | :term:`OVERRIDES`, and provides some examples to help with understanding. |
502 | 502 | ||
503 | Conditional Metadata | 503 | Conditional Metadata |
504 | -------------------- | 504 | -------------------- |
505 | 505 | ||
506 | You can use ``OVERRIDES`` to conditionally select a specific version of | 506 | 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 | 507 | a variable and to conditionally append or prepend the value of a |
508 | variable. | 508 | variable. |
509 | 509 | ||
@@ -513,10 +513,10 @@ variable. | |||
513 | underscores are not permitted in override names as they are used to | 513 | underscores are not permitted in override names as they are used to |
514 | separate overrides from each other and from the variable name. | 514 | separate overrides from each other and from the variable name. |
515 | 515 | ||
516 | - *Selecting a Variable:* The ``OVERRIDES`` variable is a | 516 | - *Selecting a Variable:* The :term:`OVERRIDES` variable is a |
517 | colon-character-separated list that contains items for which you want | 517 | colon-character-separated list that contains items for which you want |
518 | to satisfy conditions. Thus, if you have a variable that is | 518 | to satisfy conditions. Thus, if you have a variable that is |
519 | conditional on "arm", and "arm" is in ``OVERRIDES``, then the | 519 | conditional on "arm", and "arm" is in :term:`OVERRIDES`, then the |
520 | "arm"-specific version of the variable is used rather than the | 520 | "arm"-specific version of the variable is used rather than the |
521 | non-conditional version. Here is an example:: | 521 | non-conditional version. Here is an example:: |
522 | 522 | ||
@@ -525,7 +525,7 @@ variable. | |||
525 | TEST_os = "osspecific" | 525 | TEST_os = "osspecific" |
526 | TEST_nooverride = "othercondvalue" | 526 | TEST_nooverride = "othercondvalue" |
527 | 527 | ||
528 | In this example, the ``OVERRIDES`` | 528 | In this example, the :term:`OVERRIDES` |
529 | variable lists three overrides: "architecture", "os", and "machine". | 529 | variable lists three overrides: "architecture", "os", and "machine". |
530 | The variable ``TEST`` by itself has a default value of "default". You | 530 | The variable ``TEST`` by itself has a default value of "default". You |
531 | select the os-specific version of the ``TEST`` variable by appending | 531 | select the os-specific version of the ``TEST`` variable by appending |
@@ -547,13 +547,13 @@ variable. | |||
547 | 547 | ||
548 | - *Appending and Prepending:* BitBake also supports append and prepend | 548 | - *Appending and Prepending:* BitBake also supports append and prepend |
549 | operations to variable values based on whether a specific item is | 549 | operations to variable values based on whether a specific item is |
550 | listed in ``OVERRIDES``. Here is an example:: | 550 | listed in :term:`OVERRIDES`. Here is an example:: |
551 | 551 | ||
552 | DEPENDS = "glibc ncurses" | 552 | DEPENDS = "glibc ncurses" |
553 | OVERRIDES = "machine:local" | 553 | OVERRIDES = "machine:local" |
554 | DEPENDS_append_machine = "libmad" | 554 | DEPENDS_append_machine = "libmad" |
555 | 555 | ||
556 | In this example, ``DEPENDS`` becomes "glibc ncurses libmad". | 556 | In this example, :term:`DEPENDS` becomes "glibc ncurses libmad". |
557 | 557 | ||
558 | Again, using an OpenEmbedded metadata-based kernel recipe file as an | 558 | Again, using an OpenEmbedded metadata-based kernel recipe file as an |
559 | example, the following lines will conditionally append to the | 559 | example, the following lines will conditionally append to the |
@@ -627,7 +627,7 @@ not been applied yet, ``A_foo`` is set to "X" due to the append and | |||
627 | ``A`` simply equals "Z". | 627 | ``A`` simply equals "Z". |
628 | 628 | ||
629 | Applying overrides, however, changes things. Since "foo" is listed in | 629 | Applying overrides, however, changes things. Since "foo" is listed in |
630 | ``OVERRIDES``, the conditional variable ``A`` is replaced with the "foo" | 630 | :term:`OVERRIDES`, the conditional variable ``A`` is replaced with the "foo" |
631 | version, which is equal to "X". So effectively, ``A_foo`` replaces | 631 | version, which is equal to "X". So effectively, ``A_foo`` replaces |
632 | ``A``. | 632 | ``A``. |
633 | 633 | ||
@@ -686,7 +686,7 @@ share the task. | |||
686 | 686 | ||
687 | This section presents the mechanisms BitBake provides to allow you to | 687 | This section presents the mechanisms BitBake provides to allow you to |
688 | share functionality between recipes. Specifically, the mechanisms | 688 | share functionality between recipes. Specifically, the mechanisms |
689 | include ``include``, ``inherit``, ``INHERIT``, and ``require`` | 689 | include ``include``, ``inherit``, :term:`INHERIT`, and ``require`` |
690 | directives. | 690 | directives. |
691 | 691 | ||
692 | Locating Include and Class Files | 692 | Locating Include and Class Files |
@@ -702,7 +702,7 @@ current directory for ``include`` and ``require`` directives. | |||
702 | 702 | ||
703 | In order for include and class files to be found by BitBake, they need | 703 | 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 | 704 | to be located in a "classes" subdirectory that can be found in |
705 | ``BBPATH``. | 705 | :term:`BBPATH`. |
706 | 706 | ||
707 | ``inherit`` Directive | 707 | ``inherit`` Directive |
708 | --------------------- | 708 | --------------------- |
@@ -725,7 +725,7 @@ functionality for using Autotools that could be shared across recipes:: | |||
725 | inherit autotools | 725 | inherit autotools |
726 | 726 | ||
727 | In this case, BitBake would search for the directory | 727 | In this case, BitBake would search for the directory |
728 | ``classes/autotools.bbclass`` in ``BBPATH``. | 728 | ``classes/autotools.bbclass`` in :term:`BBPATH`. |
729 | 729 | ||
730 | .. note:: | 730 | .. note:: |
731 | 731 | ||
@@ -780,7 +780,7 @@ BitBake understands the ``include`` directive. This directive causes | |||
780 | BitBake to parse whatever file you specify, and to insert that file at | 780 | 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 | 781 | 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, | 782 | that if the path specified on the include line is a relative path, |
783 | BitBake locates the first file it can find within ``BBPATH``. | 783 | BitBake locates the first file it can find within :term:`BBPATH`. |
784 | 784 | ||
785 | The include directive is a more generic method of including | 785 | 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>` | 786 | functionality as compared to the :ref:`inherit <bitbake-user-manual/bitbake-user-manual-metadata:\`\`inherit\`\` directive>` |
@@ -822,7 +822,7 @@ does not suit a ``.bbclass`` file. | |||
822 | 822 | ||
823 | Similar to how BitBake handles :ref:`include <bitbake-user-manual/bitbake-user-manual-metadata:\`\`include\`\` directive>`, if | 823 | 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 | 824 | the path specified on the require line is a relative path, BitBake |
825 | locates the first file it can find within ``BBPATH``. | 825 | locates the first file it can find within :term:`BBPATH`. |
826 | 826 | ||
827 | As an example, suppose you have two versions of a recipe (e.g. | 827 | 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 | 828 | ``foo_1.2.2.bb`` and ``foo_2.0.0.bb``) where each version contains some |
@@ -851,7 +851,7 @@ As an example, suppose you needed to inherit a class file called | |||
851 | This configuration directive causes the named class to be inherited at | 851 | This configuration directive causes the named class to be inherited at |
852 | the point of the directive during parsing. As with the ``inherit`` | 852 | the point of the directive during parsing. As with the ``inherit`` |
853 | directive, the ``.bbclass`` file must be located in a "classes" | 853 | directive, the ``.bbclass`` file must be located in a "classes" |
854 | subdirectory in one of the directories specified in ``BBPATH``. | 854 | subdirectory in one of the directories specified in :term:`BBPATH`. |
855 | 855 | ||
856 | .. note:: | 856 | .. note:: |
857 | 857 | ||
@@ -1015,7 +1015,7 @@ is an example:: | |||
1015 | SOMECONDITION = "1" | 1015 | SOMECONDITION = "1" |
1016 | DEPENDS = "${@get_depends(d)}" | 1016 | DEPENDS = "${@get_depends(d)}" |
1017 | 1017 | ||
1018 | This would result in ``DEPENDS`` containing ``dependencywithcond``. | 1018 | This would result in :term:`DEPENDS` containing ``dependencywithcond``. |
1019 | 1019 | ||
1020 | Here are some things to know about Python functions: | 1020 | Here are some things to know about Python functions: |
1021 | 1021 | ||
@@ -1382,7 +1382,7 @@ Sometimes, it is useful to be able to obtain information from the | |||
1382 | original execution environment. BitBake saves a copy of the original | 1382 | original execution environment. BitBake saves a copy of the original |
1383 | environment into a special variable named :term:`BB_ORIGENV`. | 1383 | environment into a special variable named :term:`BB_ORIGENV`. |
1384 | 1384 | ||
1385 | The ``BB_ORIGENV`` variable returns a datastore object that can be | 1385 | The :term:`BB_ORIGENV` variable returns a datastore object that can be |
1386 | queried using the standard datastore operators such as | 1386 | queried using the standard datastore operators such as |
1387 | ``getVar(, False)``. The datastore object is useful, for example, to | 1387 | ``getVar(, False)``. The datastore object is useful, for example, to |
1388 | find the original ``DISPLAY`` variable. Here is an example:: | 1388 | find the original ``DISPLAY`` variable. Here is an example:: |
@@ -1467,7 +1467,7 @@ functionality of the task: | |||
1467 | can result in unpredictable behavior. | 1467 | can result in unpredictable behavior. |
1468 | 1468 | ||
1469 | - Setting the varflag to a value greater than the value used in | 1469 | - Setting the varflag to a value greater than the value used in |
1470 | the ``BB_NUMBER_THREADS`` variable causes ``number_threads`` to | 1470 | the :term:`BB_NUMBER_THREADS` variable causes ``number_threads`` to |
1471 | have no effect. | 1471 | have no effect. |
1472 | 1472 | ||
1473 | - ``[postfuncs]``: List of functions to call after the completion of | 1473 | - ``[postfuncs]``: List of functions to call after the completion of |
@@ -1537,7 +1537,7 @@ intent is to make it easy to do things like email notification on build | |||
1537 | failures. | 1537 | failures. |
1538 | 1538 | ||
1539 | Following is an example event handler that prints the name of the event | 1539 | Following is an example event handler that prints the name of the event |
1540 | and the content of the ``FILE`` variable:: | 1540 | and the content of the :term:`FILE` variable:: |
1541 | 1541 | ||
1542 | addhandler myclass_eventhandler | 1542 | addhandler myclass_eventhandler |
1543 | python myclass_eventhandler() { | 1543 | python myclass_eventhandler() { |
@@ -1576,7 +1576,7 @@ might have an interest in viewing: | |||
1576 | 1576 | ||
1577 | - ``bb.event.ConfigParsed()``: Fired when the base configuration; which | 1577 | - ``bb.event.ConfigParsed()``: Fired when the base configuration; which |
1578 | consists of ``bitbake.conf``, ``base.bbclass`` and any global | 1578 | consists of ``bitbake.conf``, ``base.bbclass`` and any global |
1579 | ``INHERIT`` statements; has been parsed. You can see multiple such | 1579 | :term:`INHERIT` statements; has been parsed. You can see multiple such |
1580 | events when each of the workers parse the base configuration or if | 1580 | events when each of the workers parse the base configuration or if |
1581 | the server changes configuration and reparses. Any given datastore | 1581 | the server changes configuration and reparses. Any given datastore |
1582 | only has one such event executed against it, however. If | 1582 | only has one such event executed against it, however. If |
@@ -1733,13 +1733,13 @@ Build Dependencies | |||
1733 | 1733 | ||
1734 | BitBake uses the :term:`DEPENDS` variable to manage | 1734 | BitBake uses the :term:`DEPENDS` variable to manage |
1735 | build time dependencies. The ``[deptask]`` varflag for tasks signifies | 1735 | build time dependencies. The ``[deptask]`` varflag for tasks signifies |
1736 | the task of each item listed in ``DEPENDS`` that must complete before | 1736 | the task of each item listed in :term:`DEPENDS` that must complete before |
1737 | that task can be executed. Here is an example:: | 1737 | that task can be executed. Here is an example:: |
1738 | 1738 | ||
1739 | do_configure[deptask] = "do_populate_sysroot" | 1739 | do_configure[deptask] = "do_populate_sysroot" |
1740 | 1740 | ||
1741 | In this example, the ``do_populate_sysroot`` task | 1741 | In this example, the ``do_populate_sysroot`` task |
1742 | of each item in ``DEPENDS`` must complete before ``do_configure`` can | 1742 | of each item in :term:`DEPENDS` must complete before ``do_configure`` can |
1743 | execute. | 1743 | execute. |
1744 | 1744 | ||
1745 | Runtime Dependencies | 1745 | Runtime Dependencies |
@@ -1748,8 +1748,8 @@ Runtime Dependencies | |||
1748 | BitBake uses the :term:`PACKAGES`, :term:`RDEPENDS`, and :term:`RRECOMMENDS` | 1748 | BitBake uses the :term:`PACKAGES`, :term:`RDEPENDS`, and :term:`RRECOMMENDS` |
1749 | variables to manage runtime dependencies. | 1749 | variables to manage runtime dependencies. |
1750 | 1750 | ||
1751 | The ``PACKAGES`` variable lists runtime packages. Each of those packages | 1751 | The :term:`PACKAGES` variable lists runtime packages. Each of those packages |
1752 | can have ``RDEPENDS`` and ``RRECOMMENDS`` runtime dependencies. The | 1752 | can have :term:`RDEPENDS` and :term:`RRECOMMENDS` runtime dependencies. The |
1753 | ``[rdeptask]`` flag for tasks is used to signify the task of each item | 1753 | ``[rdeptask]`` flag for tasks is used to signify the task of each item |
1754 | runtime dependency which must have completed before that task can be | 1754 | runtime dependency which must have completed before that task can be |
1755 | executed. :: | 1755 | executed. :: |
@@ -1757,9 +1757,9 @@ executed. :: | |||
1757 | do_package_qa[rdeptask] = "do_packagedata" | 1757 | do_package_qa[rdeptask] = "do_packagedata" |
1758 | 1758 | ||
1759 | In the previous | 1759 | In the previous |
1760 | example, the ``do_packagedata`` task of each item in ``RDEPENDS`` must | 1760 | example, the ``do_packagedata`` task of each item in :term:`RDEPENDS` must |
1761 | have completed before ``do_package_qa`` can execute. | 1761 | have completed before ``do_package_qa`` can execute. |
1762 | Although ``RDEPENDS`` contains entries from the | 1762 | Although :term:`RDEPENDS` contains entries from the |
1763 | runtime dependency namespace, BitBake knows how to map them back | 1763 | runtime dependency namespace, BitBake knows how to map them back |
1764 | to the build-time dependency namespace, in which the tasks are defined. | 1764 | to the build-time dependency namespace, in which the tasks are defined. |
1765 | 1765 | ||
@@ -1802,7 +1802,7 @@ Inter-Task Dependencies | |||
1802 | BitBake uses the ``[depends]`` flag in a more generic form to manage | 1802 | BitBake uses the ``[depends]`` flag in a more generic form to manage |
1803 | inter-task dependencies. This more generic form allows for | 1803 | inter-task dependencies. This more generic form allows for |
1804 | inter-dependency checks for specific tasks rather than checks for the | 1804 | inter-dependency checks for specific tasks rather than checks for the |
1805 | data in ``DEPENDS``. Here is an example:: | 1805 | data in :term:`DEPENDS`. Here is an example:: |
1806 | 1806 | ||
1807 | do_patch[depends] = "quilt-native:do_populate_sysroot" | 1807 | do_patch[depends] = "quilt-native:do_populate_sysroot" |
1808 | 1808 | ||
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 af870d515a..797e2a00cc 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 | |||
@@ -31,7 +31,7 @@ overview of their function and contents. | |||
31 | attempt to build. Instead, BitBake assumes these recipes have already | 31 | attempt to build. Instead, BitBake assumes these recipes have already |
32 | been built. | 32 | been built. |
33 | 33 | ||
34 | In OpenEmbedded-Core, ``ASSUME_PROVIDED`` mostly specifies native | 34 | In OpenEmbedded-Core, :term:`ASSUME_PROVIDED` mostly specifies native |
35 | 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 |
36 | 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 |
37 | rather than building ``git-native``. | 37 | rather than building ``git-native``. |
@@ -84,14 +84,14 @@ overview of their function and contents. | |||
84 | 84 | ||
85 | - Attempts to access networks not in the host list cause a failure. | 85 | - Attempts to access networks not in the host list cause a failure. |
86 | 86 | ||
87 | Using ``BB_ALLOWED_NETWORKS`` in conjunction with | 87 | Using :term:`BB_ALLOWED_NETWORKS` in conjunction with |
88 | :term:`PREMIRRORS` is very useful. Adding the | 88 | :term:`PREMIRRORS` is very useful. Adding the |
89 | host you want to use to ``PREMIRRORS`` results in the source code | 89 | host you want to use to :term:`PREMIRRORS` results in the source code |
90 | being fetched from an allowed location and avoids raising an error | 90 | being fetched from an allowed location and avoids raising an error |
91 | when a host that is not allowed is in a | 91 | when a host that is not allowed is in a |
92 | :term:`SRC_URI` statement. This is because the | 92 | :term:`SRC_URI` statement. This is because the |
93 | fetcher does not attempt to use the host listed in ``SRC_URI`` after | 93 | fetcher does not attempt to use the host listed in :term:`SRC_URI` after |
94 | a successful fetch from the ``PREMIRRORS`` occurs. | 94 | a successful fetch from the :term:`PREMIRRORS` occurs. |
95 | 95 | ||
96 | :term:`BB_CONSOLELOG` | 96 | :term:`BB_CONSOLELOG` |
97 | Specifies the path to a log file into which BitBake's user interface | 97 | Specifies the path to a log file into which BitBake's user interface |
@@ -178,7 +178,7 @@ overview of their function and contents. | |||
178 | issues a warning when the disk space in the ``${SSTATE_DIR}`` | 178 | issues a warning when the disk space in the ``${SSTATE_DIR}`` |
179 | directory drops below 1 Gbyte or the number of free inodes drops | 179 | directory drops below 1 Gbyte or the number of free inodes drops |
180 | below 100 Kbytes. Subsequent warnings are issued during intervals as | 180 | below 100 Kbytes. Subsequent warnings are issued during intervals as |
181 | defined by the ``BB_DISKMON_WARNINTERVAL`` variable. | 181 | defined by the :term:`BB_DISKMON_WARNINTERVAL` variable. |
182 | 182 | ||
183 | The second example stops the build after all currently executing | 183 | The second example stops the build after all currently executing |
184 | tasks complete when the minimum disk space in the ``${TMPDIR}`` | 184 | tasks complete when the minimum disk space in the ``${TMPDIR}`` |
@@ -192,14 +192,14 @@ overview of their function and contents. | |||
192 | :term:`BB_DISKMON_WARNINTERVAL` | 192 | :term:`BB_DISKMON_WARNINTERVAL` |
193 | Defines the disk space and free inode warning intervals. | 193 | Defines the disk space and free inode warning intervals. |
194 | 194 | ||
195 | If you are going to use the ``BB_DISKMON_WARNINTERVAL`` variable, you | 195 | If you are going to use the :term:`BB_DISKMON_WARNINTERVAL` variable, you |
196 | must also use the :term:`BB_DISKMON_DIRS` | 196 | must also use the :term:`BB_DISKMON_DIRS` |
197 | variable and define its action as "WARN". During the build, | 197 | variable and define its action as "WARN". During the build, |
198 | subsequent warnings are issued each time disk space or number of free | 198 | subsequent warnings are issued each time disk space or number of free |
199 | inodes further reduces by the respective interval. | 199 | inodes further reduces by the respective interval. |
200 | 200 | ||
201 | If you do not provide a ``BB_DISKMON_WARNINTERVAL`` variable and you | 201 | If you do not provide a :term:`BB_DISKMON_WARNINTERVAL` variable and you |
202 | do use ``BB_DISKMON_DIRS`` with the "WARN" action, the disk | 202 | do use :term:`BB_DISKMON_DIRS` with the "WARN" action, the disk |
203 | monitoring interval defaults to the following: | 203 | monitoring interval defaults to the following: |
204 | BB_DISKMON_WARNINTERVAL = "50M,5K" | 204 | BB_DISKMON_WARNINTERVAL = "50M,5K" |
205 | 205 | ||
@@ -264,7 +264,7 @@ overview of their function and contents. | |||
264 | :term:`BB_FILENAME` | 264 | :term:`BB_FILENAME` |
265 | Contains the filename of the recipe that owns the currently running | 265 | Contains the filename of the recipe that owns the currently running |
266 | task. For example, if the ``do_fetch`` task that resides in the | 266 | task. For example, if the ``do_fetch`` task that resides in the |
267 | ``my-recipe.bb`` is executing, the ``BB_FILENAME`` variable contains | 267 | ``my-recipe.bb`` is executing, the :term:`BB_FILENAME` variable contains |
268 | "/foo/path/my-recipe.bb". | 268 | "/foo/path/my-recipe.bb". |
269 | 269 | ||
270 | :term:`BB_GENERATE_MIRROR_TARBALLS` | 270 | :term:`BB_GENERATE_MIRROR_TARBALLS` |
@@ -334,7 +334,7 @@ overview of their function and contents. | |||
334 | 334 | ||
335 | :term:`BB_LOGFMT` | 335 | :term:`BB_LOGFMT` |
336 | Specifies the name of the log files saved into | 336 | Specifies the name of the log files saved into |
337 | ``${``\ :term:`T`\ ``}``. By default, the ``BB_LOGFMT`` | 337 | ``${``\ :term:`T`\ ``}``. By default, the :term:`BB_LOGFMT` |
338 | variable is undefined and the log file names get created using the | 338 | variable is undefined and the log file names get created using the |
339 | following form:: | 339 | following form:: |
340 | 340 | ||
@@ -389,7 +389,7 @@ overview of their function and contents. | |||
389 | :term:`BB_RUNFMT` | 389 | :term:`BB_RUNFMT` |
390 | Specifies the name of the executable script files (i.e. run files) | 390 | Specifies the name of the executable script files (i.e. run files) |
391 | saved into ``${``\ :term:`T`\ ``}``. By default, the | 391 | saved into ``${``\ :term:`T`\ ``}``. By default, the |
392 | ``BB_RUNFMT`` variable is undefined and the run file names get | 392 | :term:`BB_RUNFMT` variable is undefined and the run file names get |
393 | created using the following form:: | 393 | created using the following form:: |
394 | 394 | ||
395 | run.{task}.{pid} | 395 | run.{task}.{pid} |
@@ -455,7 +455,7 @@ overview of their function and contents. | |||
455 | :term:`BB_SRCREV_POLICY` | 455 | :term:`BB_SRCREV_POLICY` |
456 | Defines the behavior of the fetcher when it interacts with source | 456 | Defines the behavior of the fetcher when it interacts with source |
457 | control systems and dynamic source revisions. The | 457 | control systems and dynamic source revisions. The |
458 | ``BB_SRCREV_POLICY`` variable is useful when working without a | 458 | :term:`BB_SRCREV_POLICY` variable is useful when working without a |
459 | network. | 459 | network. |
460 | 460 | ||
461 | The variable can be set using one of two policies: | 461 | The variable can be set using one of two policies: |
@@ -499,7 +499,7 @@ overview of their function and contents. | |||
499 | Allows adjustment of a task's Input/Output priority. During | 499 | Allows adjustment of a task's Input/Output priority. During |
500 | Autobuilder testing, random failures can occur for tasks due to I/O | 500 | Autobuilder testing, random failures can occur for tasks due to I/O |
501 | starvation. These failures occur during various QEMU runtime | 501 | starvation. These failures occur during various QEMU runtime |
502 | timeouts. You can use the ``BB_TASK_IONICE_LEVEL`` variable to adjust | 502 | timeouts. You can use the :term:`BB_TASK_IONICE_LEVEL` variable to adjust |
503 | the I/O priority of these tasks. | 503 | the I/O priority of these tasks. |
504 | 504 | ||
505 | .. note:: | 505 | .. note:: |
@@ -573,13 +573,13 @@ overview of their function and contents. | |||
573 | 573 | ||
574 | .. note:: | 574 | .. note:: |
575 | 575 | ||
576 | Internally, the ``BBCLASSEXTEND`` mechanism generates recipe | 576 | Internally, the :term:`BBCLASSEXTEND` mechanism generates recipe |
577 | variants by rewriting variable values and applying overrides such | 577 | variants by rewriting variable values and applying overrides such |
578 | as ``_class-native``. For example, to generate a native version of | 578 | as ``_class-native``. For example, to generate a native version of |
579 | a recipe, a :term:`DEPENDS` on "foo" is | 579 | a recipe, a :term:`DEPENDS` on "foo" is |
580 | rewritten to a ``DEPENDS`` on "foo-native". | 580 | rewritten to a :term:`DEPENDS` on "foo-native". |
581 | 581 | ||
582 | Even when using ``BBCLASSEXTEND``, the recipe is only parsed once. | 582 | Even when using :term:`BBCLASSEXTEND`, the recipe is only parsed once. |
583 | Parsing once adds some limitations. For example, it is not | 583 | Parsing once adds some limitations. For example, it is not |
584 | possible to include a different file depending on the variant, | 584 | possible to include a different file depending on the variant, |
585 | since ``include`` statements are processed when the recipe is | 585 | since ``include`` statements are processed when the recipe is |
@@ -615,14 +615,14 @@ overview of their function and contents. | |||
615 | - effectively letting you control the precedence for the multiple | 615 | - effectively letting you control the precedence for the multiple |
616 | layers. The precedence established through this variable stands | 616 | layers. The precedence established through this variable stands |
617 | regardless of a recipe's version (:term:`PV` variable). | 617 | regardless of a recipe's version (:term:`PV` variable). |
618 | For example, a layer that has a recipe with a higher ``PV`` value but | 618 | For example, a layer that has a recipe with a higher :term:`PV` value but |
619 | for which the ``BBFILE_PRIORITY`` is set to have a lower precedence | 619 | for which the :term:`BBFILE_PRIORITY` is set to have a lower precedence |
620 | still has a lower precedence. | 620 | still has a lower precedence. |
621 | 621 | ||
622 | A larger value for the ``BBFILE_PRIORITY`` variable results in a | 622 | A larger value for the :term:`BBFILE_PRIORITY` variable results in a |
623 | higher precedence. For example, the value 6 has a higher precedence | 623 | higher precedence. For example, the value 6 has a higher precedence |
624 | than the value 5. If not specified, the ``BBFILE_PRIORITY`` variable | 624 | than the value 5. If not specified, the :term:`BBFILE_PRIORITY` variable |
625 | is set based on layer dependencies (see the ``LAYERDEPENDS`` variable | 625 | is set based on layer dependencies (see the :term:`LAYERDEPENDS` variable |
626 | for more information. The default priority, if unspecified for a | 626 | for more information. The default priority, if unspecified for a |
627 | layer with no dependencies, is the lowest defined priority + 1 (or 1 | 627 | layer with no dependencies, is the lowest defined priority + 1 (or 1 |
628 | if no priorities are defined). | 628 | if no priorities are defined). |
@@ -645,7 +645,7 @@ overview of their function and contents. | |||
645 | Activates content depending on presence of identified layers. You | 645 | Activates content depending on presence of identified layers. You |
646 | identify the layers by the collections that the layers define. | 646 | identify the layers by the collections that the layers define. |
647 | 647 | ||
648 | Use the ``BBFILES_DYNAMIC`` variable to avoid ``.bbappend`` files whose | 648 | Use the :term:`BBFILES_DYNAMIC` variable to avoid ``.bbappend`` files whose |
649 | corresponding ``.bb`` file is in a layer that attempts to modify other | 649 | corresponding ``.bb`` file is in a layer that attempts to modify other |
650 | layers through ``.bbappend`` but does not want to introduce a hard | 650 | layers through ``.bbappend`` but does not want to introduce a hard |
651 | dependency on those other layers. | 651 | dependency on those other layers. |
@@ -654,7 +654,7 @@ overview of their function and contents. | |||
654 | ``.bb`` files in case a layer is not present. Use this avoid hard | 654 | ``.bb`` files in case a layer is not present. Use this avoid hard |
655 | dependency on those other layers. | 655 | dependency on those other layers. |
656 | 656 | ||
657 | Use the following form for ``BBFILES_DYNAMIC``:: | 657 | Use the following form for :term:`BBFILES_DYNAMIC`:: |
658 | 658 | ||
659 | collection_name:filename_pattern | 659 | collection_name:filename_pattern |
660 | 660 | ||
@@ -691,7 +691,7 @@ overview of their function and contents. | |||
691 | :term:`BBINCLUDELOGS_LINES` | 691 | :term:`BBINCLUDELOGS_LINES` |
692 | If :term:`BBINCLUDELOGS` is set, specifies | 692 | If :term:`BBINCLUDELOGS` is set, specifies |
693 | the maximum number of lines from the task log file to print when | 693 | the maximum number of lines from the task log file to print when |
694 | reporting a failed task. If you do not set ``BBINCLUDELOGS_LINES``, | 694 | reporting a failed task. If you do not set :term:`BBINCLUDELOGS_LINES`, |
695 | the entire log is printed. | 695 | the entire log is printed. |
696 | 696 | ||
697 | :term:`BBLAYERS` | 697 | :term:`BBLAYERS` |
@@ -717,7 +717,7 @@ overview of their function and contents. | |||
717 | :term:`BBMASK` | 717 | :term:`BBMASK` |
718 | Prevents BitBake from processing recipes and recipe append files. | 718 | Prevents BitBake from processing recipes and recipe append files. |
719 | 719 | ||
720 | You can use the ``BBMASK`` variable to "hide" these ``.bb`` and | 720 | You can use the :term:`BBMASK` variable to "hide" these ``.bb`` and |
721 | ``.bbappend`` files. BitBake ignores any recipe or recipe append | 721 | ``.bbappend`` files. BitBake ignores any recipe or recipe append |
722 | files that match any of the expressions. It is as if BitBake does not | 722 | files that match any of the expressions. It is as if BitBake does not |
723 | see them at all. Consequently, matching files are not parsed or | 723 | see them at all. Consequently, matching files are not parsed or |
@@ -754,7 +754,7 @@ overview of their function and contents. | |||
754 | Enables BitBake to perform multiple configuration builds and lists | 754 | Enables BitBake to perform multiple configuration builds and lists |
755 | each separate configuration (multiconfig). You can use this variable | 755 | each separate configuration (multiconfig). You can use this variable |
756 | to cause BitBake to build multiple targets where each target has a | 756 | to cause BitBake to build multiple targets where each target has a |
757 | separate configuration. Define ``BBMULTICONFIG`` in your | 757 | separate configuration. Define :term:`BBMULTICONFIG` in your |
758 | ``conf/local.conf`` configuration file. | 758 | ``conf/local.conf`` configuration file. |
759 | 759 | ||
760 | As an example, the following line specifies three multiconfigs, each | 760 | As an example, the following line specifies three multiconfigs, each |
@@ -766,7 +766,7 @@ overview of their function and contents. | |||
766 | build directory within a directory named ``conf/multiconfig`` (e.g. | 766 | build directory within a directory named ``conf/multiconfig`` (e.g. |
767 | build_directory\ ``/conf/multiconfig/configA.conf``). | 767 | build_directory\ ``/conf/multiconfig/configA.conf``). |
768 | 768 | ||
769 | For information on how to use ``BBMULTICONFIG`` in an environment | 769 | For information on how to use :term:`BBMULTICONFIG` in an environment |
770 | that supports building targets with multiple configurations, see the | 770 | that supports building targets with multiple configurations, see the |
771 | ":ref:`bitbake-user-manual/bitbake-user-manual-intro:executing a multiple configuration build`" | 771 | ":ref:`bitbake-user-manual/bitbake-user-manual-intro:executing a multiple configuration build`" |
772 | section. | 772 | section. |
@@ -777,7 +777,7 @@ overview of their function and contents. | |||
777 | variable. | 777 | variable. |
778 | 778 | ||
779 | If you run BitBake from a directory outside of the build directory, | 779 | If you run BitBake from a directory outside of the build directory, |
780 | you must be sure to set ``BBPATH`` to point to the build directory. | 780 | you must be sure to set :term:`BBPATH` to point to the build directory. |
781 | Set the variable as you would any environment variable and then run | 781 | Set the variable as you would any environment variable and then run |
782 | BitBake:: | 782 | BitBake:: |
783 | 783 | ||
@@ -824,7 +824,7 @@ overview of their function and contents. | |||
824 | The most common usage of this is variable is to set it to "-1" within | 824 | The most common usage of this is variable is to set it to "-1" within |
825 | a recipe for a development version of a piece of software. Using the | 825 | a recipe for a development version of a piece of software. Using the |
826 | variable in this way causes the stable version of the recipe to build | 826 | variable in this way causes the stable version of the recipe to build |
827 | by default in the absence of ``PREFERRED_VERSION`` being used to | 827 | by default in the absence of :term:`PREFERRED_VERSION` being used to |
828 | build the development version. | 828 | build the development version. |
829 | 829 | ||
830 | .. note:: | 830 | .. note:: |
@@ -837,7 +837,7 @@ overview of their function and contents. | |||
837 | Lists a recipe's build-time dependencies (i.e. other recipe files). | 837 | Lists a recipe's build-time dependencies (i.e. other recipe files). |
838 | 838 | ||
839 | Consider this simple example for two recipes named "a" and "b" that | 839 | Consider this simple example for two recipes named "a" and "b" that |
840 | produce similarly named packages. In this example, the ``DEPENDS`` | 840 | produce similarly named packages. In this example, the :term:`DEPENDS` |
841 | statement appears in the "a" recipe:: | 841 | statement appears in the "a" recipe:: |
842 | 842 | ||
843 | DEPENDS = "b" | 843 | DEPENDS = "b" |
@@ -855,7 +855,7 @@ overview of their function and contents. | |||
855 | 855 | ||
856 | :term:`DL_DIR` | 856 | :term:`DL_DIR` |
857 | The central download directory used by the build process to store | 857 | The central download directory used by the build process to store |
858 | downloads. By default, ``DL_DIR`` gets files suitable for mirroring for | 858 | downloads. By default, :term:`DL_DIR` gets files suitable for mirroring for |
859 | everything except Git repositories. If you want tarballs of Git | 859 | everything except Git repositories. If you want tarballs of Git |
860 | repositories, use the :term:`BB_GENERATE_MIRROR_TARBALLS` variable. | 860 | repositories, use the :term:`BB_GENERATE_MIRROR_TARBALLS` variable. |
861 | 861 | ||
@@ -870,14 +870,14 @@ overview of their function and contents. | |||
870 | 870 | ||
871 | .. note:: | 871 | .. note:: |
872 | 872 | ||
873 | Recipes added to ``EXCLUDE_FROM_WORLD`` may still be built during a world | 873 | Recipes added to :term:`EXCLUDE_FROM_WORLD` may still be built during a world |
874 | build in order to satisfy dependencies of other recipes. Adding a | 874 | build in order to satisfy dependencies of other recipes. Adding a |
875 | recipe to ``EXCLUDE_FROM_WORLD`` only ensures that the recipe is not | 875 | recipe to :term:`EXCLUDE_FROM_WORLD` only ensures that the recipe is not |
876 | explicitly added to the list of build targets in a world build. | 876 | explicitly added to the list of build targets in a world build. |
877 | 877 | ||
878 | :term:`FAKEROOT` | 878 | :term:`FAKEROOT` |
879 | Contains the command to use when running a shell script in a fakeroot | 879 | Contains the command to use when running a shell script in a fakeroot |
880 | environment. The ``FAKEROOT`` variable is obsolete and has been | 880 | environment. The :term:`FAKEROOT` variable is obsolete and has been |
881 | replaced by the other ``FAKEROOT*`` variables. See these entries in | 881 | replaced by the other ``FAKEROOT*`` variables. See these entries in |
882 | the glossary for more information. | 882 | the glossary for more information. |
883 | 883 | ||
@@ -940,9 +940,9 @@ overview of their function and contents. | |||
940 | Causes the named class or classes to be inherited globally. Anonymous | 940 | Causes the named class or classes to be inherited globally. Anonymous |
941 | functions in the class or classes are not executed for the base | 941 | functions in the class or classes are not executed for the base |
942 | configuration and in each individual recipe. The OpenEmbedded build | 942 | configuration and in each individual recipe. The OpenEmbedded build |
943 | system ignores changes to ``INHERIT`` in individual recipes. | 943 | system ignores changes to :term:`INHERIT` in individual recipes. |
944 | 944 | ||
945 | For more information on ``INHERIT``, see the | 945 | For more information on :term:`INHERIT`, see the |
946 | ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:\`\`inherit\`\` configuration directive`" | 946 | ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:\`\`inherit\`\` configuration directive`" |
947 | section. | 947 | section. |
948 | 948 | ||
@@ -990,7 +990,7 @@ overview of their function and contents. | |||
990 | the build system searches for source code, it first tries the local | 990 | the build system searches for source code, it first tries the local |
991 | download directory. If that location fails, the build system tries | 991 | download directory. If that location fails, the build system tries |
992 | locations defined by :term:`PREMIRRORS`, the | 992 | locations defined by :term:`PREMIRRORS`, the |
993 | upstream source, and then locations specified by ``MIRRORS`` in that | 993 | upstream source, and then locations specified by :term:`MIRRORS` in that |
994 | order. | 994 | order. |
995 | 995 | ||
996 | :term:`MULTI_PROVIDER_WHITELIST` | 996 | :term:`MULTI_PROVIDER_WHITELIST` |
@@ -1007,12 +1007,12 @@ overview of their function and contents. | |||
1007 | ``virtual/kernel``, and so forth). | 1007 | ``virtual/kernel``, and so forth). |
1008 | 1008 | ||
1009 | :term:`OVERRIDES` | 1009 | :term:`OVERRIDES` |
1010 | BitBake uses ``OVERRIDES`` to control what variables are overridden | 1010 | BitBake uses :term:`OVERRIDES` to control what variables are overridden |
1011 | after BitBake parses recipes and configuration files. | 1011 | after BitBake parses recipes and configuration files. |
1012 | 1012 | ||
1013 | Following is a simple example that uses an overrides list based on | 1013 | Following is a simple example that uses an overrides list based on |
1014 | machine architectures: OVERRIDES = "arm:x86:mips:powerpc" You can | 1014 | machine architectures: OVERRIDES = "arm:x86:mips:powerpc" You can |
1015 | find information on how to use ``OVERRIDES`` in the | 1015 | find information on how to use :term:`OVERRIDES` in the |
1016 | ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:conditional syntax | 1016 | ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:conditional syntax |
1017 | (overrides)`" section. | 1017 | (overrides)`" section. |
1018 | 1018 | ||
@@ -1026,11 +1026,11 @@ overview of their function and contents. | |||
1026 | :term:`PACKAGES_DYNAMIC` | 1026 | :term:`PACKAGES_DYNAMIC` |
1027 | A promise that your recipe satisfies runtime dependencies for | 1027 | A promise that your recipe satisfies runtime dependencies for |
1028 | optional modules that are found in other recipes. | 1028 | optional modules that are found in other recipes. |
1029 | ``PACKAGES_DYNAMIC`` does not actually satisfy the dependencies, it | 1029 | :term:`PACKAGES_DYNAMIC` does not actually satisfy the dependencies, it |
1030 | only states that they should be satisfied. For example, if a hard, | 1030 | only states that they should be satisfied. For example, if a hard, |
1031 | runtime dependency (:term:`RDEPENDS`) of another | 1031 | runtime dependency (:term:`RDEPENDS`) of another |
1032 | package is satisfied during the build through the | 1032 | package is satisfied during the build through the |
1033 | ``PACKAGES_DYNAMIC`` variable, but a package with the module name is | 1033 | :term:`PACKAGES_DYNAMIC` variable, but a package with the module name is |
1034 | never actually produced, then the other package will be broken. | 1034 | never actually produced, then the other package will be broken. |
1035 | 1035 | ||
1036 | :term:`PE` | 1036 | :term:`PE` |
@@ -1069,8 +1069,8 @@ overview of their function and contents. | |||
1069 | :term:`PREFERRED_PROVIDERS` | 1069 | :term:`PREFERRED_PROVIDERS` |
1070 | Determines which recipe should be given preference for cases where | 1070 | Determines which recipe should be given preference for cases where |
1071 | multiple recipes provide the same item. Functionally, | 1071 | multiple recipes provide the same item. Functionally, |
1072 | ``PREFERRED_PROVIDERS`` is identical to | 1072 | :term:`PREFERRED_PROVIDERS` is identical to |
1073 | :term:`PREFERRED_PROVIDER`. However, the ``PREFERRED_PROVIDERS`` variable | 1073 | :term:`PREFERRED_PROVIDER`. However, the :term:`PREFERRED_PROVIDERS` variable |
1074 | lets you define preferences for multiple situations using the following | 1074 | lets you define preferences for multiple situations using the following |
1075 | form:: | 1075 | form:: |
1076 | 1076 | ||
@@ -1088,7 +1088,7 @@ overview of their function and contents. | |||
1088 | select, and you should set :term:`PV` accordingly for | 1088 | select, and you should set :term:`PV` accordingly for |
1089 | precedence. | 1089 | precedence. |
1090 | 1090 | ||
1091 | The ``PREFERRED_VERSION`` variable supports limited wildcard use | 1091 | The :term:`PREFERRED_VERSION` variable supports limited wildcard use |
1092 | through the "``%``" character. You can use the character to match any | 1092 | through the "``%``" character. You can use the character to match any |
1093 | number of characters, which can be useful when specifying versions | 1093 | number of characters, which can be useful when specifying versions |
1094 | that contain long revision numbers that potentially change. Here are | 1094 | that contain long revision numbers that potentially change. Here are |
@@ -1111,7 +1111,7 @@ overview of their function and contents. | |||
1111 | Specifies additional paths from which BitBake gets source code. When | 1111 | Specifies additional paths from which BitBake gets source code. When |
1112 | the build system searches for source code, it first tries the local | 1112 | the build system searches for source code, it first tries the local |
1113 | download directory. If that location fails, the build system tries | 1113 | download directory. If that location fails, the build system tries |
1114 | locations defined by ``PREMIRRORS``, the upstream source, and then | 1114 | locations defined by :term:`PREMIRRORS`, the upstream source, and then |
1115 | locations specified by :term:`MIRRORS` in that order. | 1115 | locations specified by :term:`MIRRORS` in that order. |
1116 | 1116 | ||
1117 | Typically, you would add a specific server for the build system to | 1117 | Typically, you would add a specific server for the build system to |
@@ -1131,25 +1131,25 @@ overview of their function and contents. | |||
1131 | 1131 | ||
1132 | :term:`PROVIDES` | 1132 | :term:`PROVIDES` |
1133 | A list of aliases by which a particular recipe can be known. By | 1133 | A list of aliases by which a particular recipe can be known. By |
1134 | default, a recipe's own ``PN`` is implicitly already in its | 1134 | default, a recipe's own :term:`PN` is implicitly already in its |
1135 | ``PROVIDES`` list. If a recipe uses ``PROVIDES``, the additional | 1135 | :term:`PROVIDES` list. If a recipe uses :term:`PROVIDES`, the additional |
1136 | aliases are synonyms for the recipe and can be useful satisfying | 1136 | aliases are synonyms for the recipe and can be useful satisfying |
1137 | dependencies of other recipes during the build as specified by | 1137 | dependencies of other recipes during the build as specified by |
1138 | ``DEPENDS``. | 1138 | :term:`DEPENDS`. |
1139 | 1139 | ||
1140 | Consider the following example ``PROVIDES`` statement from a recipe | 1140 | Consider the following example :term:`PROVIDES` statement from a recipe |
1141 | file ``libav_0.8.11.bb``:: | 1141 | file ``libav_0.8.11.bb``:: |
1142 | 1142 | ||
1143 | PROVIDES += "libpostproc" | 1143 | PROVIDES += "libpostproc" |
1144 | 1144 | ||
1145 | The ``PROVIDES`` statement results in the "libav" recipe also being known | 1145 | The :term:`PROVIDES` statement results in the "libav" recipe also being known |
1146 | as "libpostproc". | 1146 | as "libpostproc". |
1147 | 1147 | ||
1148 | In addition to providing recipes under alternate names, the | 1148 | In addition to providing recipes under alternate names, the |
1149 | ``PROVIDES`` mechanism is also used to implement virtual targets. A | 1149 | :term:`PROVIDES` mechanism is also used to implement virtual targets. A |
1150 | virtual target is a name that corresponds to some particular | 1150 | virtual target is a name that corresponds to some particular |
1151 | functionality (e.g. a Linux kernel). Recipes that provide the | 1151 | functionality (e.g. a Linux kernel). Recipes that provide the |
1152 | functionality in question list the virtual target in ``PROVIDES``. | 1152 | functionality in question list the virtual target in :term:`PROVIDES`. |
1153 | Recipes that depend on the functionality in question can include the | 1153 | Recipes that depend on the functionality in question can include the |
1154 | virtual target in :term:`DEPENDS` to leave the | 1154 | virtual target in :term:`DEPENDS` to leave the |
1155 | choice of provider open. | 1155 | choice of provider open. |
@@ -1161,12 +1161,12 @@ overview of their function and contents. | |||
1161 | :term:`PRSERV_HOST` | 1161 | :term:`PRSERV_HOST` |
1162 | The network based :term:`PR` service host and port. | 1162 | The network based :term:`PR` service host and port. |
1163 | 1163 | ||
1164 | Following is an example of how the ``PRSERV_HOST`` variable is set:: | 1164 | Following is an example of how the :term:`PRSERV_HOST` variable is set:: |
1165 | 1165 | ||
1166 | PRSERV_HOST = "localhost:0" | 1166 | PRSERV_HOST = "localhost:0" |
1167 | 1167 | ||
1168 | You must set the variable if you want to automatically start a local PR | 1168 | You must set the variable if you want to automatically start a local PR |
1169 | service. You can set ``PRSERV_HOST`` to other values to use a remote PR | 1169 | service. You can set :term:`PRSERV_HOST` to other values to use a remote PR |
1170 | service. | 1170 | service. |
1171 | 1171 | ||
1172 | :term:`PV` | 1172 | :term:`PV` |
@@ -1178,22 +1178,22 @@ overview of their function and contents. | |||
1178 | a package in this list cannot be found during the build, you will get | 1178 | a package in this list cannot be found during the build, you will get |
1179 | a build error. | 1179 | a build error. |
1180 | 1180 | ||
1181 | Because the ``RDEPENDS`` variable applies to packages being built, | 1181 | Because the :term:`RDEPENDS` variable applies to packages being built, |
1182 | you should always use the variable in a form with an attached package | 1182 | you should always use the variable in a form with an attached package |
1183 | name. For example, suppose you are building a development package | 1183 | name. For example, suppose you are building a development package |
1184 | that depends on the ``perl`` package. In this case, you would use the | 1184 | that depends on the ``perl`` package. In this case, you would use the |
1185 | following ``RDEPENDS`` statement:: | 1185 | following :term:`RDEPENDS` statement:: |
1186 | 1186 | ||
1187 | RDEPENDS_${PN}-dev += "perl" | 1187 | RDEPENDS_${PN}-dev += "perl" |
1188 | 1188 | ||
1189 | In the example, the development package depends on the ``perl`` package. | 1189 | In the example, the development package depends on the ``perl`` package. |
1190 | Thus, the ``RDEPENDS`` variable has the ``${PN}-dev`` package name as part | 1190 | Thus, the :term:`RDEPENDS` variable has the ``${PN}-dev`` package name as part |
1191 | of the variable. | 1191 | of the variable. |
1192 | 1192 | ||
1193 | BitBake supports specifying versioned dependencies. Although the | 1193 | BitBake supports specifying versioned dependencies. Although the |
1194 | syntax varies depending on the packaging format, BitBake hides these | 1194 | syntax varies depending on the packaging format, BitBake hides these |
1195 | differences from you. Here is the general syntax to specify versions | 1195 | differences from you. Here is the general syntax to specify versions |
1196 | with the ``RDEPENDS`` variable:: | 1196 | with the :term:`RDEPENDS` variable:: |
1197 | 1197 | ||
1198 | RDEPENDS_${PN} = "package (operator version)" | 1198 | RDEPENDS_${PN} = "package (operator version)" |
1199 | 1199 | ||
@@ -1219,19 +1219,19 @@ overview of their function and contents. | |||
1219 | 1219 | ||
1220 | :term:`REQUIRED_VERSION` | 1220 | :term:`REQUIRED_VERSION` |
1221 | If there are multiple versions of a recipe available, this variable | 1221 | If there are multiple versions of a recipe available, this variable |
1222 | determines which version should be given preference. ``REQUIRED_VERSION`` | 1222 | determines which version should be given preference. :term:`REQUIRED_VERSION` |
1223 | works in exactly the same manner as :term:`PREFERRED_VERSION`, except | 1223 | works in exactly the same manner as :term:`PREFERRED_VERSION`, except |
1224 | that if the specified version is not available then an error message | 1224 | that if the specified version is not available then an error message |
1225 | is shown and the build fails immediately. | 1225 | is shown and the build fails immediately. |
1226 | 1226 | ||
1227 | If both ``REQUIRED_VERSION`` and ``PREFERRED_VERSION`` are set for | 1227 | If both :term:`REQUIRED_VERSION` and :term:`PREFERRED_VERSION` are set for |
1228 | the same recipe, the ``REQUIRED_VERSION`` value applies. | 1228 | the same recipe, the :term:`REQUIRED_VERSION` value applies. |
1229 | 1229 | ||
1230 | :term:`RPROVIDES` | 1230 | :term:`RPROVIDES` |
1231 | A list of package name aliases that a package also provides. These | 1231 | A list of package name aliases that a package also provides. These |
1232 | aliases are useful for satisfying runtime dependencies of other | 1232 | aliases are useful for satisfying runtime dependencies of other |
1233 | packages both during the build and on the target (as specified by | 1233 | packages both during the build and on the target (as specified by |
1234 | ``RDEPENDS``). | 1234 | :term:`RDEPENDS`). |
1235 | 1235 | ||
1236 | As with all package-controlling variables, you must always use the | 1236 | As with all package-controlling variables, you must always use the |
1237 | variable in conjunction with a package name override. Here is an | 1237 | variable in conjunction with a package name override. Here is an |
@@ -1244,12 +1244,12 @@ overview of their function and contents. | |||
1244 | built. The package being built does not depend on this list of | 1244 | built. The package being built does not depend on this list of |
1245 | packages in order to successfully build, but needs them for the | 1245 | packages in order to successfully build, but needs them for the |
1246 | extended usability. To specify runtime dependencies for packages, see | 1246 | extended usability. To specify runtime dependencies for packages, see |
1247 | the ``RDEPENDS`` variable. | 1247 | the :term:`RDEPENDS` variable. |
1248 | 1248 | ||
1249 | BitBake supports specifying versioned recommends. Although the syntax | 1249 | BitBake supports specifying versioned recommends. Although the syntax |
1250 | varies depending on the packaging format, BitBake hides these | 1250 | varies depending on the packaging format, BitBake hides these |
1251 | differences from you. Here is the general syntax to specify versions | 1251 | differences from you. Here is the general syntax to specify versions |
1252 | with the ``RRECOMMENDS`` variable:: | 1252 | with the :term:`RRECOMMENDS` variable:: |
1253 | 1253 | ||
1254 | RRECOMMENDS_${PN} = "package (operator version)" | 1254 | RRECOMMENDS_${PN} = "package (operator version)" |
1255 | 1255 | ||
@@ -1273,10 +1273,10 @@ overview of their function and contents. | |||
1273 | The list of source files - local or remote. This variable tells | 1273 | The list of source files - local or remote. This variable tells |
1274 | BitBake which bits to pull for the build and how to pull them. For | 1274 | BitBake which bits to pull for the build and how to pull them. For |
1275 | example, if the recipe or append file needs to fetch a single tarball | 1275 | example, if the recipe or append file needs to fetch a single tarball |
1276 | from the Internet, the recipe or append file uses a ``SRC_URI`` entry | 1276 | from the Internet, the recipe or append file uses a :term:`SRC_URI` entry |
1277 | that specifies that tarball. On the other hand, if the recipe or | 1277 | that specifies that tarball. On the other hand, if the recipe or |
1278 | append file needs to fetch a tarball and include a custom file, the | 1278 | append file needs to fetch a tarball and include a custom file, the |
1279 | recipe or append file needs an ``SRC_URI`` variable that specifies | 1279 | recipe or append file needs an :term:`SRC_URI` variable that specifies |
1280 | all those sources. | 1280 | all those sources. |
1281 | 1281 | ||
1282 | The following list explains the available URI protocols: | 1282 | The following list explains the available URI protocols: |
@@ -1329,8 +1329,8 @@ overview of their function and contents. | |||
1329 | subdirectory within the archive. | 1329 | subdirectory within the archive. |
1330 | 1330 | ||
1331 | - ``name`` : Specifies a name to be used for association with | 1331 | - ``name`` : Specifies a name to be used for association with |
1332 | ``SRC_URI`` checksums when you have more than one file specified | 1332 | :term:`SRC_URI` checksums when you have more than one file specified |
1333 | in ``SRC_URI``. | 1333 | in :term:`SRC_URI`. |
1334 | 1334 | ||
1335 | - ``downloadfilename`` : Specifies the filename used when storing | 1335 | - ``downloadfilename`` : Specifies the filename used when storing |
1336 | the downloaded file. | 1336 | the downloaded file. |
@@ -1345,7 +1345,7 @@ overview of their function and contents. | |||
1345 | variable applies only when using Subversion, Git, Mercurial and | 1345 | variable applies only when using Subversion, Git, Mercurial and |
1346 | Bazaar. If you want to build a fixed revision and you want to avoid | 1346 | Bazaar. If you want to build a fixed revision and you want to avoid |
1347 | performing a query on the remote repository every time BitBake parses | 1347 | performing a query on the remote repository every time BitBake parses |
1348 | your recipe, you should specify a ``SRCREV`` that is a full revision | 1348 | your recipe, you should specify a :term:`SRCREV` that is a full revision |
1349 | identifier and not just a tag. | 1349 | identifier and not just a tag. |
1350 | 1350 | ||
1351 | :term:`SRCREV_FORMAT` | 1351 | :term:`SRCREV_FORMAT` |
@@ -1354,10 +1354,10 @@ overview of their function and contents. | |||
1354 | :term:`SRC_URI`. | 1354 | :term:`SRC_URI`. |
1355 | 1355 | ||
1356 | The system needs help constructing these values under these | 1356 | The system needs help constructing these values under these |
1357 | circumstances. Each component in the ``SRC_URI`` is assigned a name | 1357 | circumstances. Each component in the :term:`SRC_URI` is assigned a name |
1358 | and these are referenced in the ``SRCREV_FORMAT`` variable. Consider | 1358 | and these are referenced in the :term:`SRCREV_FORMAT` variable. Consider |
1359 | an example with URLs named "machine" and "meta". In this case, | 1359 | an example with URLs named "machine" and "meta". In this case, |
1360 | ``SRCREV_FORMAT`` could look like "machine_meta" and those names | 1360 | :term:`SRCREV_FORMAT` could look like "machine_meta" and those names |
1361 | would have the SCM versions substituted into each position. Only one | 1361 | would have the SCM versions substituted into each position. Only one |
1362 | ``AUTOINC`` placeholder is added and if needed. And, this placeholder | 1362 | ``AUTOINC`` placeholder is added and if needed. And, this placeholder |
1363 | is placed at the start of the returned string. | 1363 | is placed at the start of the returned string. |
@@ -1369,7 +1369,7 @@ overview of their function and contents. | |||
1369 | 1369 | ||
1370 | :term:`STAMPCLEAN` | 1370 | :term:`STAMPCLEAN` |
1371 | Specifies the base path used to create recipe stamp files. Unlike the | 1371 | Specifies the base path used to create recipe stamp files. Unlike the |
1372 | :term:`STAMP` variable, ``STAMPCLEAN`` can contain | 1372 | :term:`STAMP` variable, :term:`STAMPCLEAN` can contain |
1373 | wildcards to match the range of files a clean operation should | 1373 | wildcards to match the range of files a clean operation should |
1374 | remove. BitBake uses a clean operation to remove any other stamps it | 1374 | remove. BitBake uses a clean operation to remove any other stamps it |
1375 | should be removing when creating a new stamp. | 1375 | should be removing when creating a new stamp. |