summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorNicolas Dechesne <nicolas.dechesne@linaro.org>2020-07-31 10:00:02 +0200
committerRichard Purdie <richard.purdie@linuxfoundation.org>2020-09-16 18:14:08 +0100
commite3b76c8fc370833a623791cec6e805158d35e9d1 (patch)
tree9ad3df8166ed0a79dee3a454dcba53281f375f2f
parent4324c6e0716915c4d375805ce695a9eedb0fa010 (diff)
downloadpoky-e3b76c8fc370833a623791cec6e805158d35e9d1.tar.gz
bitbake: sphinx: last manual round of fixes/improvements
Review all pages, and fix up for formatting which was not covered by pandoc, such as some links and code block sections. (Bitbake rev: d99760cc687cc9c24d6d9a1c49fa094574476e0c) Signed-off-by: Nicolas Dechesne <nicolas.dechesne@linaro.org> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
-rw-r--r--bitbake/doc/bitbake-user-manual/bitbake-user-manual-execution.rst237
-rw-r--r--bitbake/doc/bitbake-user-manual/bitbake-user-manual-fetching.rst243
-rw-r--r--bitbake/doc/bitbake-user-manual/bitbake-user-manual-hello.rst417
-rw-r--r--bitbake/doc/bitbake-user-manual/bitbake-user-manual-intro.rst316
-rw-r--r--bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst1233
-rw-r--r--bitbake/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst457
6 files changed, 1733 insertions, 1170 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 ab61b05a87..019afd22f6 100644
--- a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-execution.rst
+++ b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-execution.rst
@@ -16,9 +16,13 @@ data, or simply return information about the execution environment.
16 16
17This chapter describes BitBake's execution process from start to finish 17This chapter describes BitBake's execution process from start to finish
18when you use it to create an image. The execution process is launched 18when you use it to create an image. The execution process is launched
19using the following command form: $ bitbake target For information on 19using the following command form: ::
20the BitBake command and its options, see "`The BitBake 20
21Command <#bitbake-user-manual-command>`__" section. 21 $ bitbake target
22
23For information on
24the BitBake command and its options, see ":ref:`The BitBake Command
25<bitbake-user-manual-command>`" section.
22 26
23.. note:: 27.. note::
24 28
@@ -28,7 +32,11 @@ Command <#bitbake-user-manual-command>`__" section.
28 your project's ``local.conf`` configuration file. 32 your project's ``local.conf`` configuration file.
29 33
30 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
31 the following: $ grep processor /proc/cpuinfo This command returns 35 the following: ::
36
37 $ grep processor /proc/cpuinfo
38
39 This command returns
32 the number of processors, which takes into account hyper-threading. 40 the number of processors, which takes into account hyper-threading.
33 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
34 eight processors, which is the value you would then assign to 42 eight processors, which is the value you would then assign to
@@ -46,12 +54,12 @@ to determine what layers BitBake needs to recognize, all necessary
46``layer.conf`` files (one from each layer), and ``bitbake.conf``. The 54``layer.conf`` files (one from each layer), and ``bitbake.conf``. The
47data itself is of various types: 55data itself is of various types:
48 56
49- *Recipes:* Details about particular pieces of software. 57- **Recipes:** Details about particular pieces of software.
50 58
51- *Class Data:* An abstraction of common build information (e.g. how to 59- **Class Data:** An abstraction of common build information (e.g. how to
52 build a Linux kernel). 60 build a Linux kernel).
53 61
54- *Configuration Data:* Machine-specific settings, policy decisions, 62- **Configuration Data:** Machine-specific settings, policy decisions,
55 and so forth. Configuration data acts as the glue to bind everything 63 and so forth. Configuration data acts as the glue to bind everything
56 together. 64 together.
57 65
@@ -72,13 +80,9 @@ Prior to parsing configuration files, BitBake looks at certain
72variables, including: 80variables, including:
73 81
74- :term:`BB_ENV_WHITELIST` 82- :term:`BB_ENV_WHITELIST`
75
76- :term:`BB_ENV_EXTRAWHITE` 83- :term:`BB_ENV_EXTRAWHITE`
77
78- :term:`BB_PRESERVE_ENV` 84- :term:`BB_PRESERVE_ENV`
79
80- :term:`BB_ORIGENV` 85- :term:`BB_ORIGENV`
81
82- :term:`BITBAKE_UI` 86- :term:`BITBAKE_UI`
83 87
84The first four variables in this list relate to how BitBake treats shell 88The first four variables in this list relate to how BitBake treats shell
@@ -87,8 +91,8 @@ the environment variables and provides tight control over the shell
87execution environment. However, through the use of these first four 91execution environment. However, through the use of these first four
88variables, you can apply your control regarding the environment 92variables, you can apply your control regarding the environment
89variables allowed to be used by BitBake in the shell during execution of 93variables allowed to be used by BitBake in the shell during execution of
90tasks. See the "`Passing Information Into the Build Task 94tasks. See the
91Environment <#passing-information-into-the-build-task-environment>`__" 95":ref:`bitbake-user-manual/bitbake-user-manual-metadata:Passing Information Into the Build Task Environment`"
92section and the information about these variables in the variable 96section and the information about these variables in the variable
93glossary for more information on how they work and on how to use them. 97glossary for more information on how they work and on how to use them.
94 98
@@ -118,8 +122,8 @@ Only variable definitions and include directives are allowed in BitBake
118``.conf`` files. Some variables directly influence BitBake's behavior. 122``.conf`` files. Some variables directly influence BitBake's behavior.
119These variables might have been set from the environment depending on 123These variables might have been set from the environment depending on
120the environment variables previously mentioned or set in the 124the environment variables previously mentioned or set in the
121configuration files. The "`Variables 125configuration files. The ":ref:`bitbake-user-manual/bitbake-user-manual-ref-variables:Variables Glossary`"
122Glossary <#ref-bb-variables-glos>`__" chapter presents a full list of 126chapter presents a full list of
123variables. 127variables.
124 128
125After parsing configuration files, BitBake uses its rudimentary 129After parsing configuration files, BitBake uses its rudimentary
@@ -135,7 +139,11 @@ in ``BBPATH`` in the same way as configuration files.
135 139
136A good way to get an idea of the configuration files and the class files 140A good way to get an idea of the configuration files and the class files
137used in your execution environment is to run the following BitBake 141used in your execution environment is to run the following BitBake
138command: $ bitbake -e > mybb.log Examining the top of the ``mybb.log`` 142command: ::
143
144 $ bitbake -e > mybb.log
145
146Examining the top of the ``mybb.log``
139shows you the many configuration files and class files used in your 147shows you the many configuration files and class files used in your
140execution environment. 148execution environment.
141 149
@@ -147,15 +155,28 @@ execution environment.
147 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
148 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.
149 157
150 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: ::
151 fakeroot create_shar() { cat << "EOF" > 159
152 ${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.sh usage() { echo "test" ###### 160 fakeroot create_shar() {
153 The following "}" at the start of the line causes a parsing error 161 cat << "EOF" > ${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.sh
154 ###### } EOF } Writing the recipe this way avoids the error: fakeroot 162 usage()
155 create_shar() { cat << "EOF" > 163 {
156 ${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.sh usage() { echo "test" 164 echo "test"
157 ######The following "}" with a leading space at the start of the line 165 ###### The following "}" at the start of the line causes a parsing error ######
158 avoids the error ###### } EOF } 166 }
167 EOF
168 }
169
170 Writing the recipe this way avoids the error:
171 fakeroot create_shar() {
172 cat << "EOF" > ${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.sh
173 usage()
174 {
175 echo "test"
176 ###### The following "}" with a leading space at the start of the line avoids the error ######
177 }
178 EOF
179 }
159 180
160Locating and Parsing Recipes 181Locating and Parsing Recipes
161============================ 182============================
@@ -164,16 +185,17 @@ During the configuration phase, BitBake will have set
164:term:`BBFILES`. BitBake now uses it to construct a 185:term:`BBFILES`. BitBake now uses it to construct a
165list of recipes to parse, along with any append files (``.bbappend``) to 186list of recipes to parse, along with any append files (``.bbappend``) to
166apply. ``BBFILES`` is a space-separated list of available files and 187apply. ``BBFILES`` is a space-separated list of available files and
167supports wildcards. An example would be: BBFILES = 188supports wildcards. An example would be: ::
168"/path/to/bbfiles/*.bb /path/to/appends/*.bbappend" BitBake parses each 189
190 BBFILES = "/path/to/bbfiles/*.bb /path/to/appends/*.bbappend"
191
192BitBake parses each
169recipe and append file located with ``BBFILES`` and stores the values of 193recipe and append file located with ``BBFILES`` and stores the values of
170various variables into the datastore. 194various variables into the datastore.
171 195
172.. note:: 196.. note::
173 197
174 Append files are applied in the order they are encountered in 198 Append files are applied in the order they are encountered in BBFILES.
175 BBFILES
176 .
177 199
178For each file, a fresh copy of the base configuration is made, then the 200For each file, a fresh copy of the base configuration is made, then the
179recipe is parsed line by line. Any inherit statements cause BitBake to 201recipe is parsed line by line. Any inherit statements cause BitBake to
@@ -184,11 +206,12 @@ parses in order any append files found in ``BBFILES``.
184One common convention is to use the recipe filename to define pieces of 206One common convention is to use the recipe filename to define pieces of
185metadata. For example, in ``bitbake.conf`` the recipe name and version 207metadata. For example, in ``bitbake.conf`` the recipe name and version
186are used to set the variables :term:`PN` and 208are used to set the variables :term:`PN` and
187:term:`PV`: PN = 209:term:`PV`: ::
188"${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE', False),d)[0] or 210
189'defaultpkgname'}" PV = 211 PN = "${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE', False),d)[0] or 'defaultpkgname'}"
190"${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE', False),d)[1] or 212 PV = "${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE', False),d)[1] or '1.0'}"
191'1.0'}" In this example, a recipe called "something_1.2.3.bb" would set 213
214In this example, a recipe called "something_1.2.3.bb" would set
192``PN`` to "something" and ``PV`` to "1.2.3". 215``PN`` to "something" and ``PV`` to "1.2.3".
193 216
194By the time parsing is complete for a recipe, BitBake has a list of 217By the time parsing is complete for a recipe, BitBake has a list of
@@ -215,11 +238,13 @@ Recipe file collections exist to allow the user to have multiple
215repositories of ``.bb`` files that contain the same exact package. For 238repositories of ``.bb`` files that contain the same exact package. For
216example, one could easily use them to make one's own local copy of an 239example, one could easily use them to make one's own local copy of an
217upstream repository, but with custom modifications that one does not 240upstream repository, but with custom modifications that one does not
218want upstream. Here is an example: BBFILES = "/stuff/openembedded/*/*.bb 241want upstream. Here is an example: ::
219/stuff/openembedded.modified/*/*.bb" BBFILE_COLLECTIONS = "upstream 242
220local" BBFILE_PATTERN_upstream = "^/stuff/openembedded/" 243 BBFILES = "/stuff/openembedded/*/*.bb /stuff/openembedded.modified/*/*.bb"
221BBFILE_PATTERN_local = "^/stuff/openembedded.modified/" 244 BBFILE_COLLECTIONS = "upstream local"
222BBFILE_PRIORITY_upstream = "5" BBFILE_PRIORITY_local = "10" 245 BBFILE_PATTERN_upstream = "^/stuff/openembedded/"
246 BBFILE_PATTERN_local = "^/stuff/openembedded.modified/"
247 BBFILE_PRIORITY_upstream = "5" BBFILE_PRIORITY_local = "10"
223 248
224.. note:: 249.. note::
225 250
@@ -244,7 +269,11 @@ variable, which is optional.
244When a recipe uses ``PROVIDES``, that recipe's functionality can be 269When a recipe uses ``PROVIDES``, that recipe's functionality can be
245found under an alternative name or names other than the implicit ``PN`` 270found under an alternative name or names other than the implicit ``PN``
246name. As an example, suppose a recipe named ``keyboard_1.0.bb`` 271name. As an example, suppose a recipe named ``keyboard_1.0.bb``
247contained the following: PROVIDES += "fullkeyboard" The ``PROVIDES`` 272contained the following: ::
273
274 PROVIDES += "fullkeyboard"
275
276The ``PROVIDES``
248list for this recipe becomes "keyboard", which is implicit, and 277list for this recipe becomes "keyboard", which is implicit, and
249"fullkeyboard", which is explicit. Consequently, the functionality found 278"fullkeyboard", which is explicit. Consequently, the functionality found
250in ``keyboard_1.0.bb`` can be found under two different names. 279in ``keyboard_1.0.bb`` can be found under two different names.
@@ -261,9 +290,11 @@ needs to prioritize providers by determining provider preferences.
261A common example in which a target has multiple providers is 290A common example in which a target has multiple providers is
262"virtual/kernel", which is on the ``PROVIDES`` list for each kernel 291"virtual/kernel", which is on the ``PROVIDES`` list for each kernel
263recipe. Each machine often selects the best kernel provider by using a 292recipe. Each machine often selects the best kernel provider by using a
264line similar to the following in the machine configuration file: 293line similar to the following in the machine configuration file: ::
265PREFERRED_PROVIDER_virtual/kernel = "linux-yocto" The default 294
266:term:`PREFERRED_PROVIDER` is the provider 295 PREFERRED_PROVIDER_virtual/kernel = "linux-yocto"
296
297The default :term:`PREFERRED_PROVIDER` is the provider
267with the same name as the target. BitBake iterates through each target 298with the same name as the target. BitBake iterates through each target
268it needs to build and resolves them and their dependencies using this 299it needs to build and resolves them and their dependencies using this
269process. 300process.
@@ -299,8 +330,9 @@ If the first recipe is named ``a_1.1.bb``, then the
299 330
300Thus, if a recipe named ``a_1.2.bb`` exists, BitBake will choose 1.2 by 331Thus, if a recipe named ``a_1.2.bb`` exists, BitBake will choose 1.2 by
301default. However, if you define the following variable in a ``.conf`` 332default. However, if you define the following variable in a ``.conf``
302file that BitBake parses, you can change that preference: 333file that BitBake parses, you can change that preference: ::
303PREFERRED_VERSION_a = "1.1" 334
335 PREFERRED_VERSION_a = "1.1"
304 336
305.. note:: 337.. note::
306 338
@@ -312,7 +344,11 @@ PREFERRED_VERSION_a = "1.1"
312 For example, in the OpenEmbedded codebase, there is a standard, 344 For example, in the OpenEmbedded codebase, there is a standard,
313 versioned recipe file for BusyBox, ``busybox_1.22.1.bb``, but there 345 versioned recipe file for BusyBox, ``busybox_1.22.1.bb``, but there
314 is also a Git-based version, ``busybox_git.bb``, which explicitly 346 is also a Git-based version, ``busybox_git.bb``, which explicitly
315 contains the line DEFAULT_PREFERENCE = "-1" to ensure that the 347 contains the line ::
348
349 DEFAULT_PREFERENCE = "-1"
350
351 to ensure that the
316 numbered, stable version is always preferred unless the developer 352 numbered, stable version is always preferred unless the developer
317 selects otherwise. 353 selects otherwise.
318 354
@@ -327,15 +363,16 @@ performance on multi-core systems, BitBake considers each task as an
327independent entity with its own set of dependencies. 363independent entity with its own set of dependencies.
328 364
329Dependencies are defined through several variables. You can find 365Dependencies are defined through several variables. You can find
330information about variables BitBake uses in the `Variables 366information about variables BitBake uses in the
331Glossary <#ref-bb-variables-glos>`__ near the end of this manual. At a 367:doc:`bitbake-user-manual-ref-variables` near the end of this manual. At a
332basic level, it is sufficient to know that BitBake uses the 368basic level, it is sufficient to know that BitBake uses the
333:term:`DEPENDS` and 369:term:`DEPENDS` and
334:term:`RDEPENDS` variables when calculating 370:term:`RDEPENDS` variables when calculating
335dependencies. 371dependencies.
336 372
337For more information on how BitBake handles dependencies, see the 373For more information on how BitBake handles dependencies, see the
338"`Dependencies <#dependencies>`__" section. 374:ref:`bitbake-user-manual/bitbake-user-manual-metadata:Dependencies`
375section.
339 376
340.. _ref-bitbake-tasklist: 377.. _ref-bitbake-tasklist:
341 378
@@ -344,7 +381,8 @@ The Task List
344 381
345Based on the generated list of providers and the dependency information, 382Based on the generated list of providers and the dependency information,
346BitBake can now calculate exactly what tasks it needs to run and in what 383BitBake can now calculate exactly what tasks it needs to run and in what
347order it needs to run them. The "`Executing Tasks <#executing-tasks>`__" 384order it needs to run them. The
385:ref:`bitbake-user-manual/bitbake-user-manual-execution:executing tasks`
348section has more information on how BitBake chooses which task to 386section has more information on how BitBake chooses which task to
349execute next. 387execute next.
350 388
@@ -371,8 +409,9 @@ The exact format of the stamps is partly configurable. In modern
371versions of BitBake, a hash is appended to the stamp so that if the 409versions of BitBake, a hash is appended to the stamp so that if the
372configuration changes, the stamp becomes invalid and the task is 410configuration changes, the stamp becomes invalid and the task is
373automatically rerun. This hash, or signature used, is governed by the 411automatically rerun. This hash, or signature used, is governed by the
374signature policy that is configured (see the "`Checksums 412signature policy that is configured (see the
375(Signatures) <#checksums>`__" section for information). It is also 413:ref:`bitbake-user-manual/bitbake-user-manual-execution:checksums (signatures)`
414section for information). It is also
376possible to append extra metadata to the stamp using the 415possible to append extra metadata to the stamp using the
377``[stamp-extra-info]`` task flag. For example, OpenEmbedded uses this 416``[stamp-extra-info]`` task flag. For example, OpenEmbedded uses this
378flag to make some tasks machine-specific. 417flag to make some tasks machine-specific.
@@ -383,7 +422,8 @@ flag to make some tasks machine-specific.
383 created when these tasks are run. Consequently, "nostamp" tasks are 422 created when these tasks are run. Consequently, "nostamp" tasks are
384 always rerun. 423 always rerun.
385 424
386For more information on tasks, see the "`Tasks <#tasks>`__" section. 425For more information on tasks, see the
426:ref:`bitbake-user-manual/bitbake-user-manual-metadata:tasks` section.
387 427
388Executing Tasks 428Executing Tasks
389=============== 429===============
@@ -457,14 +497,21 @@ to the task.
457 497
458Like the working directory case, situations exist where dependencies 498Like the working directory case, situations exist where dependencies
459should be ignored. For these cases, you can instruct the build process 499should be ignored. For these cases, you can instruct the build process
460to ignore a dependency by using a line like the following: 500to ignore a dependency by using a line like the following: ::
461PACKAGE_ARCHS[vardepsexclude] = "MACHINE" This example ensures that the 501
502 PACKAGE_ARCHS[vardepsexclude] = "MACHINE"
503
504This example ensures that the
462``PACKAGE_ARCHS`` variable does not depend on the value of ``MACHINE``, 505``PACKAGE_ARCHS`` variable does not depend on the value of ``MACHINE``,
463even if it does reference it. 506even if it does reference it.
464 507
465Equally, there are cases where we need to add dependencies BitBake is 508Equally, there are cases where we need to add dependencies BitBake is
466not able to find. You can accomplish this by using a line like the 509not able to find. You can accomplish this by using a line like the
467following: PACKAGE_ARCHS[vardeps] = "MACHINE" This example explicitly 510following: ::
511
512 PACKAGE_ARCHS[vardeps] = "MACHINE"
513
514This example explicitly
468adds the ``MACHINE`` variable as a dependency for ``PACKAGE_ARCHS``. 515adds the ``MACHINE`` variable as a dependency for ``PACKAGE_ARCHS``.
469 516
470Consider a case with in-line Python, for example, where BitBake is not 517Consider a case with in-line Python, for example, where BitBake is not
@@ -488,13 +535,15 @@ configuration file, we can give BitBake some extra information to help
488it construct the basehash. The following statement effectively results 535it construct the basehash. The following statement effectively results
489in a list of global variable dependency excludes - variables never 536in a list of global variable dependency excludes - variables never
490included in any checksum. This example uses variables from OpenEmbedded 537included in any checksum. This example uses variables from OpenEmbedded
491to help illustrate the concept: BB_HASHBASE_WHITELIST ?= "TMPDIR FILE 538to help illustrate the concept: ::
492PATH PWD BB_TASKHASH BBPATH DL_DIR \\ SSTATE_DIR THISDIR FILESEXTRAPATHS 539
493FILE_DIRNAME HOME LOGNAME SHELL \\ USER FILESPATH STAGING_DIR_HOST 540 BB_HASHBASE_WHITELIST ?= "TMPDIR FILE PATH PWD BB_TASKHASH BBPATH DL_DIR \
494STAGING_DIR_TARGET COREBASE PRSERV_HOST \\ PRSERV_DUMPDIR 541 SSTATE_DIR THISDIR FILESEXTRAPATHS FILE_DIRNAME HOME LOGNAME SHELL \
495PRSERV_DUMPFILE PRSERV_LOCKDOWN PARALLEL_MAKE \\ CCACHE_DIR 542 USER FILESPATH STAGING_DIR_HOST STAGING_DIR_TARGET COREBASE PRSERV_HOST \
496EXTERNAL_TOOLCHAIN CCACHE CCACHE_DISABLE LICENSE_PATH SDKPKGSUFFIX" The 543 PRSERV_DUMPDIR PRSERV_DUMPFILE PRSERV_LOCKDOWN PARALLEL_MAKE \
497previous example excludes the work directory, which is part of 544 CCACHE_DIR EXTERNAL_TOOLCHAIN CCACHE CCACHE_DISABLE LICENSE_PATH SDKPKGSUFFIX"
545
546The previous example excludes the work directory, which is part of
498``TMPDIR``. 547``TMPDIR``.
499 548
500The rules for deciding which hashes of dependent tasks to include 549The rules for deciding which hashes of dependent tasks to include
@@ -507,8 +556,11 @@ OpenEmbedded-Core uses: "OEBasic" and "OEBasicHash". By default, there
507is a dummy "noop" signature handler enabled in BitBake. This means that 556is a dummy "noop" signature handler enabled in BitBake. This means that
508behavior is unchanged from previous versions. ``OE-Core`` uses the 557behavior is unchanged from previous versions. ``OE-Core`` uses the
509"OEBasicHash" signature handler by default through this setting in the 558"OEBasicHash" signature handler by default through this setting in the
510``bitbake.conf`` file: BB_SIGNATURE_HANDLER ?= "OEBasicHash" The 559``bitbake.conf`` file: ::
511"OEBasicHash" ``BB_SIGNATURE_HANDLER`` is the same as the "OEBasic" 560
561 BB_SIGNATURE_HANDLER ?= "OEBasicHash"
562
563The "OEBasicHash" ``BB_SIGNATURE_HANDLER`` is the same as the "OEBasic"
512version but adds the task hash to the stamp files. This results in any 564version but adds the task hash to the stamp files. This results in any
513metadata change that changes the task hash, automatically causing the 565metadata change that changes the task hash, automatically causing the
514task to be run again. This removes the need to bump 566task to be run again. This removes the need to bump
@@ -519,13 +571,13 @@ It is also worth noting that the end result of these signature
519generators is to make some dependency and hash information available to 571generators is to make some dependency and hash information available to
520the build. This information includes: 572the build. This information includes:
521 573
522- ``BB_BASEHASH_task-``\ taskname: The base hashes for each task in the 574- ``BB_BASEHASH_task-``\ *taskname*: The base hashes for each task in the
523 recipe. 575 recipe.
524 576
525- ``BB_BASEHASH_``\ filename\ ``:``\ taskname: The base hashes for each 577- ``BB_BASEHASH_``\ *filename:taskname*: The base hashes for each
526 dependent task. 578 dependent task.
527 579
528- ``BBHASHDEPS_``\ filename\ ``:``\ taskname: The task dependencies for 580- ``BBHASHDEPS_``\ *filename:taskname*: The task dependencies for
529 each task. 581 each task.
530 582
531- ``BB_TASKHASH``: The hash of the currently running task. 583- ``BB_TASKHASH``: The hash of the currently running task.
@@ -547,8 +599,9 @@ where these two stamp trees diverge.
547 It is likely that future versions of BitBake will provide other 599 It is likely that future versions of BitBake will provide other
548 signature handlers triggered through additional "-S" parameters. 600 signature handlers triggered through additional "-S" parameters.
549 601
550You can find more information on checksum metadata in the "`Task 602You can find more information on checksum metadata in the
551Checksums and Setscene <#task-checksums-and-setscene>`__" section. 603:ref:`bitbake-user-manual/bitbake-user-manual-metadata:task checksums and setscene`
604section.
552 605
553Setscene 606Setscene
554======== 607========
@@ -601,8 +654,9 @@ with the list of tasks BitBake thinks has been "covered". The metadata
601can then ensure that this list is correct and can inform BitBake that it 654can then ensure that this list is correct and can inform BitBake that it
602wants specific tasks to be run regardless of the setscene result. 655wants specific tasks to be run regardless of the setscene result.
603 656
604You can find more information on setscene metadata in the "`Task 657You can find more information on setscene metadata in the
605Checksums and Setscene <#task-checksums-and-setscene>`__" section. 658:ref:`bitbake-user-manual/bitbake-user-manual-metadata:task checksums and setscene`
659section.
606 660
607Logging 661Logging
608======= 662=======
@@ -648,11 +702,32 @@ logging configuration is merged using the following rules:
648 702
649As an example, consider the following user logging configuration file 703As an example, consider the following user logging configuration file
650which logs all Hash Equivalence related messages of VERBOSE or higher to 704which logs all Hash Equivalence related messages of VERBOSE or higher to
651a file called ``hashequiv.log`` { "version": 1, "handlers": { 705a file called ``hashequiv.log`` ::
652"autobuilderlog": { "class": "logging.FileHandler", "formatter": 706
653"logfileFormatter", "level": "DEBUG", "filename": "hashequiv.log", 707 {
654"mode": "w" } }, "formatters": { "logfileFormatter": { "format": 708 "version": 1,
655"%(name)s: %(levelname)s: %(message)s" } }, "loggers": { 709 "handlers": {
656"BitBake.SigGen.HashEquiv": { "level": "VERBOSE", "handlers": 710 "autobuilderlog": {
657["autobuilderlog"] }, "BitBake.RunQueue.HashEquiv": { "level": 711 "class": "logging.FileHandler",
658"VERBOSE", "handlers": ["autobuilderlog"] } } } 712 "formatter": "logfileFormatter",
713 "level": "DEBUG",
714 "filename": "hashequiv.log",
715 "mode": "w"
716 }
717 },
718 "formatters": {
719 "logfileFormatter": {
720 "format": "%(name)s: %(levelname)s: %(message)s"
721 }
722 },
723 "loggers": {
724 "BitBake.SigGen.HashEquiv": {
725 "level": "VERBOSE",
726 "handlers": ["autobuilderlog"]
727 },
728 "BitBake.RunQueue.HashEquiv": {
729 "level": "VERBOSE",
730 "handlers": ["autobuilderlog"]
731 }
732 }
733 }
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 a8815f3e22..f62ddffe8e 100644
--- a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-fetching.rst
+++ b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-fetching.rst
@@ -27,22 +27,28 @@ and unpacking the files is often optionally followed by patching.
27Patching, however, is not covered by this module. 27Patching, however, is not covered by this module.
28 28
29The code to execute the first part of this process, a fetch, looks 29The code to execute the first part of this process, a fetch, looks
30something like the following: src_uri = (d.getVar('SRC_URI') or 30something like the following: ::
31"").split() fetcher = bb.fetch2.Fetch(src_uri, d) fetcher.download() 31
32 src_uri = (d.getVar('SRC_URI') or "").split()
33 fetcher = bb.fetch2.Fetch(src_uri, d)
34 fetcher.download()
35
32This code sets up an instance of the fetch class. The instance uses a 36This code sets up an instance of the fetch class. The instance uses a
33space-separated list of URLs from the :term:`SRC_URI` 37space-separated list of URLs from the :term:`SRC_URI`
34variable and then calls the ``download`` method to download the files. 38variable and then calls the ``download`` method to download the files.
35 39
36The instantiation of the fetch class is usually followed by: rootdir = 40The instantiation of the fetch class is usually followed by: ::
37l.getVar('WORKDIR') fetcher.unpack(rootdir) This code unpacks the 41
38downloaded files to the specified by ``WORKDIR``. 42 rootdir = l.getVar('WORKDIR')
43 fetcher.unpack(rootdir)
44
45This code unpacks the downloaded files to the specified by ``WORKDIR``.
39 46
40.. note:: 47.. note::
41 48
42 For convenience, the naming in these examples matches the variables 49 For convenience, the naming in these examples matches the variables
43 used by OpenEmbedded. If you want to see the above code in action, 50 used by OpenEmbedded. If you want to see the above code in action,
44 examine the OpenEmbedded class file 51 examine the OpenEmbedded class file ``base.bbclass``
45 base.bbclass
46 . 52 .
47 53
48The ``SRC_URI`` and ``WORKDIR`` variables are not hardcoded into the 54The ``SRC_URI`` and ``WORKDIR`` variables are not hardcoded into the
@@ -61,30 +67,37 @@ URLs by looking for source files in a specific search order:
61 from ``SRC_URI``). 67 from ``SRC_URI``).
62 68
63- *Mirror Sites:* If fetch failures occur, BitBake next uses mirror 69- *Mirror Sites:* If fetch failures occur, BitBake next uses mirror
64 locations as defined by the :term:`MIRRORS` 70 locations as defined by the :term:`MIRRORS` variable.
65 variable.
66 71
67For each URL passed to the fetcher, the fetcher calls the submodule that 72For each URL passed to the fetcher, the fetcher calls the submodule that
68handles that particular URL type. This behavior can be the source of 73handles that particular URL type. This behavior can be the source of
69some confusion when you are providing URLs for the ``SRC_URI`` variable. 74some confusion when you are providing URLs for the ``SRC_URI`` variable.
70Consider the following two URLs: 75Consider the following two URLs: ::
71http://git.yoctoproject.org/git/poky;protocol=git 76
72git://git.yoctoproject.org/git/poky;protocol=http In the former case, 77 http://git.yoctoproject.org/git/poky;protocol=git
73the URL is passed to the ``wget`` fetcher, which does not understand 78 git://git.yoctoproject.org/git/poky;protocol=http
74"git". Therefore, the latter case is the correct form since the Git 79
80In the former case, the URL is passed to the ``wget`` fetcher, which does not
81understand "git". Therefore, the latter case is the correct form since the Git
75fetcher does know how to use HTTP as a transport. 82fetcher does know how to use HTTP as a transport.
76 83
77Here are some examples that show commonly used mirror definitions: 84Here are some examples that show commonly used mirror definitions: ::
78PREMIRRORS ?= "\\ bzr://.*/.\* http://somemirror.org/sources/ \\n \\ 85
79cvs://.*/.\* http://somemirror.org/sources/ \\n \\ git://.*/.\* 86 PREMIRRORS ?= "\
80http://somemirror.org/sources/ \\n \\ hg://.*/.\* 87 bzr://.*/.\* http://somemirror.org/sources/ \\n \
81http://somemirror.org/sources/ \\n \\ osc://.*/.\* 88 cvs://.*/.\* http://somemirror.org/sources/ \\n \
82http://somemirror.org/sources/ \\n \\ p4://.*/.\* 89 git://.*/.\* http://somemirror.org/sources/ \\n \
83http://somemirror.org/sources/ \\n \\ svn://.*/.\* 90 hg://.*/.\* http://somemirror.org/sources/ \\n \
84http://somemirror.org/sources/ \\n" MIRRORS =+ "\\ ftp://.*/.\* 91 osc://.*/.\* http://somemirror.org/sources/ \\n \
85http://somemirror.org/sources/ \\n \\ http://.*/.\* 92 p4://.*/.\* http://somemirror.org/sources/ \\n \
86http://somemirror.org/sources/ \\n \\ https://.*/.\* 93 svn://.*/.\* http://somemirror.org/sources/ \\n"
87http://somemirror.org/sources/ \\n" It is useful to note that BitBake 94
95 MIRRORS =+ "\
96 ftp://.*/.\* http://somemirror.org/sources/ \\n \
97 http://.*/.\* http://somemirror.org/sources/ \\n \
98 https://.*/.\* http://somemirror.org/sources/ \\n"
99
100It is useful to note that BitBake
88supports cross-URLs. It is possible to mirror a Git repository on an 101supports cross-URLs. It is possible to mirror a Git repository on an
89HTTP server as a tarball. This is what the ``git://`` mapping in the 102HTTP server as a tarball. This is what the ``git://`` mapping in the
90previous example does. 103previous example does.
@@ -98,15 +111,24 @@ File integrity is of key importance for reproducing builds. For
98non-local archive downloads, the fetcher code can verify SHA-256 and MD5 111non-local archive downloads, the fetcher code can verify SHA-256 and MD5
99checksums to ensure the archives have been downloaded correctly. You can 112checksums to ensure the archives have been downloaded correctly. You can
100specify these checksums by using the ``SRC_URI`` variable with the 113specify these checksums by using the ``SRC_URI`` variable with the
101appropriate varflags as follows: SRC_URI[md5sum] = "value" 114appropriate varflags as follows: ::
102SRC_URI[sha256sum] = "value" You can also specify the checksums as 115
103parameters on the ``SRC_URI`` as shown below: SRC_URI = 116 SRC_URI[md5sum] = "value"
104"http://example.com/foobar.tar.bz2;md5sum=4a8e0f237e961fd7785d19d07fdb994d" 117 SRC_URI[sha256sum] = "value"
118
119You can also specify the checksums as
120parameters on the ``SRC_URI`` as shown below: ::
121
122 SRC_URI = "http://example.com/foobar.tar.bz2;md5sum=4a8e0f237e961fd7785d19d07fdb994d"
123
105If multiple URIs exist, you can specify the checksums either directly as 124If multiple URIs exist, you can specify the checksums either directly as
106in the previous example, or you can name the URLs. The following syntax 125in the previous example, or you can name the URLs. The following syntax
107shows how you name the URIs: SRC_URI = 126shows how you name the URIs: ::
108"http://example.com/foobar.tar.bz2;name=foo" SRC_URI[foo.md5sum] = 127
1094a8e0f237e961fd7785d19d07fdb994d After a file has been downloaded and 128 SRC_URI = "http://example.com/foobar.tar.bz2;name=foo"
129 SRC_URI[foo.md5sum] = 4a8e0f237e961fd7785d19d07fdb994d
130
131After a file has been downloaded and
110has had its checksum checked, a ".done" stamp is placed in ``DL_DIR``. 132has had its checksum checked, a ".done" stamp is placed in ``DL_DIR``.
111BitBake uses this stamp during subsequent builds to avoid downloading or 133BitBake uses this stamp during subsequent builds to avoid downloading or
112comparing a checksum for the file again. 134comparing a checksum for the file again.
@@ -182,8 +204,10 @@ time the ``download()`` method is called.
182If you specify a directory, the entire directory is unpacked. 204If you specify a directory, the entire directory is unpacked.
183 205
184Here are a couple of example URLs, the first relative and the second 206Here are a couple of example URLs, the first relative and the second
185absolute: SRC_URI = "file://relativefile.patch" SRC_URI = 207absolute: ::
186"file:///Users/ich/very_important_software" 208
209 SRC_URI = "file://relativefile.patch"
210 SRC_URI = "file:///Users/ich/very_important_software"
187 211
188.. _http-ftp-fetcher: 212.. _http-ftp-fetcher:
189 213
@@ -201,10 +225,11 @@ downloaded file is useful for avoiding collisions in
201:term:`DL_DIR` when dealing with multiple files that 225:term:`DL_DIR` when dealing with multiple files that
202have the same name. 226have the same name.
203 227
204Some example URLs are as follows: SRC_URI = 228Some example URLs are as follows: ::
205"http://oe.handhelds.org/not_there.aac" SRC_URI = 229
206"ftp://oe.handhelds.org/not_there_as_well.aac" SRC_URI = 230 SRC_URI = "http://oe.handhelds.org/not_there.aac"
207"ftp://you@oe.handhelds.org/home/you/secret.plan" 231 SRC_URI = "ftp://oe.handhelds.org/not_there_as_well.aac"
232 SRC_URI = "ftp://you@oe.handhelds.org/home/you/secret.plan"
208 233
209.. note:: 234.. note::
210 235
@@ -214,14 +239,14 @@ Some example URLs are as follows: SRC_URI =
214 :: 239 ::
215 240
216 SRC_URI = "http://abc123.org/git/?p=gcc/gcc.git;a=snapshot;h=a5dd47" 241 SRC_URI = "http://abc123.org/git/?p=gcc/gcc.git;a=snapshot;h=a5dd47"
217 242
218 243
219 Such URLs should should be modified by replacing semi-colons with '&' 244 Such URLs should should be modified by replacing semi-colons with '&'
220 characters: 245 characters:
221 :: 246 ::
222 247
223 SRC_URI = "http://abc123.org/git/?p=gcc/gcc.git&a=snapshot&h=a5dd47" 248 SRC_URI = "http://abc123.org/git/?p=gcc/gcc.git&a=snapshot&h=a5dd47"
224 249
225 250
226 In most cases this should work. Treating semi-colons and '&' in 251 In most cases this should work. Treating semi-colons and '&' in
227 queries identically is recommended by the World Wide Web Consortium 252 queries identically is recommended by the World Wide Web Consortium
@@ -230,7 +255,7 @@ Some example URLs are as follows: SRC_URI =
230 :: 255 ::
231 256
232 SRC_URI = "http://abc123.org/git/?p=gcc/gcc.git&a=snapshot&h=a5dd47;downloadfilename=myfile.bz2" 257 SRC_URI = "http://abc123.org/git/?p=gcc/gcc.git&a=snapshot&h=a5dd47;downloadfilename=myfile.bz2"
233 258
234 259
235.. _cvs-fetcher: 260.. _cvs-fetcher:
236 261
@@ -240,20 +265,20 @@ CVS fetcher (``(cvs://``)
240This submodule handles checking out files from the CVS version control 265This submodule handles checking out files from the CVS version control
241system. You can configure it using a number of different variables: 266system. You can configure it using a number of different variables:
242 267
243- *``FETCHCMD_cvs``:* The name of the executable to use when running 268- :term:`FETCHCMD_cvs <FETCHCMD>`: The name of the executable to use when running
244 the ``cvs`` command. This name is usually "cvs". 269 the ``cvs`` command. This name is usually "cvs".
245 270
246- *``SRCDATE``:* The date to use when fetching the CVS source code. A 271- :term:`SRCDATE`: The date to use when fetching the CVS source code. A
247 special value of "now" causes the checkout to be updated on every 272 special value of "now" causes the checkout to be updated on every
248 build. 273 build.
249 274
250- :term:`CVSDIR`\ *:* Specifies where a temporary 275- :term:`CVSDIR`: Specifies where a temporary
251 checkout is saved. The location is often ``DL_DIR/cvs``. 276 checkout is saved. The location is often ``DL_DIR/cvs``.
252 277
253- *``CVS_PROXY_HOST``:* The name to use as a "proxy=" parameter to the 278- CVS_PROXY_HOST: The name to use as a "proxy=" parameter to the
254 ``cvs`` command. 279 ``cvs`` command.
255 280
256- *``CVS_PROXY_PORT``:* The port number to use as a "proxyport=" 281- CVS_PROXY_PORT: The port number to use as a "proxyport="
257 parameter to the ``cvs`` command. 282 parameter to the ``cvs`` command.
258 283
259As well as the standard username and password URL syntax, you can also 284As well as the standard username and password URL syntax, you can also
@@ -282,7 +307,7 @@ The supported parameters are as follows:
282 are forcing the module into a special directory relative to 307 are forcing the module into a special directory relative to
283 :term:`CVSDIR`. 308 :term:`CVSDIR`.
284 309
285- *"rsh"* Used in conjunction with the "method" parameter. 310- *"rsh":* Used in conjunction with the "method" parameter.
286 311
287- *"scmdata":* Causes the CVS metadata to be maintained in the tarball 312- *"scmdata":* Causes the CVS metadata to be maintained in the tarball
288 the fetcher creates when set to "keep". The tarball is expanded into 313 the fetcher creates when set to "keep". The tarball is expanded into
@@ -296,9 +321,10 @@ The supported parameters are as follows:
296 321
297- *"port":* The port to which the CVS server connects. 322- *"port":* The port to which the CVS server connects.
298 323
299Some example URLs are as follows: SRC_URI = 324Some example URLs are as follows: ::
300"cvs://CVSROOT;module=mymodule;tag=some-version;method=ext" SRC_URI = 325
301"cvs://CVSROOT;module=mymodule;date=20060126;localdir=usethat" 326 SRC_URI = "cvs://CVSROOT;module=mymodule;tag=some-version;method=ext"
327 SRC_URI = "cvs://CVSROOT;module=mymodule;date=20060126;localdir=usethat"
302 328
303.. _svn-fetcher: 329.. _svn-fetcher:
304 330
@@ -337,10 +363,11 @@ The supported parameters are as follows:
337 username is different than the username used in the main URL, which 363 username is different than the username used in the main URL, which
338 is passed to the subversion command. 364 is passed to the subversion command.
339 365
340Following are three examples using svn: SRC_URI = 366Following are three examples using svn: ::
341"svn://myrepos/proj1;module=vip;protocol=http;rev=667" SRC_URI = 367
342"svn://myrepos/proj1;module=opie;protocol=svn+ssh" SRC_URI = 368 SRC_URI = "svn://myrepos/proj1;module=vip;protocol=http;rev=667"
343"svn://myrepos/proj1;module=trunk;protocol=http;path_spec=${MY_DIR}/proj1" 369 SRC_URI = "svn://myrepos/proj1;module=opie;protocol=svn+ssh"
370 SRC_URI = "svn://myrepos/proj1;module=trunk;protocol=http;path_spec=${MY_DIR}/proj1"
344 371
345.. _git-fetcher: 372.. _git-fetcher:
346 373
@@ -409,20 +436,22 @@ This fetcher supports the following parameters:
409 parameter implies no branch and only works when the transfer protocol 436 parameter implies no branch and only works when the transfer protocol
410 is ``file://``. 437 is ``file://``.
411 438
412Here are some example URLs: SRC_URI = 439Here are some example URLs: ::
413"git://git.oe.handhelds.org/git/vip.git;tag=version-1" SRC_URI = 440
414"git://git.oe.handhelds.org/git/vip.git;protocol=http" 441 SRC_URI = "git://git.oe.handhelds.org/git/vip.git;tag=version-1"
442 SRC_URI = "git://git.oe.handhelds.org/git/vip.git;protocol=http"
415 443
416.. _gitsm-fetcher: 444.. _gitsm-fetcher:
417 445
418Git Submodule Fetcher (``gitsm://``) 446Git Submodule Fetcher (``gitsm://``)
419------------------------------------ 447------------------------------------
420 448
421This fetcher submodule inherits from the `Git fetcher <#git-fetcher>`__ 449This fetcher submodule inherits from the :ref:`Git
422and extends that fetcher's behavior by fetching a repository's 450fetcher<bitbake-user-manual/bitbake-user-manual-fetching:git fetcher
423submodules. :term:`SRC_URI` is passed to the Git 451(\`\`git://\`\`)>` and extends that fetcher's behavior by fetching a
424fetcher as described in the "`Git Fetcher 452repository's submodules. :term:`SRC_URI` is passed to the Git fetcher as
425(``git://``) <#git-fetcher>`__" section. 453described in the :ref:`bitbake-user-manual/bitbake-user-manual-fetching:git
454fetcher (\`\`git://\`\`)` section.
426 455
427.. note:: 456.. note::
428 457
@@ -446,42 +475,33 @@ repository.
446 475
447To use this fetcher, make sure your recipe has proper 476To use this fetcher, make sure your recipe has proper
448:term:`SRC_URI`, :term:`SRCREV`, and 477:term:`SRC_URI`, :term:`SRCREV`, and
449:term:`PV` settings. Here is an example: SRC_URI = 478:term:`PV` settings. Here is an example: ::
450"ccrc://cc.example.org/ccrc;vob=/example_vob;module=/example_module" 479
451SRCREV = "EXAMPLE_CLEARCASE_TAG" PV = "${@d.getVar("SRCREV", 480 SRC_URI = "ccrc://cc.example.org/ccrc;vob=/example_vob;module=/example_module"
452False).replace("/", "+")}" The fetcher uses the ``rcleartool`` or 481 SRCREV = "EXAMPLE_CLEARCASE_TAG"
482 PV = "${@d.getVar("SRCREV", False).replace("/", "+")}"
483
484The fetcher uses the ``rcleartool`` or
453``cleartool`` remote client, depending on which one is available. 485``cleartool`` remote client, depending on which one is available.
454 486
455Following are options for the ``SRC_URI`` statement: 487Following are options for the ``SRC_URI`` statement:
456 488
457- *``vob``*: The name, which must include the prepending "/" character, 489- *vob*: The name, which must include the prepending "/" character,
458 of the ClearCase VOB. This option is required. 490 of the ClearCase VOB. This option is required.
459 491
460- *``module``*: The module, which must include the prepending "/" 492- *module*: The module, which must include the prepending "/"
461 character, in the selected VOB. 493 character, in the selected VOB.
462 494
463 .. note:: 495 .. note::
464 496
465 The 497 The module and vob options are combined to create the load rule in the
466 module 498 view config spec. As an example, consider the vob and module values from
467 and 499 the SRC_URI statement at the start of this section. Combining those values
468 vob 500 results in the following: ::
469 options are combined to create the 501
470 load 502 load /example_vob/example_module
471 rule in the view config spec. As an example, consider the 503
472 vob 504- *proto*: The protocol, which can be either ``http`` or ``https``.
473 and
474 module
475 values from the
476 SRC_URI
477 statement at the start of this section. Combining those values
478 results in the following:
479 ::
480
481 load /example_vob/example_module
482
483
484- *``proto``*: The protocol, which can be either ``http`` or ``https``.
485 505
486By default, the fetcher creates a configuration specification. If you 506By default, the fetcher creates a configuration specification. If you
487want this specification written to an area other than the default, use 507want this specification written to an area other than the default, use
@@ -490,11 +510,8 @@ the specification is written.
490 510
491.. note:: 511.. note::
492 512
493 the 513 the SRCREV loses its functionality if you specify this variable. However,
494 SRCREV 514 SRCREV is still used to label the archive after a fetch even though it does
495 loses its functionality if you specify this variable. However,
496 SRCREV
497 is still used to label the archive after a fetch even though it does
498 not define what is fetched. 515 not define what is fetched.
499 516
500Here are a couple of other behaviors worth mentioning: 517Here are a couple of other behaviors worth mentioning:
@@ -532,34 +549,36 @@ the server's URL and port number, and you can specify a username and
532password directly in your recipe within ``SRC_URI``. 549password directly in your recipe within ``SRC_URI``.
533 550
534Here is an example that relies on ``P4CONFIG`` to specify the server URL 551Here is an example that relies on ``P4CONFIG`` to specify the server URL
535and port, username, and password, and fetches the Head Revision: SRC_URI 552and port, username, and password, and fetches the Head Revision: ::
536= "p4://example-depot/main/source/..." SRCREV = "${AUTOREV}" PV = 553
537"p4-${SRCPV}" S = "${WORKDIR}/p4" 554 SRC_URI = "p4://example-depot/main/source/..."
555 SRCREV = "${AUTOREV}"
556 PV = "p4-${SRCPV}"
557 S = "${WORKDIR}/p4"
538 558
539Here is an example that specifies the server URL and port, username, and 559Here is an example that specifies the server URL and port, username, and
540password, and fetches a Revision based on a Label: P4PORT = 560password, and fetches a Revision based on a Label: ::
541"tcp:p4server.example.net:1666" SRC_URI = 561
542"p4://user:passwd@example-depot/main/source/..." SRCREV = "release-1.0" 562 P4PORT = "tcp:p4server.example.net:1666"
543PV = "p4-${SRCPV}" S = "${WORKDIR}/p4" 563 SRC_URI = "p4://user:passwd@example-depot/main/source/..."
564 SRCREV = "release-1.0"
565 PV = "p4-${SRCPV}"
566 S = "${WORKDIR}/p4"
544 567
545.. note:: 568.. note::
546 569
547 You should always set 570 You should always set S to "${WORKDIR}/p4" in your recipe.
548 S
549 to
550 "${WORKDIR}/p4"
551 in your recipe.
552 571
553By default, the fetcher strips the depot location from the local file paths. In 572By default, the fetcher strips the depot location from the local file paths. In
554the above example, the content of ``example-depot/main/source/`` will be placed 573the above example, the content of ``example-depot/main/source/`` will be placed
555in ``${WORKDIR}/p4``. For situations where preserving parts of the remote depot 574in ``${WORKDIR}/p4``. For situations where preserving parts of the remote depot
556paths locally is desirable, the fetcher supports two parameters: 575paths locally is desirable, the fetcher supports two parameters:
557 576
558- **"module":** 577- *"module":*
559 The top-level depot location or directory to fetch. The value of this 578 The top-level depot location or directory to fetch. The value of this
560 parameter can also point to a single file within the depot, in which case 579 parameter can also point to a single file within the depot, in which case
561 the local file path will include the module path. 580 the local file path will include the module path.
562- **"remotepath":** 581- *"remotepath":*
563 When used with the value "``keep``", the fetcher will mirror the full depot 582 When used with the value "``keep``", the fetcher will mirror the full depot
564 paths locally for the specified location, even in combination with the 583 paths locally for the specified location, even in combination with the
565 ``module`` parameter. 584 ``module`` parameter.
@@ -589,7 +608,7 @@ Repo Fetcher (``repo://``)
589This fetcher submodule fetches code from ``google-repo`` source control 608This fetcher submodule fetches code from ``google-repo`` source control
590system. The fetcher works by initiating and syncing sources of the 609system. The fetcher works by initiating and syncing sources of the
591repository into :term:`REPODIR`, which is usually 610repository into :term:`REPODIR`, which is usually
592:term:`DL_DIR`\ ``/repo``. 611``${DL_DIR}/repo``.
593 612
594This fetcher supports the following parameters: 613This fetcher supports the following parameters:
595 614
@@ -600,10 +619,10 @@ This fetcher supports the following parameters:
600 619
601- *"manifest":* Name of the manifest file (default: ``default.xml``). 620- *"manifest":* Name of the manifest file (default: ``default.xml``).
602 621
603Here are some example URLs: SRC_URI = 622Here are some example URLs: ::
604"repo://REPOROOT;protocol=git;branch=some_branch;manifest=my_manifest.xml" 623
605SRC_URI = 624 SRC_URI = "repo://REPOROOT;protocol=git;branch=some_branch;manifest=my_manifest.xml"
606"repo://REPOROOT;protocol=file;branch=some_branch;manifest=my_manifest.xml" 625 SRC_URI = "repo://REPOROOT;protocol=file;branch=some_branch;manifest=my_manifest.xml"
607 626
608Other Fetchers 627Other Fetchers
609-------------- 628--------------
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 d64f6e00ca..e3fd321588 100644
--- a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-hello.rst
+++ b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-hello.rst
@@ -18,21 +18,28 @@ it.
18Obtaining BitBake 18Obtaining BitBake
19================= 19=================
20 20
21See the "`Obtaining BitBake <#obtaining-bitbake>`__" section for 21See the :ref:`bitbake-user-manual/bitbake-user-manual-hello:obtaining bitbake` section for
22information on how to obtain BitBake. Once you have the source code on 22information on how to obtain BitBake. Once you have the source code on
23your machine, the BitBake directory appears as follows: $ ls -al total 23your machine, the BitBake directory appears as follows: ::
24100 drwxrwxr-x. 9 wmat wmat 4096 Jan 31 13:44 . drwxrwxr-x. 3 wmat wmat 24
254096 Feb 4 10:45 .. -rw-rw-r--. 1 wmat wmat 365 Nov 26 04:55 AUTHORS 25 $ ls -al
26drwxrwxr-x. 2 wmat wmat 4096 Nov 26 04:55 bin drwxrwxr-x. 4 wmat wmat 26 total 100
274096 Jan 31 13:44 build -rw-rw-r--. 1 wmat wmat 16501 Nov 26 04:55 27 drwxrwxr-x. 9 wmat wmat 4096 Jan 31 13:44 .
28ChangeLog drwxrwxr-x. 2 wmat wmat 4096 Nov 26 04:55 classes drwxrwxr-x. 28 drwxrwxr-x. 3 wmat wmat 4096 Feb 4 10:45 ..
292 wmat wmat 4096 Nov 26 04:55 conf drwxrwxr-x. 3 wmat wmat 4096 Nov 26 29 -rw-rw-r--. 1 wmat wmat 365 Nov 26 04:55 AUTHORS
3004:55 contrib -rw-rw-r--. 1 wmat wmat 17987 Nov 26 04:55 COPYING 30 drwxrwxr-x. 2 wmat wmat 4096 Nov 26 04:55 bin
31drwxrwxr-x. 3 wmat wmat 4096 Nov 26 04:55 doc -rw-rw-r--. 1 wmat wmat 69 31 drwxrwxr-x. 4 wmat wmat 4096 Jan 31 13:44 build
32Nov 26 04:55 .gitignore -rw-rw-r--. 1 wmat wmat 849 Nov 26 04:55 HEADER 32 -rw-rw-r--. 1 wmat wmat 16501 Nov 26 04:55 ChangeLog
33drwxrwxr-x. 5 wmat wmat 4096 Jan 31 13:44 lib -rw-rw-r--. 1 wmat wmat 33 drwxrwxr-x. 2 wmat wmat 4096 Nov 26 04:55 classes
34195 Nov 26 04:55 MANIFEST.in -rw-rw-r--. 1 wmat wmat 2887 Nov 26 04:55 34 drwxrwxr-x. 2 wmat wmat 4096 Nov 26 04:55 conf
35TODO 35 drwxrwxr-x. 3 wmat wmat 4096 Nov 26 04:55 contrib
36 -rw-rw-r--. 1 wmat wmat 17987 Nov 26 04:55 COPYING
37 drwxrwxr-x. 3 wmat wmat 4096 Nov 26 04:55 doc
38 -rw-rw-r--. 1 wmat wmat 69 Nov 26 04:55 .gitignore
39 -rw-rw-r--. 1 wmat wmat 849 Nov 26 04:55 HEADER
40 drwxrwxr-x. 5 wmat wmat 4096 Jan 31 13:44 lib
41 -rw-rw-r--. 1 wmat wmat 195 Nov 26 04:55 MANIFEST.in
42 -rw-rw-r--. 1 wmat wmat 2887 Nov 26 04:55 TODO
36 43
37At this point, you should have BitBake cloned to a directory that 44At this point, you should have BitBake cloned to a directory that
38matches the previous listing except for dates and user names. 45matches the previous listing except for dates and user names.
@@ -42,18 +49,29 @@ Setting Up the BitBake Environment
42 49
43First, you need to be sure that you can run BitBake. Set your working 50First, you need to be sure that you can run BitBake. Set your working
44directory to where your local BitBake files are and run the following 51directory to where your local BitBake files are and run the following
45command: $ ./bin/bitbake --version BitBake Build Tool Core version 52command: ::
461.23.0, bitbake version 1.23.0 The console output tells you what version 53
54 $ ./bin/bitbake --version
55 BitBake Build Tool Core version 1.23.0, bitbake version 1.23.0
56
57The console output tells you what version
47you are running. 58you are running.
48 59
49The recommended method to run BitBake is from a directory of your 60The recommended method to run BitBake is from a directory of your
50choice. To be able to run BitBake from any directory, you need to add 61choice. To be able to run BitBake from any directory, you need to add
51the executable binary to your binary to your shell's environment 62the executable binary to your binary to your shell's environment
52``PATH`` variable. First, look at your current ``PATH`` variable by 63``PATH`` variable. First, look at your current ``PATH`` variable by
53entering the following: $ echo $PATH Next, add the directory location 64entering the following: ::
65
66 $ echo $PATH
67
68Next, add the directory location
54for the BitBake binary to the ``PATH``. Here is an example that adds the 69for the BitBake binary to the ``PATH``. Here is an example that adds the
55``/home/scott-lenovo/bitbake/bin`` directory to the front of the 70``/home/scott-lenovo/bitbake/bin`` directory to the front of the
56``PATH`` variable: $ export PATH=/home/scott-lenovo/bitbake/bin:$PATH 71``PATH`` variable: ::
72
73 $ export PATH=/home/scott-lenovo/bitbake/bin:$PATH
74
57You should now be able to enter the ``bitbake`` command from the command 75You should now be able to enter the ``bitbake`` command from the command
58line while working from any directory. 76line while working from any directory.
59 77
@@ -74,8 +92,7 @@ example.
74While every attempt is made to explain what is happening during the 92While every attempt is made to explain what is happening during the
75example, the descriptions cannot cover everything. You can find further 93example, the descriptions cannot cover everything. You can find further
76information throughout this manual. Also, you can actively participate 94information throughout this manual. Also, you can actively participate
77in the 95in the :oe_lists:`/g/bitbake-devel`
78http://lists.openembedded.org/mailman/listinfo/bitbake-devel
79discussion mailing list about the BitBake build tool. 96discussion mailing list about the BitBake build tool.
80 97
81.. note:: 98.. note::
@@ -87,36 +104,46 @@ discussion mailing list about the BitBake build tool.
87As stated earlier, the goal of this example is to eventually compile 104As stated earlier, the goal of this example is to eventually compile
88"Hello World". However, it is unknown what BitBake needs and what you 105"Hello World". However, it is unknown what BitBake needs and what you
89have to provide in order to achieve that goal. Recall that BitBake 106have to provide in order to achieve that goal. Recall that BitBake
90utilizes three types of metadata files: `Configuration 107utilizes three types of metadata files:
91Files <#configuration-files>`__, `Classes <#classes>`__, and 108:ref:`bitbake-user-manual/bitbake-user-manual-intro:configuration files`,
92`Recipes <#recipes>`__. But where do they go? How does BitBake find 109:ref:`bitbake-user-manual/bitbake-user-manual-intro:classes`, and
110:ref:`bitbake-user-manual/bitbake-user-manual-intro:recipes`.
111But where do they go? How does BitBake find
93them? BitBake's error messaging helps you answer these types of 112them? BitBake's error messaging helps you answer these types of
94questions and helps you better understand exactly what is going on. 113questions and helps you better understand exactly what is going on.
95 114
96Following is the complete "Hello World" example. 115Following is the complete "Hello World" example.
97 116
981. *Create a Project Directory:* First, set up a directory for the 117#. **Create a Project Directory:** First, set up a directory for the
99 "Hello World" project. Here is how you can do so in your home 118 "Hello World" project. Here is how you can do so in your home
100 directory: $ mkdir ~/hello $ cd ~/hello This is the directory that 119 directory: ::
120
121 $ mkdir ~/hello
122 $ cd ~/hello
123
124 This is the directory that
101 BitBake will use to do all of its work. You can use this directory 125 BitBake will use to do all of its work. You can use this directory
102 to keep all the metafiles needed by BitBake. Having a project 126 to keep all the metafiles needed by BitBake. Having a project
103 directory is a good way to isolate your project. 127 directory is a good way to isolate your project.
104 128
1052. *Run BitBake:* At this point, you have nothing but a project 129#. **Run BitBake:** At this point, you have nothing but a project
106 directory. Run the ``bitbake`` command and see what it does: $ 130 directory. Run the ``bitbake`` command and see what it does: ::
107 bitbake The BBPATH variable is not set and bitbake did not find a 131
108 conf/bblayers.conf file in the expected location. Maybe you 132 $ bitbake
109 accidentally invoked bitbake from the wrong directory? DEBUG: 133 The BBPATH variable is not set and bitbake did not
110 Removed the following variables from the environment: 134 find a conf/bblayers.conf file in the expected location.
111 GNOME_DESKTOP_SESSION_ID, XDG_CURRENT_DESKTOP, 135 Maybe you accidentally invoked bitbake from the wrong directory?
112 GNOME_KEYRING_CONTROL, DISPLAY, SSH_AGENT_PID, LANG, no_proxy, 136 DEBUG: Removed the following variables from the environment:
113 XDG_SESSION_PATH, XAUTHORITY, SESSION_MANAGER, SHLVL, 137 GNOME_DESKTOP_SESSION_ID, XDG_CURRENT_DESKTOP,
114 MANDATORY_PATH, COMPIZ_CONFIG_PROFILE, WINDOWID, EDITOR, 138 GNOME_KEYRING_CONTROL, DISPLAY, SSH_AGENT_PID, LANG, no_proxy,
115 GPG_AGENT_INFO, SSH_AUTH_SOCK, GDMSESSION, GNOME_KEYRING_PID, 139 XDG_SESSION_PATH, XAUTHORITY, SESSION_MANAGER, SHLVL,
116 XDG_SEAT_PATH, XDG_CONFIG_DIRS, LESSOPEN, DBUS_SESSION_BUS_ADDRESS, 140 MANDATORY_PATH, COMPIZ_CONFIG_PROFILE, WINDOWID, EDITOR,
117 \_, XDG_SESSION_COOKIE, DESKTOP_SESSION, LESSCLOSE, DEFAULTS_PATH, 141 GPG_AGENT_INFO, SSH_AUTH_SOCK, GDMSESSION, GNOME_KEYRING_PID,
118 UBUNTU_MENUPROXY, OLDPWD, XDG_DATA_DIRS, COLORTERM, LS_COLORS The 142 XDG_SEAT_PATH, XDG_CONFIG_DIRS, LESSOPEN, DBUS_SESSION_BUS_ADDRESS,
119 majority of this output is specific to environment variables that 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
120 are not directly relevant to BitBake. However, the very first 147 are not directly relevant to BitBake. However, the very first
121 message regarding the ``BBPATH`` variable and the 148 message regarding the ``BBPATH`` variable and the
122 ``conf/bblayers.conf`` file is relevant. 149 ``conf/bblayers.conf`` file is relevant.
@@ -128,14 +155,18 @@ Following is the complete "Hello World" example.
128 (``.conf``) or recipe files (``.bb``) at all. BitBake also cannot 155 (``.conf``) or recipe files (``.bb``) at all. BitBake also cannot
129 find the ``bitbake.conf`` file. 156 find the ``bitbake.conf`` file.
130 157
1313. *Setting ``BBPATH``:* For this example, you can set ``BBPATH`` in 158#. **Setting BBPATH:** For this example, you can set ``BBPATH`` in
132 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
133 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
134 ``BBPATH`` variable up in a configuration file for each project. 161 ``BBPATH`` variable up in a configuration file for each project.
135 162
136 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
137 ``BBPATH`` variable: $ BBPATH="projectdirectory" $ export BBPATH Use 164 ``BBPATH`` variable: ::
138 your actual project directory in the command. BitBake uses that 165
166 $ BBPATH="projectdirectory"
167 $ export BBPATH
168
169 Use your actual project directory in the command. BitBake uses that
139 directory to find the metadata it needs for your project. 170 directory to find the metadata it needs for your project.
140 171
141 .. note:: 172 .. note::
@@ -144,28 +175,32 @@ Following is the complete "Hello World" example.
144 ("~") character as BitBake does not expand that character as the 175 ("~") character as BitBake does not expand that character as the
145 shell would. 176 shell would.
146 177
1474. *Run BitBake:* Now that you have ``BBPATH`` defined, run the 178#. **Run BitBake:** Now that you have ``BBPATH`` defined, run the
148 ``bitbake`` command again: $ bitbake ERROR: Traceback (most recent 179 ``bitbake`` command again: ::
149 call last): File "/home/scott-lenovo/bitbake/lib/bb/cookerdata.py", 180
150 line 163, in wrapped return func(fn, \*args) File 181 $ bitbake
151 "/home/scott-lenovo/bitbake/lib/bb/cookerdata.py", line 173, in 182 ERROR: Traceback (most recent call last):
152 parse_config_file return bb.parse.handle(fn, data, include) File 183 File "/home/scott-lenovo/bitbake/lib/bb/cookerdata.py", line 163, in wrapped
153 "/home/scott-lenovo/bitbake/lib/bb/parse/__init__.py", line 99, in 184 return func(fn, *args)
154 handle return h['handle'](fn, data, include) File 185 File "/home/scott-lenovo/bitbake/lib/bb/cookerdata.py", line 173, in parse_config_file
155 "/home/scott-lenovo/bitbake/lib/bb/parse/parse_py/ConfHandler.py", 186 return bb.parse.handle(fn, data, include)
156 line 120, in handle abs_fn = resolve_file(fn, data) File 187 File "/home/scott-lenovo/bitbake/lib/bb/parse/__init__.py", line 99, in handle
157 "/home/scott-lenovo/bitbake/lib/bb/parse/__init__.py", line 117, in 188 return h['handle'](fn, data, include)
158 resolve_file raise IOError("file %s not found in %s" % (fn, bbpath)) 189 File "/home/scott-lenovo/bitbake/lib/bb/parse/parse_py/ConfHandler.py", line 120, in handle
159 IOError: file conf/bitbake.conf not found in 190 abs_fn = resolve_file(fn, data)
160 /home/scott-lenovo/hello ERROR: Unable to parse conf/bitbake.conf: 191 File "/home/scott-lenovo/bitbake/lib/bb/parse/__init__.py", line 117, in resolve_file
161 file conf/bitbake.conf not found in /home/scott-lenovo/hello This 192 raise IOError("file %s not found in %s" % (fn, bbpath))
162 sample output shows that BitBake could not find the 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
197 This sample output shows that BitBake could not find the
163 ``conf/bitbake.conf`` file in the project directory. This file is 198 ``conf/bitbake.conf`` file in the project directory. This file is
164 the first thing BitBake must find in order to build a target. And, 199 the first thing BitBake must find in order to build a target. And,
165 since the project directory for this example is empty, you need to 200 since the project directory for this example is empty, you need to
166 provide a ``conf/bitbake.conf`` file. 201 provide a ``conf/bitbake.conf`` file.
167 202
1685. *Creating ``conf/bitbake.conf``:* The ``conf/bitbake.conf`` includes 203#. **Creating conf/bitbake.conf:** The ``conf/bitbake.conf`` includes
169 a number of configuration variables BitBake uses for metadata and 204 a number of configuration variables BitBake uses for metadata and
170 recipe files. For this example, you need to create the file in your 205 recipe files. For this example, you need to create the file in your
171 project directory and define some key BitBake variables. For more 206 project directory and define some key BitBake variables. For more
@@ -173,106 +208,100 @@ Following is the complete "Hello World" example.
173 http://git.openembedded.org/bitbake/tree/conf/bitbake.conf. 208 http://git.openembedded.org/bitbake/tree/conf/bitbake.conf.
174 209
175 Use the following commands to create the ``conf`` directory in the 210 Use the following commands to create the ``conf`` directory in the
176 project directory: $ mkdir conf From within the ``conf`` directory, 211 project directory: ::
212
213 $ mkdir conf
214
215 From within the ``conf`` directory,
177 use some editor to create the ``bitbake.conf`` so that it contains 216 use some editor to create the ``bitbake.conf`` so that it contains
178 the following: :term:`PN` = 217 the following: ::
179 "${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE', False),d)[0] 218
180 or 'defaultpkgname'}" TMPDIR = "${:term:`TOPDIR`}/tmp" 219 PN = "${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE', False),d)[0] or 'defaultpkgname'}"
181 :term:`CACHE` = "${TMPDIR}/cache" 220
182 :term:`STAMP` = "${TMPDIR}/${PN}/stamps" 221 TMPDIR = "${TOPDIR}/tmp"
183 :term:`T` = "${TMPDIR}/${PN}/work" :term:`B` = 222 CACHE = "${TMPDIR}/cache"
184 "${TMPDIR}/${PN}" 223 STAMP = "${TMPDIR}/${PN}/stamps"
224 T = "${TMPDIR}/${PN}/work"
225 B = "${TMPDIR}/${PN}"
185 226
186 .. note:: 227 .. note::
187 228
188 Without a value for 229 Without a value for PN , the variables STAMP , T , and B , prevent more
189 PN 230 than one recipe from working. You can fix this by either setting PN to
190 , the variables 231 have a value similar to what OpenEmbedded and BitBake use in the default
191 STAMP 232 bitbake.conf file (see previous example). Or, by manually updating each
192 , 233 recipe to set PN . You will also need to include PN as part of the STAMP
193 T 234 , T , and B variable definitions in the local.conf file.
194 , and
195 B
196 , prevent more than one recipe from working. You can fix this by
197 either setting
198 PN
199 to have a value similar to what OpenEmbedded and BitBake use in
200 the default
201 bitbake.conf
202 file (see previous example). Or, by manually updating each recipe
203 to set
204 PN
205 . You will also need to include
206 PN
207 as part of the
208 STAMP
209 ,
210 T
211 , and
212 B
213 variable definitions in the
214 local.conf
215 file.
216 235
217 The ``TMPDIR`` variable establishes a directory that BitBake uses 236 The ``TMPDIR`` variable establishes a directory that BitBake uses
218 for build output and intermediate files other than the cached 237 for build output and intermediate files other than the cached
219 information used by the `Setscene <#setscene>`__ process. Here, the 238 information used by the
220 ``TMPDIR`` directory is set to ``hello/tmp``. 239 :ref:`bitbake-user-manual/bitbake-user-manual-execution:setscene`
240 process. Here, the ``TMPDIR`` directory is set to ``hello/tmp``.
221 241
222 .. note:: 242 .. tip::
223 243
224 You can always safely delete the 244 You can always safely delete the tmp directory in order to rebuild a
225 tmp 245 BitBake target. The build process creates the directory for you when you
226 directory in order to rebuild a BitBake target. The build process 246 run BitBake.
227 creates the directory for you when you run BitBake.
228 247
229 For information about each of the other variables defined in this 248 For information about each of the other variables defined in this
230 example, click on the links to take you to the definitions in the 249 example, check :term:`PN`, :term:`TOPDIR`, :term:`CACHE`, :term:`STAMP`,
250 :term:`T` or :term:`B` to take you to the definitions in the
231 glossary. 251 glossary.
232 252
2336. *Run BitBake:* After making sure that the ``conf/bitbake.conf`` file 253#. **Run BitBake:** After making sure that the ``conf/bitbake.conf`` file
234 exists, you can run the ``bitbake`` command again: $ bitbake ERROR: 254 exists, you can run the ``bitbake`` command again: ::
235 Traceback (most recent call last): File 255
236 "/home/scott-lenovo/bitbake/lib/bb/cookerdata.py", line 163, in 256 $ bitbake
237 wrapped return func(fn, \*args) File 257 ERROR: Traceback (most recent call last):
238 "/home/scott-lenovo/bitbake/lib/bb/cookerdata.py", line 177, in 258 File "/home/scott-lenovo/bitbake/lib/bb/cookerdata.py", line 163, in wrapped
239 \_inherit bb.parse.BBHandler.inherit(bbclass, "configuration 259 return func(fn, *args)
240 INHERITs", 0, data) File 260 File "/home/scott-lenovo/bitbake/lib/bb/cookerdata.py", line 177, in _inherit
241 "/home/scott-lenovo/bitbake/lib/bb/parse/parse_py/BBHandler.py", 261 bb.parse.BBHandler.inherit(bbclass, "configuration INHERITs", 0, data)
242 line 92, in inherit include(fn, file, lineno, d, "inherit") File 262 File "/home/scott-lenovo/bitbake/lib/bb/parse/parse_py/BBHandler.py", line 92, in inherit
243 "/home/scott-lenovo/bitbake/lib/bb/parse/parse_py/ConfHandler.py", 263 include(fn, file, lineno, d, "inherit")
244 line 100, in include raise ParseError("Could not %(error_out)s file 264 File "/home/scott-lenovo/bitbake/lib/bb/parse/parse_py/ConfHandler.py", line 100, in include
245 %(fn)s" % vars(), oldfn, lineno) ParseError: ParseError in 265 raise ParseError("Could not %(error_out)s file %(fn)s" % vars(), oldfn, lineno)
246 configuration INHERITs: Could not inherit file classes/base.bbclass 266 ParseError: ParseError in configuration INHERITs: Could not inherit file classes/base.bbclass
247 ERROR: Unable to parse base: ParseError in configuration INHERITs: 267
248 Could not inherit file classes/base.bbclass In the sample output, 268 ERROR: Unable to parse base: ParseError in configuration INHERITs: Could not inherit file classes/base.bbclass
269
270 In the sample output,
249 BitBake could not find the ``classes/base.bbclass`` file. You need 271 BitBake could not find the ``classes/base.bbclass`` file. You need
250 to create that file next. 272 to create that file next.
251 273
2527. *Creating ``classes/base.bbclass``:* BitBake uses class files to 274#. **Creating classes/base.bbclass:** BitBake uses class files to
253 provide common code and functionality. The minimally required class 275 provide common code and functionality. The minimally required class
254 for BitBake is the ``classes/base.bbclass`` file. The ``base`` class 276 for BitBake is the ``classes/base.bbclass`` file. The ``base`` class
255 is implicitly inherited by every recipe. BitBake looks for the class 277 is implicitly inherited by every recipe. BitBake looks for the class
256 in the ``classes`` directory of the project (i.e ``hello/classes`` 278 in the ``classes`` directory of the project (i.e ``hello/classes``
257 in this example). 279 in this example).
258 280
259 Create the ``classes`` directory as follows: $ cd $HOME/hello $ 281 Create the ``classes`` directory as follows: ::
260 mkdir classes Move to the ``classes`` directory and then create the 282
283 $ cd $HOME/hello
284 $ mkdir classes
285
286 Move to the ``classes`` directory and then create the
261 ``base.bbclass`` file by inserting this single line: addtask build 287 ``base.bbclass`` file by inserting this single line: addtask build
262 The minimal task that BitBake runs is the ``do_build`` task. This is 288 The minimal task that BitBake runs is the ``do_build`` task. This is
263 all the example needs in order to build the project. Of course, the 289 all the example needs in order to build the project. Of course, the
264 ``base.bbclass`` can have much more depending on which build 290 ``base.bbclass`` can have much more depending on which build
265 environments BitBake is supporting. 291 environments BitBake is supporting.
266 292
2678. *Run BitBake:* After making sure that the ``classes/base.bbclass`` 293#. **Run BitBake:** After making sure that the ``classes/base.bbclass``
268 file exists, you can run the ``bitbake`` command again: $ bitbake 294 file exists, you can run the ``bitbake`` command again: ::
269 Nothing to do. Use 'bitbake world' to build everything, or run 295
270 'bitbake --help' for usage information. BitBake is finally reporting 296 $ bitbake
297 Nothing to do. Use 'bitbake world' to build everything, or run 'bitbake --help' for usage information.
298
299 BitBake is finally reporting
271 no errors. However, you can see that it really does not have 300 no errors. However, you can see that it really does not have
272 anything to do. You need to create a recipe that gives BitBake 301 anything to do. You need to create a recipe that gives BitBake
273 something to do. 302 something to do.
274 303
2759. *Creating a Layer:* While it is not really necessary for such a 304#. **Creating a Layer:** While it is not really necessary for such a
276 small example, it is good practice to create a layer in which to 305 small example, it is good practice to create a layer in which to
277 keep your code separate from the general metadata used by BitBake. 306 keep your code separate from the general metadata used by BitBake.
278 Thus, this example creates and uses a layer called "mylayer". 307 Thus, this example creates and uses a layer called "mylayer".
@@ -285,78 +314,102 @@ Following is the complete "Hello World" example.
285 Minimally, you need a recipe file and a layer configuration file in 314 Minimally, you need a recipe file and a layer configuration file in
286 your layer. The configuration file needs to be in the ``conf`` 315 your layer. The configuration file needs to be in the ``conf``
287 directory inside the layer. Use these commands to set up the layer 316 directory inside the layer. Use these commands to set up the layer
288 and the ``conf`` directory: $ cd $HOME $ mkdir mylayer $ cd mylayer 317 and the ``conf`` directory: ::
289 $ mkdir conf Move to the ``conf`` directory and create a 318
290 ``layer.conf`` file that has the following: BBPATH .= 319 $ cd $HOME
291 ":${:term:`LAYERDIR`}" :term:`BBFILES` 320 $ mkdir mylayer
292 += "${LAYERDIR}/\*.bb" 321 $ cd mylayer
293 :term:`BBFILE_COLLECTIONS` += "mylayer" 322 $ mkdir conf
294 `BBFILE_PATTERN_mylayer <#var-bb-BBFILE_PATTERN>`__ := 323
295 "^${LAYERDIR_RE}/" For information on these variables, click the 324 Move to the ``conf`` directory and create a ``layer.conf`` file that has the
296 links to go to the definitions in the glossary. 325 following: ::
326
327 BBPATH .= ":${LAYERDIR}"
328 BBFILES += "${LAYERDIR}/\*.bb"
329 BBFILE_COLLECTIONS += "mylayer"
330 `BBFILE_PATTERN_mylayer := "^${LAYERDIR_RE}/"
331
332 For information on these variables, click on :term:`BBFILES`,
333 :term:`LAYERDIR`, :term:`BBFILE_COLLECTIONS` or :term:`BBFILE_PATTERN_mylayer <BBFILE_PATTERN>`
334 to go to the definitions in the glossary.
297 335
298 You need to create the recipe file next. Inside your layer at the 336 You need to create the recipe file next. Inside your layer at the
299 top-level, use an editor and create a recipe file named 337 top-level, use an editor and create a recipe file named
300 ``printhello.bb`` that has the following: 338 ``printhello.bb`` that has the following: ::
301 :term:`DESCRIPTION` = "Prints Hello World" 339
302 :term:`PN` = 'printhello' :term:`PV` = '1' python 340 DESCRIPTION = "Prints Hello World"
303 do_build() { bb.plain("********************"); bb.plain("\* \*"); 341 PN = 'printhello'
304 bb.plain("\* Hello, World! \*"); bb.plain("\* \*"); 342 PV = '1'
305 bb.plain("********************"); } The recipe file simply provides 343
344 python do_build() {
345 bb.plain("********************");
346 bb.plain("* *");
347 bb.plain("* Hello, World! *");
348 bb.plain("* *");
349 bb.plain("********************");
350 }
351
352 The recipe file simply provides
306 a description of the recipe, the name, version, and the ``do_build`` 353 a description of the recipe, the name, version, and the ``do_build``
307 task, which prints out "Hello World" to the console. For more 354 task, which prints out "Hello World" to the console. For more
308 information on these variables, follow the links to the glossary. 355 information on :term:`DESCRIPTION`, :term:`PN` or :term:`PV`
356 follow the links to the glossary.
357
358#. **Run BitBake With a Target:** Now that a BitBake target exists, run
359 the command and provide that target: ::
309 360
31010. *Run BitBake With a Target:* Now that a BitBake target exists, run 361 $ cd $HOME/hello
311 the command and provide that target: $ cd $HOME/hello $ bitbake 362 $ bitbake printhello
312 printhello ERROR: no recipe files to build, check your BBPATH and 363 ERROR: no recipe files to build, check your BBPATH and BBFILES?
313 BBFILES? Summary: There was 1 ERROR message shown, returning a 364
314 non-zero exit code. We have created the layer with the recipe and 365 Summary: There was 1 ERROR message shown, returning a non-zero exit code.
366
367 We have created the layer with the recipe and
315 the layer configuration file but it still seems that BitBake cannot 368 the layer configuration file but it still seems that BitBake cannot
316 find the recipe. BitBake needs a ``conf/bblayers.conf`` that lists 369 find the recipe. BitBake needs a ``conf/bblayers.conf`` that lists
317 the layers for the project. Without this file, BitBake cannot find 370 the layers for the project. Without this file, BitBake cannot find
318 the recipe. 371 the recipe.
319 372
32011. *Creating ``conf/bblayers.conf``:* BitBake uses the 373#. **Creating conf/bblayers.conf:** BitBake uses the
321 ``conf/bblayers.conf`` file to locate layers needed for the project. 374 ``conf/bblayers.conf`` file to locate layers needed for the project.
322 This file must reside in the ``conf`` directory of the project (i.e. 375 This file must reside in the ``conf`` directory of the project (i.e.
323 ``hello/conf`` for this example). 376 ``hello/conf`` for this example).
324 377
325 Set your working directory to the ``hello/conf`` directory and then 378 Set your working directory to the ``hello/conf`` directory and then
326 create the ``bblayers.conf`` file so that it contains the following: 379 create the ``bblayers.conf`` file so that it contains the following: ::
327 BBLAYERS ?= " \\ /home/<you>/mylayer \\ " You need to provide your 380
328 own information for ``you`` in the file. 381 BBLAYERS ?= " \
382 /home/<you>/mylayer \
383 "
384
385 You need to provide your own information for ``you`` in the file.
329 386
33012. *Run BitBake With a Target:* Now that you have supplied the 387#. **Run BitBake With a Target:** Now that you have supplied the
331 ``bblayers.conf`` file, run the ``bitbake`` command and provide the 388 ``bblayers.conf`` file, run the ``bitbake`` command and provide the
332 target: $ bitbake printhello Parsing recipes: 100% 389 target: ::
333 \|##################################################################################\| 390
334 Time: 00:00:00 Parsing of 1 .bb files complete (0 cached, 1 parsed). 391 $ bitbake printhello
335 1 targets, 0 skipped, 0 masked, 0 errors. NOTE: Resolving any 392 Parsing recipes: 100% |##################################################################################|
336 missing task queue dependencies NOTE: Preparing RunQueue NOTE: 393 Time: 00:00:00
337 Executing RunQueue Tasks \*******************\* \* \* \* Hello, 394 Parsing of 1 .bb files complete (0 cached, 1 parsed). 1 targets, 0 skipped, 0 masked, 0 errors.
338 World! \* \* \* \*******************\* NOTE: Tasks Summary: 395 NOTE: Resolving any missing task queue dependencies
339 Attempted 1 tasks of which 0 didn't need to be rerun and all 396 NOTE: Preparing RunQueue
340 succeeded. BitBake finds the ``printhello`` recipe and successfully 397 NOTE: Executing RunQueue Tasks
341 runs the task. 398 ********************
399 * *
400 * Hello, World! *
401 * *
402 ********************
403 NOTE: Tasks Summary: Attempted 1 tasks of which 0 didn't need to be rerun and all succeeded.
342 404
343 .. note:: 405 .. note::
344 406
345 After the first execution, re-running 407 After the first execution, re-running bitbake printhello again will not
346 bitbake printhello 408 result in a BitBake run that prints the same console output. The reason
347 again will not result in a BitBake run that prints the same 409 for this is that the first time the printhello.bb recipe's do_build task
348 console output. The reason for this is that the first time the 410 executes successfully, BitBake writes a stamp file for the task. Thus,
349 printhello.bb 411 the next time you attempt to run the task using that same bitbake
350 recipe's 412 command, BitBake notices the stamp and therefore determines that the task
351 do_build 413 does not need to be re-run. If you delete the tmp directory or run
352 task executes successfully, BitBake writes a stamp file for the 414 bitbake -c clean printhello and then re-run the build, the "Hello,
353 task. Thus, the next time you attempt to run the task using that 415 World!" message will be printed again.
354 same
355 bitbake
356 command, BitBake notices the stamp and therefore determines that
357 the task does not need to be re-run. If you delete the
358 tmp
359 directory or run
360 bitbake -c clean printhello
361 and then re-run the build, the "Hello, World!" message will be
362 printed again.
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 34abda2db3..77dc9668ab 100644
--- a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-intro.rst
+++ b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-intro.rst
@@ -248,19 +248,23 @@ underlying, similarly-named recipe files.
248 248
249When you name an append file, you can use the "``%``" wildcard character 249When you name an append file, you can use the "``%``" wildcard character
250to allow for matching recipe names. For example, suppose you have an 250to allow for matching recipe names. For example, suppose you have an
251append file named as follows: busybox_1.21.%.bbappend That append file 251append file named as follows: ::
252
253 busybox_1.21.%.bbappend
254
255That append file
252would match any ``busybox_1.21.``\ x\ ``.bb`` version of the recipe. So, 256would match any ``busybox_1.21.``\ x\ ``.bb`` version of the recipe. So,
253the append file would match the following recipe names: 257the append file would match the following recipe names: ::
254busybox_1.21.1.bb busybox_1.21.2.bb busybox_1.21.3.bb 258
259 busybox_1.21.1.bb
260 busybox_1.21.2.bb
261 busybox_1.21.3.bb
255 262
256.. note:: 263.. note::
257 264
258 The use of the " 265 The use of the " % " character is limited in that it only works directly in
259 % 266 front of the .bbappend portion of the append file's name. You cannot use the
260 " character is limited in that it only works directly in front of the 267 wildcard character in any other location of the name.
261 .bbappend
262 portion of the append file's name. You cannot use the wildcard
263 character in any other location of the name.
264 268
265If the ``busybox`` recipe was updated to ``busybox_1.3.0.bb``, the 269If the ``busybox`` recipe was updated to ``busybox_1.3.0.bb``, the
266append name would not match. However, if you named the append file 270append name would not match. However, if you named the append file
@@ -274,7 +278,7 @@ Obtaining BitBake
274 278
275You can obtain BitBake several different ways: 279You can obtain BitBake several different ways:
276 280
277- *Cloning BitBake:* Using Git to clone the BitBake source code 281- **Cloning BitBake:** Using Git to clone the BitBake source code
278 repository is the recommended method for obtaining BitBake. Cloning 282 repository is the recommended method for obtaining BitBake. Cloning
279 the repository makes it easy to get bug fixes and have access to 283 the repository makes it easy to get bug fixes and have access to
280 stable branches and the master branch. Once you have cloned BitBake, 284 stable branches and the master branch. Once you have cloned BitBake,
@@ -286,36 +290,42 @@ You can obtain BitBake several different ways:
286 are using. The metadata is generally backwards compatible but not 290 are using. The metadata is generally backwards compatible but not
287 forward compatible. 291 forward compatible.
288 292
289 Here is an example that clones the BitBake repository: $ git clone 293 Here is an example that clones the BitBake repository: ::
290 git://git.openembedded.org/bitbake This command clones the BitBake 294
295 $ git clone git://git.openembedded.org/bitbake
296
297 This command clones the BitBake
291 Git repository into a directory called ``bitbake``. Alternatively, 298 Git repository into a directory called ``bitbake``. Alternatively,
292 you can designate a directory after the ``git clone`` command if you 299 you can designate a directory after the ``git clone`` command if you
293 want to call the new directory something other than ``bitbake``. Here 300 want to call the new directory something other than ``bitbake``. Here
294 is an example that names the directory ``bbdev``: $ git clone 301 is an example that names the directory ``bbdev``: ::
295 git://git.openembedded.org/bitbake bbdev 302
303 $ git clone git://git.openembedded.org/bitbake bbdev
296 304
297- *Installation using your Distribution Package Management System:* 305- **Installation using your Distribution Package Management System:**
298 This method is not recommended because the BitBake version that is 306 This method is not recommended because the BitBake version that is
299 provided by your distribution, in most cases, is several releases 307 provided by your distribution, in most cases, is several releases
300 behind a snapshot of the BitBake repository. 308 behind a snapshot of the BitBake repository.
301 309
302- *Taking a snapshot of BitBake:* Downloading a snapshot of BitBake 310- **Taking a snapshot of BitBake:** Downloading a snapshot of BitBake
303 from the source code repository gives you access to a known branch or 311 from the source code repository gives you access to a known branch or
304 release of BitBake. 312 release of BitBake.
305 313
306 .. note:: 314 .. note::
315
316 Cloning the Git repository, as described earlier, is the preferred
317 method for getting BitBake. Cloning the repository makes it easier
318 to update as patches are added to the stable branches.
319
320 The following example downloads a snapshot of BitBake version 1.17.0: ::
307 321
308 Cloning the Git repository, as described earlier, is the preferred 322 $ wget http://git.openembedded.org/bitbake/snapshot/bitbake-1.17.0.tar.gz
309 method for getting BitBake. Cloning the repository makes it easier 323 $ tar zxpvf bitbake-1.17.0.tar.gz
310 to update as patches are added to the stable branches.
311 324
312 The following example downloads a snapshot of BitBake version 1.17.0: 325 After extraction of the tarball using
313 $ wget
314 http://git.openembedded.org/bitbake/snapshot/bitbake-1.17.0.tar.gz $
315 tar zxpvf bitbake-1.17.0.tar.gz After extraction of the tarball using
316 the tar utility, you have a directory entitled ``bitbake-1.17.0``. 326 the tar utility, you have a directory entitled ``bitbake-1.17.0``.
317 327
318- *Using the BitBake that Comes With Your Build Checkout:* A final 328- **Using the BitBake that Comes With Your Build Checkout:** A final
319 possibility for getting a copy of BitBake is that it already comes 329 possibility for getting a copy of BitBake is that it already comes
320 with your checkout of a larger BitBake-based build system, such as 330 with your checkout of a larger BitBake-based build system, such as
321 Poky. Rather than manually checking out individual layers and gluing 331 Poky. Rather than manually checking out individual layers and gluing
@@ -337,75 +347,108 @@ execution examples.
337Usage and syntax 347Usage and syntax
338---------------- 348----------------
339 349
340Following is the usage and syntax for BitBake: $ bitbake -h Usage: 350Following is the usage and syntax for BitBake: ::
341bitbake [options] [recipename/target recipe:do_task ...] Executes the 351
342specified task (default is 'build') for a given set of target recipes 352 $ bitbake -h
343(.bb files). It is assumed there is a conf/bblayers.conf available in 353 Usage: bitbake [options] [recipename/target recipe:do_task ...]
344cwd or in BBPATH which will provide the layer, BBFILES and other 354
345configuration information. Options: --version show program's version 355 Executes the specified task (default is 'build') for a given set of target recipes (.bb files).
346number and exit -h, --help show this help message and exit -b BUILDFILE, 356 It is assumed there is a conf/bblayers.conf available in cwd or in BBPATH which
347--buildfile=BUILDFILE Execute tasks from a specific .bb recipe directly. 357 will provide the layer, BBFILES and other configuration information.
348WARNING: Does not handle any dependencies from other recipes. -k, 358
349--continue Continue as much as possible after an error. While the target 359 Options:
350that failed and anything depending on it cannot be built, as much as 360 --version show program's version number and exit
351possible will be built before stopping. -f, --force Force the specified 361 -h, --help show this help message and exit
352targets/task to run (invalidating any existing stamp file). -c CMD, 362 -b BUILDFILE, --buildfile=BUILDFILE
353--cmd=CMD Specify the task to execute. The exact options available 363 Execute tasks from a specific .bb recipe directly.
354depend on the metadata. Some examples might be 'compile' or 364 WARNING: Does not handle any dependencies from other
355'populate_sysroot' or 'listtasks' may give a list of the tasks 365 recipes.
356available. -C INVALIDATE_STAMP, --clear-stamp=INVALIDATE_STAMP 366 -k, --continue Continue as much as possible after an error. While the
357Invalidate the stamp for the specified task such as 'compile' and then 367 target that failed and anything depending on it cannot
358run the default task for the specified target(s). -r PREFILE, 368 be built, as much as possible will be built before
359--read=PREFILE Read the specified file before bitbake.conf. -R POSTFILE, 369 stopping.
360--postread=POSTFILE Read the specified file after bitbake.conf. -v, 370 -f, --force Force the specified targets/task to run (invalidating
361--verbose Enable tracing of shell tasks (with 'set -x'). Also print 371 any existing stamp file).
362bb.note(...) messages to stdout (in addition to writing them to 372 -c CMD, --cmd=CMD Specify the task to execute. The exact options
363${T}/log.do_<task>). -D, --debug Increase the debug level. You can 373 available depend on the metadata. Some examples might
364specify this more than once. -D sets the debug level to 1, where only 374 be 'compile' or 'populate_sysroot' or 'listtasks' may
365bb.debug(1, ...) messages are printed to stdout; -DD sets the debug 375 give a list of the tasks available.
366level to 2, where both bb.debug(1, ...) and bb.debug(2, ...) messages 376 -C INVALIDATE_STAMP, --clear-stamp=INVALIDATE_STAMP
367are printed; etc. Without -D, no debug messages are printed. Note that 377 Invalidate the stamp for the specified task such as
368-D only affects output to stdout. All debug messages are written to 378 'compile' and then run the default task for the
369${T}/log.do_taskname, regardless of the debug level. -q, --quiet Output 379 specified target(s).
370less log message data to the terminal. You can specify this more than 380 -r PREFILE, --read=PREFILE
371once. -n, --dry-run Don't execute, just go through the motions. -S 381 Read the specified file before bitbake.conf.
372SIGNATURE_HANDLER, --dump-signatures=SIGNATURE_HANDLER Dump out the 382 -R POSTFILE, --postread=POSTFILE
373signature construction information, with no task execution. The 383 Read the specified file after bitbake.conf.
374SIGNATURE_HANDLER parameter is passed to the handler. Two common values 384 -v, --verbose Enable tracing of shell tasks (with 'set -x'). Also
375are none and printdiff but the handler may define more/less. none means 385 print bb.note(...) messages to stdout (in addition to
376only dump the signature, printdiff means compare the dumped signature 386 writing them to ${T}/log.do_&lt;task&gt;).
377with the cached one. -p, --parse-only Quit after parsing the BB recipes. 387 -D, --debug Increase the debug level. You can specify this more
378-s, --show-versions Show current and preferred versions of all recipes. 388 than once. -D sets the debug level to 1, where only
379-e, --environment Show the global or per-recipe environment complete 389 bb.debug(1, ...) messages are printed to stdout; -DD
380with information about where variables were set/changed. -g, --graphviz 390 sets the debug level to 2, where both bb.debug(1, ...)
381Save dependency tree information for the specified targets in the dot 391 and bb.debug(2, ...) messages are printed; etc.
382syntax. -I EXTRA_ASSUME_PROVIDED, --ignore-deps=EXTRA_ASSUME_PROVIDED 392 Without -D, no debug messages are printed. Note that
383Assume these dependencies don't exist and are already provided 393 -D only affects output to stdout. All debug messages
384(equivalent to ASSUME_PROVIDED). Useful to make dependency graphs more 394 are written to ${T}/log.do_taskname, regardless of the
385appealing -l DEBUG_DOMAINS, --log-domains=DEBUG_DOMAINS Show debug 395 debug level.
386logging for the specified logging domains -P, --profile Profile the 396 -q, --quiet Output less log message data to the terminal. You can
387command and save reports. -u UI, --ui=UI The user interface to use 397 specify this more than once.
388(knotty, ncurses or taskexp - default knotty). --token=XMLRPCTOKEN 398 -n, --dry-run Don't execute, just go through the motions.
389Specify the connection token to be used when connecting to a remote 399 -S SIGNATURE_HANDLER, --dump-signatures=SIGNATURE_HANDLER
390server. --revisions-changed Set the exit code depending on whether 400 Dump out the signature construction information, with
391upstream floating revisions have changed or not. --server-only Run 401 no task execution. The SIGNATURE_HANDLER parameter is
392bitbake without a UI, only starting a server (cooker) process. -B BIND, 402 passed to the handler. Two common values are none and
393--bind=BIND The name/address for the bitbake xmlrpc server to bind to. 403 printdiff but the handler may define more/less. none
394-T SERVER_TIMEOUT, --idle-timeout=SERVER_TIMEOUT Set timeout to unload 404 means only dump the signature, printdiff means compare
395bitbake server due to inactivity, set to -1 means no unload, default: 405 the dumped signature with the cached one.
396Environment variable BB_SERVER_TIMEOUT. --no-setscene Do not run any 406 -p, --parse-only Quit after parsing the BB recipes.
397setscene tasks. sstate will be ignored and everything needed, built. 407 -s, --show-versions Show current and preferred versions of all recipes.
398--setscene-only Only run setscene tasks, don't run any real tasks. 408 -e, --environment Show the global or per-recipe environment complete
399--remote-server=REMOTE_SERVER Connect to the specified server. -m, 409 with information about where variables were
400--kill-server Terminate any running bitbake server. --observe-only 410 set/changed.
401Connect to a server as an observing-only client. --status-only Check the 411 -g, --graphviz Save dependency tree information for the specified
402status of the remote bitbake server. -w WRITEEVENTLOG, 412 targets in the dot syntax.
403--write-log=WRITEEVENTLOG Writes the event log of the build to a bitbake 413 -I EXTRA_ASSUME_PROVIDED, --ignore-deps=EXTRA_ASSUME_PROVIDED
404event json file. Use '' (empty string) to assign the name automatically. 414 Assume these dependencies don't exist and are already
405--runall=RUNALL Run the specified task for any recipe in the taskgraph 415 provided (equivalent to ASSUME_PROVIDED). Useful to
406of the specified target (even if it wouldn't otherwise have run). 416 make dependency graphs more appealing
407--runonly=RUNONLY Run only the specified task within the taskgraph of 417 -l DEBUG_DOMAINS, --log-domains=DEBUG_DOMAINS
408the specified targets (and any task dependencies those tasks may have). 418 Show debug logging for the specified logging domains
419 -P, --profile Profile the command and save reports.
420 -u UI, --ui=UI The user interface to use (knotty, ncurses or taskexp
421 - default knotty).
422 --token=XMLRPCTOKEN Specify the connection token to be used when
423 connecting to a remote server.
424 --revisions-changed Set the exit code depending on whether upstream
425 floating revisions have changed or not.
426 --server-only Run bitbake without a UI, only starting a server
427 (cooker) process.
428 -B BIND, --bind=BIND The name/address for the bitbake xmlrpc server to bind
429 to.
430 -T SERVER_TIMEOUT, --idle-timeout=SERVER_TIMEOUT
431 Set timeout to unload bitbake server due to
432 inactivity, set to -1 means no unload, default:
433 Environment variable BB_SERVER_TIMEOUT.
434 --no-setscene Do not run any setscene tasks. sstate will be ignored
435 and everything needed, built.
436 --setscene-only Only run setscene tasks, don't run any real tasks.
437 --remote-server=REMOTE_SERVER
438 Connect to the specified server.
439 -m, --kill-server Terminate any running bitbake server.
440 --observe-only Connect to a server as an observing-only client.
441 --status-only Check the status of the remote bitbake server.
442 -w WRITEEVENTLOG, --write-log=WRITEEVENTLOG
443 Writes the event log of the build to a bitbake event
444 json file. Use '' (empty string) to assign the name
445 automatically.
446 --runall=RUNALL Run the specified task for any recipe in the taskgraph
447 of the specified target (even if it wouldn't otherwise
448 have run).
449 --runonly=RUNONLY Run only the specified task within the taskgraph of
450 the specified targets (and any task dependencies those
451 tasks may have).
409 452
410.. _bitbake-examples: 453.. _bitbake-examples:
411 454
@@ -426,9 +469,13 @@ default task, which is "build”. BitBake obeys inter-task dependencies
426when doing so. 469when doing so.
427 470
428The following command runs the build task, which is the default task, on 471The following command runs the build task, which is the default task, on
429the ``foo_1.0.bb`` recipe file: $ bitbake -b foo_1.0.bb The following 472the ``foo_1.0.bb`` recipe file: ::
430command runs the clean task on the ``foo.bb`` recipe file: $ bitbake -b 473
431foo.bb -c clean 474 $ bitbake -b foo_1.0.bb
475
476The following command runs the clean task on the ``foo.bb`` recipe file: ::
477
478 $ bitbake -b foo.bb -c clean
432 479
433.. note:: 480.. note::
434 481
@@ -450,9 +497,15 @@ functionality, or when there are multiple versions of a recipe.
450The ``bitbake`` command, when not using "--buildfile" or "-b" only 497The ``bitbake`` command, when not using "--buildfile" or "-b" only
451accepts a "PROVIDES". You cannot provide anything else. By default, a 498accepts a "PROVIDES". You cannot provide anything else. By default, a
452recipe file generally "PROVIDES" its "packagename" as shown in the 499recipe file generally "PROVIDES" its "packagename" as shown in the
453following example: $ bitbake foo This next example "PROVIDES" the 500following example: ::
501
502 $ bitbake foo
503
504This next example "PROVIDES" the
454package name and also uses the "-c" option to tell BitBake to just 505package name and also uses the "-c" option to tell BitBake to just
455execute the ``do_clean`` task: $ bitbake -c clean foo 506execute the ``do_clean`` task: ::
507
508 $ bitbake -c clean foo
456 509
457Executing a List of Task and Recipe Combinations 510Executing a List of Task and Recipe Combinations
458~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 511~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -461,8 +514,9 @@ The BitBake command line supports specifying different tasks for
461individual targets when you specify multiple targets. For example, 514individual targets when you specify multiple targets. For example,
462suppose you had two targets (or recipes) ``myfirstrecipe`` and 515suppose you had two targets (or recipes) ``myfirstrecipe`` and
463``mysecondrecipe`` and you needed BitBake to run ``taskA`` for the first 516``mysecondrecipe`` and you needed BitBake to run ``taskA`` for the first
464recipe and ``taskB`` for the second recipe: $ bitbake 517recipe and ``taskB`` for the second recipe: ::
465myfirstrecipe:do_taskA mysecondrecipe:do_taskB 518
519 $ bitbake myfirstrecipe:do_taskA mysecondrecipe:do_taskB
466 520
467Generating Dependency Graphs 521Generating Dependency Graphs
468~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 522~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -474,10 +528,10 @@ You can convert these graphs into images using the ``dot`` tool from
474When you generate a dependency graph, BitBake writes two files to the 528When you generate a dependency graph, BitBake writes two files to the
475current working directory: 529current working directory:
476 530
477- *``task-depends.dot``:* Shows dependencies between tasks. These 531- ``task-depends.dot``: Shows dependencies between tasks. These
478 dependencies match BitBake's internal task execution list. 532 dependencies match BitBake's internal task execution list.
479 533
480- *``pn-buildlist``:* Shows a simple list of targets that are to be 534- ``pn-buildlist``: Shows a simple list of targets that are to be
481 built. 535 built.
482 536
483To stop depending on common depends, use the "-I" depend option and 537To stop depending on common depends, use the "-I" depend option and
@@ -486,8 +540,11 @@ produce more readable graphs. This way, you can remove from the graph
486``DEPENDS`` from inherited classes such as ``base.bbclass``. 540``DEPENDS`` from inherited classes such as ``base.bbclass``.
487 541
488Here are two examples that create dependency graphs. The second example 542Here are two examples that create dependency graphs. The second example
489omits depends common in OpenEmbedded from the graph: $ bitbake -g foo $ 543omits depends common in OpenEmbedded from the graph: ::
490bitbake -g -I virtual/kernel -I eglibc foo 544
545 $ bitbake -g foo
546
547 $ bitbake -g -I virtual/kernel -I eglibc foo
491 548
492Executing a Multiple Configuration Build 549Executing a Multiple Configuration Build
493~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 550~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -504,6 +561,9 @@ files is specific. They must reside in the current build directory in a
504sub-directory of ``conf`` named ``multiconfig``. Following is an example 561sub-directory of ``conf`` named ``multiconfig``. Following is an example
505for two separate targets: 562for two separate targets:
506 563
564.. image:: figures/bb_multiconfig_files.png
565 :align: center
566
507The reason for this required file hierarchy is because the ``BBPATH`` 567The reason for this required file hierarchy is because the ``BBPATH``
508variable is not constructed until the layers are parsed. Consequently, 568variable is not constructed until the layers are parsed. Consequently,
509using the configuration file as a pre-configuration file is not possible 569using the configuration file as a pre-configuration file is not possible
@@ -522,14 +582,19 @@ accomplished by setting the
522configuration files for ``target1`` and ``target2`` defined in the build 582configuration files for ``target1`` and ``target2`` defined in the build
523directory. The following statement in the ``local.conf`` file both 583directory. The following statement in the ``local.conf`` file both
524enables BitBake to perform multiple configuration builds and specifies 584enables BitBake to perform multiple configuration builds and specifies
525the two extra multiconfigs: BBMULTICONFIG = "target1 target2" 585the two extra multiconfigs: ::
586
587 BBMULTICONFIG = "target1 target2"
526 588
527Once the target configuration files are in place and BitBake has been 589Once the target configuration files are in place and BitBake has been
528enabled to perform multiple configuration builds, use the following 590enabled to perform multiple configuration builds, use the following
529command form to start the builds: $ bitbake [mc:multiconfigname:]target 591command form to start the builds: ::
530[[[mc:multiconfigname:]target] ... ] Here is an example for two extra 592
531multiconfigs: ``target1`` and ``target2``: $ bitbake mc::target 593 $ bitbake [mc:multiconfigname:]target [[[mc:multiconfigname:]target] ... ]
532mc:target1:target mc:target2:target 594
595Here is an example for two extra multiconfigs: ``target1`` and ``target2``: ::
596
597 $ bitbake mc::target mc:target1:target mc:target2:target
533 598
534.. _bb-enabling-multiple-configuration-build-dependencies: 599.. _bb-enabling-multiple-configuration-build-dependencies:
535 600
@@ -548,26 +613,37 @@ multiconfig.
548 613
549To enable dependencies in a multiple configuration build, you must 614To enable dependencies in a multiple configuration build, you must
550declare the dependencies in the recipe using the following statement 615declare the dependencies in the recipe using the following statement
551form: task_or_package[mcdepends] = 616form: ::
552"mc:from_multiconfig:to_multiconfig:recipe_name:task_on_which_to_depend" 617
618 task_or_package[mcdepends] = "mc:from_multiconfig:to_multiconfig:recipe_name:task_on_which_to_depend"
619
553To better show how to use this statement, consider an example with two 620To better show how to use this statement, consider an example with two
554multiconfigs: ``target1`` and ``target2``: image_task[mcdepends] = 621multiconfigs: ``target1`` and ``target2``: ::
555"mc:target1:target2:image2:rootfs_task" In this example, the 622
556from_multiconfig is "target1" and the to_multiconfig is "target2". The 623 image_task[mcdepends] = "mc:target1:target2:image2:rootfs_task"
624
625In this example, the
626``from_multiconfig`` is "target1" and the ``to_multiconfig`` is "target2". The
557task on which the image whose recipe contains image_task depends on the 627task on which the image whose recipe contains image_task depends on the
558completion of the rootfs_task used to build out image2, which is 628completion of the rootfs_task used to build out image2, which is
559associated with the "target2" multiconfig. 629associated with the "target2" multiconfig.
560 630
561Once you set up this dependency, you can build the "target1" multiconfig 631Once you set up this dependency, you can build the "target1" multiconfig
562using a BitBake command as follows: $ bitbake mc:target1:image1 This 632using a BitBake command as follows: ::
563command executes all the tasks needed to create image1 for the "target1" 633
634 $ bitbake mc:target1:image1
635
636This command executes all the tasks needed to create ``image1`` for the "target1"
564multiconfig. Because of the dependency, BitBake also executes through 637multiconfig. Because of the dependency, BitBake also executes through
565the rootfs_task for the "target2" multiconfig build. 638the ``rootfs_task`` for the "target2" multiconfig build.
566 639
567Having a recipe depend on the root filesystem of another build might not 640Having a recipe depend on the root filesystem of another build might not
568seem that useful. Consider this change to the statement in the image1 641seem that useful. Consider this change to the statement in the image1
569recipe: image_task[mcdepends] = "mc:target1:target2:image2:image_task" 642recipe: ::
570In this case, BitBake must create image2 for the "target2" build since 643
644 image_task[mcdepends] = "mc:target1:target2:image2:image_task"
645
646In this case, BitBake must create ``image2`` for the "target2" build since
571the "target1" build depends on it. 647the "target1" build depends on it.
572 648
573Because "target1" and "target2" are enabled for multiple configuration 649Because "target1" and "target2" are enabled for multiple configuration
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 4de70e8e1d..12491c5947 100644
--- a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
+++ b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
@@ -21,16 +21,28 @@ Basic Variable Setting
21 21
22The following example sets ``VARIABLE`` to "value". This assignment 22The following example sets ``VARIABLE`` to "value". This assignment
23occurs immediately as the statement is parsed. It is a "hard" 23occurs immediately as the statement is parsed. It is a "hard"
24assignment. VARIABLE = "value" As expected, if you include leading or 24assignment. ::
25trailing spaces as part of an assignment, the spaces are retained: 25
26VARIABLE = " value" VARIABLE = "value " Setting ``VARIABLE`` to "" sets 26 VARIABLE = "value"
27
28As expected, if you include leading or
29trailing spaces as part of an assignment, the spaces are retained: ::
30
31 VARIABLE = " value"
32 VARIABLE = "value "
33
34Setting ``VARIABLE`` to "" sets
27it to an empty string, while setting the variable to " " sets it to a 35it to an empty string, while setting the variable to " " sets it to a
28blank space (i.e. these are not the same values). VARIABLE = "" VARIABLE 36blank space (i.e. these are not the same values). ::
29= " " 37
38 VARIABLE = ""
39 VARIABLE = " "
30 40
31You can use single quotes instead of double quotes when setting a 41You can use single quotes instead of double quotes when setting a
32variable's value. Doing so allows you to use values that contain the 42variable's value. Doing so allows you to use values that contain the
33double quote character: VARIABLE = 'I have a " in my value' 43double quote character: ::
44
45 VARIABLE = 'I have a " in my value'
34 46
35.. note:: 47.. note::
36 48
@@ -65,7 +77,11 @@ occurs, you can use BitBake to check the actual value of the suspect
65variable. You can make these checks for both configuration and recipe 77variable. You can make these checks for both configuration and recipe
66level changes: 78level changes:
67 79
68- For configuration changes, use the following: $ bitbake -e This 80- For configuration changes, use the following: ::
81
82 $ bitbake -e
83
84 This
69 command displays variable values after the configuration files (i.e. 85 command displays variable values after the configuration files (i.e.
70 ``local.conf``, ``bblayers.conf``, ``bitbake.conf`` and so forth) 86 ``local.conf``, ``bblayers.conf``, ``bitbake.conf`` and so forth)
71 have been parsed. 87 have been parsed.
@@ -75,33 +91,43 @@ level changes:
75 Variables that are exported to the environment are preceded by the 91 Variables that are exported to the environment are preceded by the
76 string "export" in the command's output. 92 string "export" in the command's output.
77 93
78- For recipe changes, use the following: $ bitbake recipe -e \| grep 94- For recipe changes, use the following: ::
79 VARIABLE=" This command checks to see if the variable actually makes 95
96 $ bitbake recipe -e \| grep VARIABLE="
97
98 This command checks to see if the variable actually makes
80 it into a specific recipe. 99 it into a specific recipe.
81 100
82Line Joining 101Line Joining
83------------ 102------------
84 103
85Outside of `functions <#functions>`__, BitBake joins any line ending in 104Outside of :ref:`functions <bitbake-user-manual/bitbake-user-manual-metadata:functions>`,
105BitBake joins any line ending in
86a backslash character ("\") with the following line before parsing 106a backslash character ("\") with the following line before parsing
87statements. The most common use for the "\" character is to split 107statements. The most common use for the "\" character is to split
88variable assignments over multiple lines, as in the following example: 108variable assignments over multiple lines, as in the following example: ::
89FOO = "bar \\ baz \\ qaz" Both the "\" character and the newline 109
110 FOO = "bar \
111 baz \
112 qaz"
113
114Both the "\" character and the newline
90character that follow it are removed when joining lines. Thus, no 115character that follow it are removed when joining lines. Thus, no
91newline characters end up in the value of ``FOO``. 116newline characters end up in the value of ``FOO``.
92 117
93Consider this additional example where the two assignments both assign 118Consider this additional example where the two assignments both assign
94"barbaz" to ``FOO``: FOO = "barbaz" FOO = "bar\\ baz" 119"barbaz" to ``FOO``: ::
120
121 FOO = "barbaz"
122 FOO = "bar\
123 baz"
95 124
96.. note:: 125.. note::
97 126
98 BitBake does not interpret escape sequences like "\n" in variable 127 BitBake does not interpret escape sequences like "\n" in variable
99 values. For these to have an effect, the value must be passed to some 128 values. For these to have an effect, the value must be passed to some
100 utility that interprets escape sequences, such as 129 utility that interprets escape sequences, such as
101 printf 130 ``printf`` or ``echo -n``.
102 or
103 echo -n
104 .
105 131
106Variable Expansion 132Variable Expansion
107------------------ 133------------------
@@ -109,32 +135,41 @@ Variable Expansion
109Variables can reference the contents of other variables using a syntax 135Variables can reference the contents of other variables using a syntax
110that is similar to variable expansion in Bourne shells. The following 136that is similar to variable expansion in Bourne shells. The following
111assignments result in A containing "aval" and B evaluating to 137assignments result in A containing "aval" and B evaluating to
112"preavalpost". A = "aval" B = "pre${A}post" 138"preavalpost". ::
139
140 A = "aval"
141 B = "pre${A}post"
113 142
114.. note:: 143.. note::
115 144
116 Unlike in Bourne shells, the curly braces are mandatory: Only 145 Unlike in Bourne shells, the curly braces are mandatory: Only ``${FOO}`` and not
117 ${FOO} 146 ``$FOO`` is recognized as an expansion of ``FOO``.
118 and not
119 $FOO
120 is recognized as an expansion of
121 FOO
122 .
123 147
124The "=" operator does not immediately expand variable references in the 148The "=" operator does not immediately expand variable references in the
125right-hand side. Instead, expansion is deferred until the variable 149right-hand side. Instead, expansion is deferred until the variable
126assigned to is actually used. The result depends on the current values 150assigned to is actually used. The result depends on the current values
127of the referenced variables. The following example should clarify this 151of the referenced variables. The following example should clarify this
128behavior: A = "${B} baz" B = "${C} bar" C = "foo" \*At this point, ${A} 152behavior: ::
129equals "foo bar baz"\* C = "qux" \*At this point, ${A} equals "qux bar 153
130baz"\* B = "norf" \*At this point, ${A} equals "norf baz"\* Contrast 154 A = "${B} baz"
131this behavior with the `immediate variable 155 B = "${C} bar"
132expansion <#immediate-variable-expansion>`__ operator (i.e. ":="). 156 C = "foo"
157 *At this point, ${A} equals "foo bar baz"*
158 C = "qux"
159 *At this point, ${A} equals "qux bar baz"*
160 B = "norf"
161 *At this point, ${A} equals "norf baz"\*
162
163Contrast this behavior with the
164:ref:`bitbake-user-manual/bitbake-user-manual-metadata:immediate variable
165expansion (:=)` operator.
133 166
134If the variable expansion syntax is used on a variable that does not 167If the variable expansion syntax is used on a variable that does not
135exist, the string is kept as is. For example, given the following 168exist, the string is kept as is. For example, given the following
136assignment, ``BAR`` expands to the literal string "${FOO}" as long as 169assignment, ``BAR`` expands to the literal string "${FOO}" as long as
137``FOO`` does not exist. BAR = "${FOO}" 170``FOO`` does not exist. ::
171
172 BAR = "${FOO}"
138 173
139Setting a default value (?=) 174Setting a default value (?=)
140---------------------------- 175----------------------------
@@ -142,7 +177,11 @@ Setting a default value (?=)
142You can use the "?=" operator to achieve a "softer" assignment for a 177You can use the "?=" operator to achieve a "softer" assignment for a
143variable. This type of assignment allows you to define a variable if it 178variable. This type of assignment allows you to define a variable if it
144is undefined when the statement is parsed, but to leave the value alone 179is undefined when the statement is parsed, but to leave the value alone
145if the variable has a value. Here is an example: A ?= "aval" If ``A`` is 180if the variable has a value. Here is an example: ::
181
182 A ?= "aval"
183
184If ``A`` is
146set at the time this statement is parsed, the variable retains its 185set at the time this statement is parsed, the variable retains its
147value. However, if ``A`` is not set, the variable is set to "aval". 186value. However, if ``A`` is not set, the variable is set to "aval".
148 187
@@ -160,8 +199,12 @@ by using the "??=" operator. This assignment behaves identical to "?="
160except that the assignment is made at the end of the parsing process 199except that the assignment is made at the end of the parsing process
161rather than immediately. Consequently, when multiple "??=" assignments 200rather than immediately. Consequently, when multiple "??=" assignments
162exist, the last one is used. Also, any "=" or "?=" assignment will 201exist, the last one is used. Also, any "=" or "?=" assignment will
163override the value set with "??=". Here is an example: A ??= "somevalue" 202override the value set with "??=". Here is an example: ::
164A ??= "someothervalue" If ``A`` is set before the above statements are 203
204 A ??= "somevalue"
205 A ??= "someothervalue"
206
207If ``A`` is set before the above statements are
165parsed, the variable retains its value. If ``A`` is not set, the 208parsed, the variable retains its value. If ``A`` is not set, the
166variable is set to "someothervalue". 209variable is set to "someothervalue".
167 210
@@ -172,8 +215,15 @@ Immediate variable expansion (:=)
172--------------------------------- 215---------------------------------
173 216
174The ":=" operator results in a variable's contents being expanded 217The ":=" operator results in a variable's contents being expanded
175immediately, rather than when the variable is actually used: T = "123" A 218immediately, rather than when the variable is actually used: ::
176:= "test ${T}" T = "456" B := "${T} ${C}" C = "cval" C := "${C}append" 219
220 T = "123"
221 A := "test ${T}"
222 T = "456"
223 B := "${T} ${C}"
224 C = "cval"
225 C := "${C}append"
226
177In this example, ``A`` contains "test 123", even though the final value 227In this example, ``A`` contains "test 123", even though the final value
178of ``T`` is "456". The variable ``B`` will end up containing "456 228of ``T`` is "456". The variable ``B`` will end up containing "456
179cvalappend". This is because references to undefined variables are 229cvalappend". This is because references to undefined variables are
@@ -191,8 +241,14 @@ the "+=" and "=+" operators. These operators insert a space between the
191current value and prepended or appended value. 241current value and prepended or appended value.
192 242
193These operators take immediate effect during parsing. Here are some 243These operators take immediate effect during parsing. Here are some
194examples: B = "bval" B += "additionaldata" C = "cval" C =+ "test" The 244examples: ::
195variable ``B`` contains "bval additionaldata" and ``C`` contains "test 245
246 B = "bval"
247 B += "additionaldata"
248 C = "cval"
249 C =+ "test"
250
251The variable ``B`` contains "bval additionaldata" and ``C`` contains "test
196cval". 252cval".
197 253
198.. _appending-and-prepending-without-spaces: 254.. _appending-and-prepending-without-spaces:
@@ -204,8 +260,14 @@ If you want to append or prepend values without an inserted space, use
204the ".=" and "=." operators. 260the ".=" and "=." operators.
205 261
206These operators take immediate effect during parsing. Here are some 262These operators take immediate effect during parsing. Here are some
207examples: B = "bval" B .= "additionaldata" C = "cval" C =. "test" The 263examples: ::
208variable ``B`` contains "bvaladditionaldata" and ``C`` contains 264
265 B = "bval"
266 B .= "additionaldata"
267 C = "cval"
268 C =. "test"
269
270The variable ``B`` contains "bvaladditionaldata" and ``C`` contains
209"testcval". 271"testcval".
210 272
211Appending and Prepending (Override Style Syntax) 273Appending and Prepending (Override Style Syntax)
@@ -216,9 +278,16 @@ style syntax. When you use this syntax, no spaces are inserted.
216 278
217These operators differ from the ":=", ".=", "=.", "+=", and "=+" 279These operators differ from the ":=", ".=", "=.", "+=", and "=+"
218operators in that their effects are applied at variable expansion time 280operators in that their effects are applied at variable expansion time
219rather than being immediately applied. Here are some examples: B = 281rather than being immediately applied. Here are some examples: ::
220"bval" B_append = " additional data" C = "cval" C_prepend = "additional 282
221data " D = "dval" D_append = "additional data" The variable ``B`` 283 B = "bval"
284 B_append = " additional data"
285 C = "cval"
286 C_prepend = "additional data "
287 D = "dval"
288 D_append = "additional data"
289
290The variable ``B``
222becomes "bval additional data" and ``C`` becomes "additional data cval". 291becomes "bval additional data" and ``C`` becomes "additional data cval".
223The variable ``D`` becomes "dvaladditional data". 292The variable ``D`` becomes "dvaladditional data".
224 293
@@ -227,9 +296,8 @@ The variable ``D`` becomes "dvaladditional data".
227 You must control all spacing when you use the override syntax. 296 You must control all spacing when you use the override syntax.
228 297
229It is also possible to append and prepend to shell functions and 298It is also possible to append and prepend to shell functions and
230BitBake-style Python functions. See the "`Shell 299BitBake-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`"
231Functions <#shell-functions>`__" and "`BitBake-Style Python 300sections for examples.
232Functions <#bitbake-style-python-functions>`__ sections for examples.
233 301
234.. _removing-override-style-syntax: 302.. _removing-override-style-syntax:
235 303
@@ -241,11 +309,20 @@ syntax. Specifying a value for removal causes all occurrences of that
241value to be removed from the variable. 309value to be removed from the variable.
242 310
243When you use this syntax, BitBake expects one or more strings. 311When you use this syntax, BitBake expects one or more strings.
244Surrounding spaces and spacing are preserved. Here is an example: FOO = 312Surrounding spaces and spacing are preserved. Here is an example: ::
245"123 456 789 123456 123 456 123 456" FOO_remove = "123" FOO_remove = 313
246"456" FOO2 = " abc def ghi abcdef abc def abc def def" FOO2_remove = " 314 FOO = "123 456 789 123456 123 456 123 456"
247\\ def \\ abc \\ ghi \\ " The variable ``FOO`` becomes 315 FOO_remove = "123"
248"  789 123456    " and ``FOO2`` becomes "     abcdef      ". 316 FOO_remove = "456"
317 FOO2 = " abc def ghi abcdef abc def abc def def"
318 FOO2_remove = "\
319 def \
320 abc \
321 ghi \
322 "
323
324The variable ``FOO`` becomes
325" 789 123456 " and ``FOO2`` becomes " abcdef ".
249 326
250Like "_append" and "_prepend", "_remove" is applied at variable 327Like "_append" and "_prepend", "_remove" is applied at variable
251expansion time. 328expansion time.
@@ -257,105 +334,115 @@ An advantage of the override style operations "_append", "_prepend", and
257"_remove" as compared to the "+=" and "=+" operators is that the 334"_remove" as compared to the "+=" and "=+" operators is that the
258override style operators provide guaranteed operations. For example, 335override style operators provide guaranteed operations. For example,
259consider a class ``foo.bbclass`` that needs to add the value "val" to 336consider a class ``foo.bbclass`` that needs to add the value "val" to
260the variable ``FOO``, and a recipe that uses ``foo.bbclass`` as follows: 337the variable ``FOO``, and a recipe that uses ``foo.bbclass`` as follows: ::
261inherit foo FOO = "initial" If ``foo.bbclass`` uses the "+=" operator, 338
339 inherit foo
340 FOO = "initial"
341
342If ``foo.bbclass`` uses the "+=" operator,
262as follows, then the final value of ``FOO`` will be "initial", which is 343as follows, then the final value of ``FOO`` will be "initial", which is
263not what is desired: FOO += "val" If, on the other hand, ``foo.bbclass`` 344not what is desired: ::
345
346 FOO += "val"
347
348If, on the other hand, ``foo.bbclass``
264uses the "_append" operator, then the final value of ``FOO`` will be 349uses the "_append" operator, then the final value of ``FOO`` will be
265"initial val", as intended: FOO_append = " val" 350"initial val", as intended: ::
351
352 FOO_append = " val"
266 353
267.. note:: 354.. note::
268 355
269 It is never necessary to use "+=" together with "_append". The 356 It is never necessary to use "+=" together with "_append". The following
270 following sequence of assignments appends "barbaz" to 357 sequence of assignments appends "barbaz" to FOO: ::
271 FOO 358
272 : 359 FOO_append = "bar"
273 :: 360 FOO_append = "baz"
274 361
275 FOO_append = "bar"
276 FOO_append = "baz"
277
278 362
279 The only effect of changing the second assignment in the previous 363 The only effect of changing the second assignment in the previous
280 example to use "+=" would be to add a space before "baz" in the 364 example to use "+=" would be to add a space before "baz" in the
281 appended value (due to how the "+=" operator works). 365 appended value (due to how the "+=" operator works).
282 366
283Another advantage of the override style operations is that you can 367Another advantage of the override style operations is that you can
284combine them with other overrides as described in the "`Conditional 368combine them with other overrides as described in the
285Syntax (Overrides) <#conditional-syntax-overrides>`__" section. 369":ref:`bitbake-user-manual/bitbake-user-manual-metadata:conditional syntax (overrides)`" section.
286 370
287Variable Flag Syntax 371Variable Flag Syntax
288-------------------- 372--------------------
289 373
290Variable flags are BitBake's implementation of variable properties or 374Variable flags are BitBake's implementation of variable properties or
291attributes. It is a way of tagging extra information onto a variable. 375attributes. It is a way of tagging extra information onto a variable.
292You can find more out about variable flags in general in the "`Variable 376You can find more out about variable flags in general in the
293Flags <#variable-flags>`__" section. 377":ref:`bitbake-user-manual/bitbake-user-manual-metadata:variable flags`" section.
294 378
295You can define, append, and prepend values to variable flags. All the 379You can define, append, and prepend values to variable flags. All the
296standard syntax operations previously mentioned work for variable flags 380standard syntax operations previously mentioned work for variable flags
297except for override style syntax (i.e. "_prepend", "_append", and 381except for override style syntax (i.e. "_prepend", "_append", and
298"_remove"). 382"_remove").
299 383
300Here are some examples showing how to set variable flags: FOO[a] = "abc" 384Here are some examples showing how to set variable flags: ::
301FOO[b] = "123" FOO[a] += "456" The variable ``FOO`` has two flags: 385
386 FOO[a] = "abc"
387 FOO[b] = "123"
388 FOO[a] += "456"
389
390The variable ``FOO`` has two flags:
302``[a]`` and ``[b]``. The flags are immediately set to "abc" and "123", 391``[a]`` and ``[b]``. The flags are immediately set to "abc" and "123",
303respectively. The ``[a]`` flag becomes "abc 456". 392respectively. The ``[a]`` flag becomes "abc 456".
304 393
305No need exists to pre-define variable flags. You can simply start using 394No need exists to pre-define variable flags. You can simply start using
306them. One extremely common application is to attach some brief 395them. One extremely common application is to attach some brief
307documentation to a BitBake variable as follows: CACHE[doc] = "The 396documentation to a BitBake variable as follows: ::
308directory holding the cache of the metadata." 397
398 CACHE[doc] = "The directory holding the cache of the metadata."
309 399
310Inline Python Variable Expansion 400Inline Python Variable Expansion
311-------------------------------- 401--------------------------------
312 402
313You can use inline Python variable expansion to set variables. Here is 403You can use inline Python variable expansion to set variables. Here is
314an example: DATE = "${@time.strftime('%Y%m%d',time.gmtime())}" This 404an example: ::
315example results in the ``DATE`` variable being set to the current date. 405
406 DATE = "${@time.strftime('%Y%m%d',time.gmtime())}"
407
408This example results in the ``DATE`` variable being set to the current date.
316 409
317Probably the most common use of this feature is to extract the value of 410Probably the most common use of this feature is to extract the value of
318variables from BitBake's internal data dictionary, ``d``. The following 411variables from BitBake's internal data dictionary, ``d``. The following
319lines select the values of a package name and its version number, 412lines select the values of a package name and its version number,
320respectively: PN = 413respectively: ::
321"${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE', False),d)[0] or 414
322'defaultpkgname'}" PV = 415 PN = "${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE', False),d)[0] or 'defaultpkgname'}"
323"${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE', False),d)[1] or 416 PV = "${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE', False),d)[1] or '1.0'}"
324'1.0'}"
325 417
326.. note:: 418.. note::
327 419
328 Inline Python expressions work just like variable expansions insofar 420 Inline Python expressions work just like variable expansions insofar as the
329 as the "=" and ":=" operators are concerned. Given the following 421 "=" and ":=" operators are concerned. Given the following assignment, foo()
330 assignment, 422 is called each time FOO is expanded: ::
331 foo()
332 is called each time
333 FOO
334 is expanded:
335 ::
336 423
337 FOO = "${@foo()}" 424 FOO = "${@foo()}"
338
339 425
340 Contrast this with the following immediate assignment, where 426 Contrast this with the following immediate assignment, where foo() is only
341 foo() 427 called once, while the assignment is parsed: ::
342 is only called once, while the assignment is parsed:
343 ::
344 428
345 FOO := "${@foo()}" 429 FOO := "${@foo()}"
346
347 430
348For a different way to set variables with Python code during parsing, 431For a different way to set variables with Python code during parsing,
349see the "`Anonymous Python Functions <#anonymous-python-functions>`__" 432see the
350section. 433":ref:`bitbake-user-manual/bitbake-user-manual-metadata:anonymous python functions`" section.
351 434
352Unsetting variables 435Unsetting variables
353------------------- 436-------------------
354 437
355It is possible to completely remove a variable or a variable flag from 438It is possible to completely remove a variable or a variable flag from
356BitBake's internal data dictionary by using the "unset" keyword. Here is 439BitBake's internal data dictionary by using the "unset" keyword. Here is
357an example: unset DATE unset do_fetch[noexec] These two statements 440an example: ::
358remove the ``DATE`` and the ``do_fetch[noexec]`` flag. 441
442 unset DATE
443 unset do_fetch[noexec]
444
445These two statements remove the ``DATE`` and the ``do_fetch[noexec]`` flag.
359 446
360Providing Pathnames 447Providing Pathnames
361------------------- 448-------------------
@@ -365,34 +452,40 @@ When specifying pathnames for use with BitBake, do not use the tilde
365cause BitBake to not recognize the path since BitBake does not expand 452cause BitBake to not recognize the path since BitBake does not expand
366this character in the same way a shell would. 453this character in the same way a shell would.
367 454
368Instead, provide a fuller path as the following example illustrates: 455Instead, provide a fuller path as the following example illustrates: ::
369BBLAYERS ?= " \\ /home/scott-lenovo/LayerA \\ " 456
457 BBLAYERS ?= " \
458 /home/scott-lenovo/LayerA \
459 "
370 460
371Exporting Variables to the Environment 461Exporting Variables to the Environment
372====================================== 462======================================
373 463
374You can export variables to the environment of running tasks by using 464You can export variables to the environment of running tasks by using
375the ``export`` keyword. For example, in the following example, the 465the ``export`` keyword. For example, in the following example, the
376``do_foo`` task prints "value from the environment" when run: export 466``do_foo`` task prints "value from the environment" when run: ::
377ENV_VARIABLE ENV_VARIABLE = "value from the environment" do_foo() { 467
378bbplain "$ENV_VARIABLE" } 468 export ENV_VARIABLE
469 ENV_VARIABLE = "value from the environment"
470
471 do_foo() {
472 bbplain "$ENV_VARIABLE"
473 }
379 474
380.. note:: 475.. note::
381 476
382 BitBake does not expand 477 BitBake does not expand ``$ENV_VARIABLE`` in this case because it lacks the
383 $ENV_VARIABLE 478 obligatory ``{}`` . Rather, ``$ENV_VARIABLE`` is expanded by the shell.
384 in this case because it lacks the obligatory
385 {}
386 . Rather,
387 $ENV_VARIABLE
388 is expanded by the shell.
389 479
390It does not matter whether ``export ENV_VARIABLE`` appears before or 480It does not matter whether ``export ENV_VARIABLE`` appears before or
391after assignments to ``ENV_VARIABLE``. 481after assignments to ``ENV_VARIABLE``.
392 482
393It is also possible to combine ``export`` with setting a value for the 483It is also possible to combine ``export`` with setting a value for the
394variable. Here is an example: export ENV_VARIABLE = "variable-value" In 484variable. Here is an example: ::
395the output of ``bitbake -e``, variables that are exported to the 485
486 export ENV_VARIABLE = "variable-value"
487
488In the output of ``bitbake -e``, variables that are exported to the
396environment are preceded by "export". 489environment are preceded by "export".
397 490
398Among the variables commonly exported to the environment are ``CC`` and 491Among the variables commonly exported to the environment are ``CC`` and
@@ -425,42 +518,58 @@ variable.
425 to satisfy conditions. Thus, if you have a variable that is 518 to satisfy conditions. Thus, if you have a variable that is
426 conditional on “arm”, and “arm” is in ``OVERRIDES``, then the 519 conditional on “arm”, and “arm” is in ``OVERRIDES``, then the
427 “arm”-specific version of the variable is used rather than the 520 “arm”-specific version of the variable is used rather than the
428 non-conditional version. Here is an example: OVERRIDES = 521 non-conditional version. Here is an example: ::
429 "architecture:os:machine" TEST = "default" TEST_os = "osspecific" 522
430 TEST_nooverride = "othercondvalue" In this example, the ``OVERRIDES`` 523 OVERRIDES = "architecture:os:machine"
524 TEST = "default"
525 TEST_os = "osspecific"
526 TEST_nooverride = "othercondvalue"
527
528 In this example, the ``OVERRIDES``
431 variable lists three overrides: "architecture", "os", and "machine". 529 variable lists three overrides: "architecture", "os", and "machine".
432 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
433 select the os-specific version of the ``TEST`` variable by appending 531 select the os-specific version of the ``TEST`` variable by appending
434 the "os" override to the variable (i.e.\ ``TEST_os``). 532 the "os" override to the variable (i.e. ``TEST_os``).
435 533
436 To better understand this, consider a practical example that assumes 534 To better understand this, consider a practical example that assumes
437 an OpenEmbedded metadata-based Linux kernel recipe file. The 535 an OpenEmbedded metadata-based Linux kernel recipe file. The
438 following lines from the recipe file first set the kernel branch 536 following lines from the recipe file first set the kernel branch
439 variable ``KBRANCH`` to a default value, then conditionally override 537 variable ``KBRANCH`` to a default value, then conditionally override
440 that value based on the architecture of the build: KBRANCH = 538 that value based on the architecture of the build: ::
441 "standard/base" KBRANCH_qemuarm = "standard/arm-versatile-926ejs" 539
442 KBRANCH_qemumips = "standard/mti-malta32" KBRANCH_qemuppc = 540 KBRANCH = "standard/base"
443 "standard/qemuppc" KBRANCH_qemux86 = "standard/common-pc/base" 541 KBRANCH_qemuarm = "standard/arm-versatile-926ejs"
444 KBRANCH_qemux86-64 = "standard/common-pc-64/base" KBRANCH_qemumips64 542 KBRANCH_qemumips = "standard/mti-malta32"
445 = "standard/mti-malta64" 543 KBRANCH_qemuppc = "standard/qemuppc"
544 KBRANCH_qemux86 = "standard/common-pc/base"
545 KBRANCH_qemux86-64 = "standard/common-pc-64/base"
546 KBRANCH_qemumips64 = "standard/mti-malta64"
446 547
447- *Appending and Prepending:* BitBake also supports append and prepend 548- *Appending and Prepending:* BitBake also supports append and prepend
448 operations to variable values based on whether a specific item is 549 operations to variable values based on whether a specific item is
449 listed in ``OVERRIDES``. Here is an example: DEPENDS = "glibc 550 listed in ``OVERRIDES``. Here is an example: ::
450 ncurses" OVERRIDES = "machine:local" DEPENDS_append_machine = " 551
451 libmad" In this example, ``DEPENDS`` becomes "glibc ncurses libmad". 552 DEPENDS = "glibc ncurses"
553 OVERRIDES = "machine:local"
554 DEPENDS_append_machine = "libmad"
555
556 In this example, ``DEPENDS`` becomes "glibc ncurses libmad".
452 557
453 Again, using an OpenEmbedded metadata-based kernel recipe file as an 558 Again, using an OpenEmbedded metadata-based kernel recipe file as an
454 example, the following lines will conditionally append to the 559 example, the following lines will conditionally append to the
455 ``KERNEL_FEATURES`` variable based on the architecture: 560 ``KERNEL_FEATURES`` variable based on the architecture: ::
456 KERNEL_FEATURES_append = " ${KERNEL_EXTRA_FEATURES}" 561
457 KERNEL_FEATURES_append_qemux86=" cfg/sound.scc cfg/paravirt_kvm.scc" 562 KERNEL_FEATURES_append = " ${KERNEL_EXTRA_FEATURES}"
458 KERNEL_FEATURES_append_qemux86-64=" cfg/sound.scc 563 KERNEL_FEATURES_append_qemux86=" cfg/sound.scc cfg/paravirt_kvm.scc"
459 cfg/paravirt_kvm.scc" 564 KERNEL_FEATURES_append_qemux86-64=" cfg/sound.scc cfg/paravirt_kvm.scc"
460 565
461- *Setting a Variable for a Single Task:* BitBake supports setting a 566- *Setting a Variable for a Single Task:* BitBake supports setting a
462 variable just for the duration of a single task. Here is an example: 567 variable just for the duration of a single task. Here is an example: ::
463 FOO_task-configure = "val 1" FOO_task-compile = "val 2" In the 568
569 FOO_task-configure = "val 1"
570 FOO_task-compile = "val 2"
571
572 In the
464 previous example, ``FOO`` has the value "val 1" while the 573 previous example, ``FOO`` has the value "val 1" while the
465 ``do_configure`` task is executed, and the value "val 2" while the 574 ``do_configure`` task is executed, and the value "val 2" while the
466 ``do_compile`` task is executed. 575 ``do_compile`` task is executed.
@@ -471,15 +580,21 @@ variable.
471 ``do_compile`` task. 580 ``do_compile`` task.
472 581
473 You can also use this syntax with other combinations (e.g. 582 You can also use this syntax with other combinations (e.g.
474 "``_prepend``") as shown in the following example: 583 "``_prepend``") as shown in the following example: ::
475 EXTRA_OEMAKE_prepend_task-compile = "${PARALLEL_MAKE} " 584
585 EXTRA_OEMAKE_prepend_task-compile = "${PARALLEL_MAKE} "
476 586
477Key Expansion 587Key Expansion
478------------- 588-------------
479 589
480Key expansion happens when the BitBake datastore is finalized. To better 590Key expansion happens when the BitBake datastore is finalized. To better
481understand this, consider the following example: A${B} = "X" B = "2" A2 591understand this, consider the following example: ::
482= "Y" In this case, after all the parsing is complete, BitBake expands 592
593 A${B} = "X"
594 B = "2"
595 A2 = "Y"
596
597In this case, after all the parsing is complete, BitBake expands
483``${B}`` into "2". This expansion causes ``A2``, which was set to "Y" 598``${B}`` into "2". This expansion causes ``A2``, which was set to "Y"
484before the expansion, to become "X". 599before the expansion, to become "X".
485 600
@@ -499,7 +614,13 @@ There is often confusion concerning the order in which overrides and
499various "append" operators take effect. Recall that an append or prepend 614various "append" operators take effect. Recall that an append or prepend
500operation using "_append" and "_prepend" does not result in an immediate 615operation using "_append" and "_prepend" does not result in an immediate
501assignment as would "+=", ".=", "=+", or "=.". Consider the following 616assignment as would "+=", ".=", "=+", or "=.". Consider the following
502example: OVERRIDES = "foo" A = "Z" A_foo_append = "X" For this case, 617example: ::
618
619 OVERRIDES = "foo"
620 A = "Z"
621 A_foo_append = "X"
622
623For this case,
503``A`` is unconditionally set to "Z" and "X" is unconditionally and 624``A`` is unconditionally set to "Z" and "X" is unconditionally and
504immediately appended to the variable ``A_foo``. Because overrides have 625immediately appended to the variable ``A_foo``. Because overrides have
505not been applied yet, ``A_foo`` is set to "X" due to the append and 626not been applied yet, ``A_foo`` is set to "X" due to the append and
@@ -510,24 +631,42 @@ Applying overrides, however, changes things. Since "foo" is listed in
510version, which is equal to "X". So effectively, ``A_foo`` replaces 631version, which is equal to "X". So effectively, ``A_foo`` replaces
511``A``. 632``A``.
512 633
513This next example changes the order of the override and the append: 634This next example changes the order of the override and the append: ::
514OVERRIDES = "foo" A = "Z" A_append_foo = "X" For this case, before 635
636 OVERRIDES = "foo"
637 A = "Z"
638 A_append_foo = "X"
639
640For this case, before
515overrides are handled, ``A`` is set to "Z" and ``A_append_foo`` is set 641overrides are handled, ``A`` is set to "Z" and ``A_append_foo`` is set
516to "X". Once the override for "foo" is applied, however, ``A`` gets 642to "X". Once the override for "foo" is applied, however, ``A`` gets
517appended with "X". Consequently, ``A`` becomes "ZX". Notice that spaces 643appended with "X". Consequently, ``A`` becomes "ZX". Notice that spaces
518are not appended. 644are not appended.
519 645
520This next example has the order of the appends and overrides reversed 646This next example has the order of the appends and overrides reversed
521back as in the first example: OVERRIDES = "foo" A = "Y" A_foo_append = 647back as in the first example: ::
522"Z" A_foo_append = "X" For this case, before any overrides are resolved, 648
649 OVERRIDES = "foo"
650 A = "Y"
651 A_foo_append = "Z"
652 A_foo_append = "X"
653
654For this case, before any overrides are resolved,
523``A`` is set to "Y" using an immediate assignment. After this immediate 655``A`` is set to "Y" using an immediate assignment. After this immediate
524assignment, ``A_foo`` is set to "Z", and then further appended with "X" 656assignment, ``A_foo`` is set to "Z", and then further appended with "X"
525leaving the variable set to "ZX". Finally, applying the override for 657leaving the variable set to "ZX". Finally, applying the override for
526"foo" results in the conditional variable ``A`` becoming "ZX" (i.e. 658"foo" results in the conditional variable ``A`` becoming "ZX" (i.e.
527``A`` is replaced with ``A_foo``). 659``A`` is replaced with ``A_foo``).
528 660
529This final example mixes in some varying operators: A = "1" A_append = 661This final example mixes in some varying operators: ::
530"2" A_append = "3" A += "4" A .= "5" For this case, the type of append 662
663 A = "1"
664 A_append = "2"
665 A_append = "3"
666 A += "4"
667 A .= "5"
668
669For this case, the type of append
531operators are affecting the order of assignments as BitBake passes 670operators are affecting the order of assignments as BitBake passes
532through the code multiple times. Initially, ``A`` is set to "1 45" 671through the code multiple times. Initially, ``A`` is set to "1 45"
533because of the three statements that use immediate operators. After 672because of the three statements that use immediate operators. After
@@ -559,11 +698,7 @@ current directory for ``include`` and ``require`` directives.
559 698
560.. note:: 699.. note::
561 700
562 The 701 The BBPATH variable is analogous to the environment variable PATH .
563 BBPATH
564 variable is analogous to the environment variable
565 PATH
566 .
567 702
568In order for include and class files to be found by BitBake, they need 703In order for include and class files to be found by BitBake, they need
569to be located in a "classes" subdirectory that can be found in 704to be located in a "classes" subdirectory that can be found in
@@ -585,8 +720,11 @@ file and then have your recipe inherit that class file.
585 720
586As an example, your recipes could use the following directive to inherit 721As an example, your recipes could use the following directive to inherit
587an ``autotools.bbclass`` file. The class file would contain common 722an ``autotools.bbclass`` file. The class file would contain common
588functionality for using Autotools that could be shared across recipes: 723functionality for using Autotools that could be shared across recipes: ::
589inherit autotools In this case, BitBake would search for the directory 724
725 inherit autotools
726
727In this case, BitBake would search for the directory
590``classes/autotools.bbclass`` in ``BBPATH``. 728``classes/autotools.bbclass`` in ``BBPATH``.
591 729
592.. note:: 730.. note::
@@ -596,24 +734,42 @@ inherit autotools In this case, BitBake would search for the directory
596 734
597If you want to use the directive to inherit multiple classes, separate 735If you want to use the directive to inherit multiple classes, separate
598them with spaces. The following example shows how to inherit both the 736them with spaces. The following example shows how to inherit both the
599``buildhistory`` and ``rm_work`` classes: inherit buildhistory rm_work 737``buildhistory`` and ``rm_work`` classes: ::
738
739 inherit buildhistory rm_work
600 740
601An advantage with the inherit directive as compared to both the 741An advantage with the inherit directive as compared to both the
602`include <#include-directive>`__ and `require <#require-inclusion>`__ 742:ref:`include <bitbake-user-manual/bitbake-user-manual-metadata:\`\`include\`\` directive>` and :ref:`require <bitbake-user-manual/bitbake-user-manual-metadata:\`\`require\`\` directive>`
603directives is that you can inherit class files conditionally. You can 743directives is that you can inherit class files conditionally. You can
604accomplish this by using a variable expression after the ``inherit`` 744accomplish this by using a variable expression after the ``inherit``
605statement. Here is an example: inherit ${VARNAME} If ``VARNAME`` is 745statement. Here is an example: ::
746
747 inherit ${VARNAME}
748
749If ``VARNAME`` is
606going to be set, it needs to be set before the ``inherit`` statement is 750going to be set, it needs to be set before the ``inherit`` statement is
607parsed. One way to achieve a conditional inherit in this case is to use 751parsed. One way to achieve a conditional inherit in this case is to use
608overrides: VARIABLE = "" VARIABLE_someoverride = "myclass" 752overrides: ::
753
754 VARIABLE = ""
755 VARIABLE_someoverride = "myclass"
756
757Another method is by using anonymous Python. Here is an example: ::
609 758
610Another method is by using anonymous Python. Here is an example: python 759 python () {
611() { if condition == value: d.setVar('VARIABLE', 'myclass') else: 760 if condition == value:
612d.setVar('VARIABLE', '') } 761 d.setVar('VARIABLE', 'myclass')
762 else:
763 d.setVar('VARIABLE', '')
764 }
613 765
614Alternatively, you could use an in-line Python expression in the 766Alternatively, you could use an in-line Python expression in the
615following form: inherit ${@'classname' if condition else ''} inherit 767following form: ::
616${@functionname(params)} In all cases, if the expression evaluates to an 768
769 inherit ${@'classname' if condition else ''}
770 inherit ${@functionname(params)}
771
772In all cases, if the expression evaluates to an
617empty string, the statement does not trigger a syntax error because it 773empty string, the statement does not trigger a syntax error because it
618becomes a no-op. 774becomes a no-op.
619 775
@@ -627,27 +783,24 @@ that if the path specified on the include line is a relative path,
627BitBake locates the first file it can find within ``BBPATH``. 783BitBake locates the first file it can find within ``BBPATH``.
628 784
629The include directive is a more generic method of including 785The include directive is a more generic method of including
630functionality as compared to the `inherit <#inherit-directive>`__ 786functionality as compared to the :ref:`inherit <bitbake-user-manual/bitbake-user-manual-metadata:\`\`inherit\`\` directive>`
631directive, which is restricted to class (i.e. ``.bbclass``) files. The 787directive, which is restricted to class (i.e. ``.bbclass``) files. The
632include directive is applicable for any other kind of shared or 788include directive is applicable for any other kind of shared or
633encapsulated functionality or configuration that does not suit a 789encapsulated functionality or configuration that does not suit a
634``.bbclass`` file. 790``.bbclass`` file.
635 791
636As an example, suppose you needed a recipe to include some self-test 792As an example, suppose you needed a recipe to include some self-test
637definitions: include test_defs.inc 793definitions: ::
794
795 include test_defs.inc
638 796
639.. note:: 797.. note::
640 798
641 The 799 The include directive does not produce an error when the file cannot be
642 include 800 found. Consequently, it is recommended that if the file you are including is
643 directive does not produce an error when the file cannot be found. 801 expected to exist, you should use :ref:`require <require-inclusion>` instead
644 Consequently, it is recommended that if the file you are including is 802 of include . Doing so makes sure that an error is produced if the file cannot
645 expected to exist, you should use 803 be found.
646 :ref:`require <require-inclusion>`
647 instead of
648 include
649 . Doing so makes sure that an error is produced if the file cannot be
650 found.
651 804
652.. _require-inclusion: 805.. _require-inclusion:
653 806
@@ -662,12 +815,12 @@ the location of the directive.
662 815
663The require directive, like the include directive previously described, 816The require directive, like the include directive previously described,
664is a more generic method of including functionality as compared to the 817is a more generic method of including functionality as compared to the
665`inherit <#inherit-directive>`__ directive, which is restricted to class 818:ref:`inherit <bitbake-user-manual/bitbake-user-manual-metadata:\`\`inherit\`\` directive>` directive, which is restricted to class
666(i.e. ``.bbclass``) files. The require directive is applicable for any 819(i.e. ``.bbclass``) files. The require directive is applicable for any
667other kind of shared or encapsulated functionality or configuration that 820other kind of shared or encapsulated functionality or configuration that
668does not suit a ``.bbclass`` file. 821does not suit a ``.bbclass`` file.
669 822
670Similar to how BitBake handles ```include`` <#include-directive>`__, if 823Similar to how BitBake handles :ref:`include <bitbake-user-manual/bitbake-user-manual-metadata:\`\`include\`\` directive>`, if
671the path specified on the require line is a relative path, BitBake 824the path specified on the require line is a relative path, BitBake
672locates the first file it can find within ``BBPATH``. 825locates the first file it can find within ``BBPATH``.
673 826
@@ -678,7 +831,9 @@ include file named ``foo.inc`` that contains the common definitions
678needed to build "foo". You need to be sure ``foo.inc`` is located in the 831needed to build "foo". You need to be sure ``foo.inc`` is located in the
679same directory as your two recipe files as well. Once these conditions 832same directory as your two recipe files as well. Once these conditions
680are set up, you can share the functionality using a ``require`` 833are set up, you can share the functionality using a ``require``
681directive from within each recipe: require foo.inc 834directive from within each recipe: ::
835
836 require foo.inc
682 837
683``INHERIT`` Configuration Directive 838``INHERIT`` Configuration Directive
684----------------------------------- 839-----------------------------------
@@ -689,7 +844,10 @@ class. BitBake only supports this directive when used within a
689configuration file. 844configuration file.
690 845
691As an example, suppose you needed to inherit a class file called 846As an example, suppose you needed to inherit a class file called
692``abc.bbclass`` from a configuration file as follows: INHERIT += "abc" 847``abc.bbclass`` from a configuration file as follows: ::
848
849 INHERIT += "abc"
850
693This configuration directive causes the named class to be inherited at 851This configuration directive causes the named class to be inherited at
694the point of the directive during parsing. As with the ``inherit`` 852the point of the directive during parsing. As with the ``inherit``
695directive, the ``.bbclass`` file must be located in a "classes" 853directive, the ``.bbclass`` file must be located in a "classes"
@@ -697,18 +855,16 @@ subdirectory in one of the directories specified in ``BBPATH``.
697 855
698.. note:: 856.. note::
699 857
700 Because 858 Because .conf files are parsed first during BitBake's execution, using
701 .conf 859 INHERIT to inherit a class effectively inherits the class globally (i.e. for
702 files are parsed first during BitBake's execution, using
703 INHERIT
704 to inherit a class effectively inherits the class globally (i.e. for
705 all recipes). 860 all recipes).
706 861
707If you want to use the directive to inherit multiple classes, you can 862If you want to use the directive to inherit multiple classes, you can
708provide them on the same line in the ``local.conf`` file. Use spaces to 863provide them on the same line in the ``local.conf`` file. Use spaces to
709separate the classes. The following example shows how to inherit both 864separate the classes. The following example shows how to inherit both
710the ``autotools`` and ``pkgconfig`` classes: INHERIT += "autotools 865the ``autotools`` and ``pkgconfig`` classes: ::
711pkgconfig" 866
867 INHERIT += "autotools pkgconfig"
712 868
713Functions 869Functions
714========= 870=========
@@ -739,8 +895,13 @@ Shell Functions
739 895
740Functions written in shell script and executed either directly as 896Functions written in shell script and executed either directly as
741functions, tasks, or both. They can also be called by other shell 897functions, tasks, or both. They can also be called by other shell
742functions. Here is an example shell function definition: some_function 898functions. Here is an example shell function definition: ::
743() { echo "Hello World" } When you create these types of functions in 899
900 some_function () {
901 echo "Hello World"
902 }
903
904When you create these types of functions in
744your recipe or class files, you need to follow the shell programming 905your recipe or class files, you need to follow the shell programming
745rules. The scripts are executed by ``/bin/sh``, which may not be a bash 906rules. The scripts are executed by ``/bin/sh``, which may not be a bash
746shell but might be something such as ``dash``. You should not use 907shell but might be something such as ``dash``. You should not use
@@ -751,16 +912,36 @@ can also be applied to shell functions. Most commonly, this application
751would be used in a ``.bbappend`` file to modify functions in the main 912would be used in a ``.bbappend`` file to modify functions in the main
752recipe. It can also be used to modify functions inherited from classes. 913recipe. It can also be used to modify functions inherited from classes.
753 914
754As an example, consider the following: do_foo() { bbplain first fn } 915As an example, consider the following: ::
755fn_prepend() { bbplain second } fn() { bbplain third } do_foo_append() { 916
756bbplain fourth } Running ``do_foo`` prints the following: recipename 917 do_foo() {
757do_foo: first recipename do_foo: second recipename do_foo: third 918 bbplain first
758recipename do_foo: fourth 919 fn
920 }
921
922 fn_prepend() {
923 bbplain second
924 }
925
926 fn() {
927 bbplain third
928 }
929
930 do_foo_append() {
931 bbplain fourth
932 }
933
934Running ``do_foo`` prints the following: ::
935
936 recipename do_foo: first
937 recipename do_foo: second
938 recipename do_foo: third
939 recipename do_foo: fourth
759 940
760.. note:: 941.. note::
761 942
762 Overrides and override-style operators can be applied to any shell 943 Overrides and override-style operators can be applied to any shell
763 function, not just :ref:`tasks <bitbake-user-manual/bitbake-user-manual-metadata:Tasks>`. 944 function, not just :ref:`tasks <bitbake-user-manual/bitbake-user-manual-metadata:tasks>`.
764 945
765You can use the ``bitbake -e`` recipename command to view the final 946You can use the ``bitbake -e`` recipename command to view the final
766assembled function after all overrides have been applied. 947assembled function after all overrides have been applied.
@@ -771,33 +952,50 @@ BitBake-Style Python Functions
771These functions are written in Python and executed by BitBake or other 952These functions are written in Python and executed by BitBake or other
772Python functions using ``bb.build.exec_func()``. 953Python functions using ``bb.build.exec_func()``.
773 954
774An example BitBake function is: python some_python_function () { 955An example BitBake function is: ::
775d.setVar("TEXT", "Hello World") print d.getVar("TEXT") } Because the 956
957 python some_python_function () {
958 d.setVar("TEXT", "Hello World")
959 print d.getVar("TEXT")
960 }
961
962Because the
776Python "bb" and "os" modules are already imported, you do not need to 963Python "bb" and "os" modules are already imported, you do not need to
777import these modules. Also in these types of functions, the datastore 964import these modules. Also in these types of functions, the datastore
778("d") is a global variable and is always automatically available. 965("d") is a global variable and is always automatically available.
779 966
780.. note:: 967.. note::
781 968
782 Variable expressions (e.g. 969 Variable expressions (e.g. ``${X}`` ) are no longer expanded within Python
783 ${X} 970 functions. This behavior is intentional in order to allow you to freely set
784 ) are no longer expanded within Python functions. This behavior is 971 variable values to expandable expressions without having them expanded
785 intentional in order to allow you to freely set variable values to 972 prematurely. If you do wish to expand a variable within a Python function,
786 expandable expressions without having them expanded prematurely. If 973 use ``d.getVar("X")`` . Or, for more complicated expressions, use ``d.expand()``.
787 you do wish to expand a variable within a Python function, use
788 d.getVar("X")
789 . Or, for more complicated expressions, use
790 d.expand()
791 .
792 974
793Similar to shell functions, you can also apply overrides and 975Similar to shell functions, you can also apply overrides and
794override-style operators to BitBake-style Python functions. 976override-style operators to BitBake-style Python functions.
795 977
796As an example, consider the following: python do_foo_prepend() { 978As an example, consider the following: ::
797bb.plain("first") } python do_foo() { bb.plain("second") } python 979
798do_foo_append() { bb.plain("third") } Running ``do_foo`` prints the 980 python do_foo_prepend() {
799following: recipename do_foo: first recipename do_foo: second recipename 981 bb.plain("first")
800do_foo: third You can use the ``bitbake -e`` recipename command to view 982 }
983
984 python do_foo() {
985 bb.plain("second")
986 }
987
988 python do_foo_append() {
989 bb.plain("third")
990 }
991
992Running ``do_foo`` prints the following: ::
993
994 recipename do_foo: first
995 recipename do_foo: second
996 recipename do_foo: third
997
998You can use the ``bitbake -e`` recipename command to view
801the final assembled function after all overrides have been applied. 999the final assembled function after all overrides have been applied.
802 1000
803Python Functions 1001Python Functions
@@ -806,10 +1004,18 @@ Python Functions
806These functions are written in Python and are executed by other Python 1004These functions are written in Python and are executed by other Python
807code. Examples of Python functions are utility functions that you intend 1005code. Examples of Python functions are utility functions that you intend
808to call from in-line Python or from within other Python functions. Here 1006to call from in-line Python or from within other Python functions. Here
809is an example: def get_depends(d): if d.getVar('SOMECONDITION'): return 1007is an example: ::
810"dependencywithcond" else: return "dependency" SOMECONDITION = "1" 1008
811DEPENDS = "${@get_depends(d)}" This would result in ``DEPENDS`` 1009 def get_depends(d):
812containing ``dependencywithcond``. 1010 if d.getVar('SOMECONDITION'):
1011 return "dependencywithcond"
1012 else:
1013 return "dependency"
1014
1015 SOMECONDITION = "1"
1016 DEPENDS = "${@get_depends(d)}"
1017
1018This would result in ``DEPENDS`` containing ``dependencywithcond``.
813 1019
814Here are some things to know about Python functions: 1020Here are some things to know about Python functions:
815 1021
@@ -827,15 +1033,15 @@ BitBake-Style Python Functions Versus Python Functions
827Following are some important differences between BitBake-style Python 1033Following are some important differences between BitBake-style Python
828functions and regular Python functions defined with "def": 1034functions and regular Python functions defined with "def":
829 1035
830- Only BitBake-style Python functions can be `tasks <#tasks>`__. 1036- Only BitBake-style Python functions can be :ref:`tasks <bitbake-user-manual/bitbake-user-manual-metadata:tasks>`.
831 1037
832- Overrides and override-style operators can only be applied to 1038- Overrides and override-style operators can only be applied to
833 BitBake-style Python functions. 1039 BitBake-style Python functions.
834 1040
835- Only regular Python functions can take arguments and return values. 1041- Only regular Python functions can take arguments and return values.
836 1042
837- `Variable flags <#variable-flags>`__ such as ``[dirs]``, 1043- :ref:`Variable flags <bitbake-user-manual/bitbake-user-manual-metadata:variable flags>` such as
838 ``[cleandirs]``, and ``[lockfiles]`` can be used on BitBake-style 1044 ``[dirs]``, ``[cleandirs]``, and ``[lockfiles]`` can be used on BitBake-style
839 Python functions, but not on regular Python functions. 1045 Python functions, but not on regular Python functions.
840 1046
841- BitBake-style Python functions generate a separate 1047- BitBake-style Python functions generate a separate
@@ -850,18 +1056,17 @@ functions and regular Python functions defined with "def":
850- Regular Python functions are called with the usual Python syntax. 1056- Regular Python functions are called with the usual Python syntax.
851 BitBake-style Python functions are usually tasks and are called 1057 BitBake-style Python functions are usually tasks and are called
852 directly by BitBake, but can also be called manually from Python code 1058 directly by BitBake, but can also be called manually from Python code
853 by using the ``bb.build.exec_func()`` function. Here is an example: 1059 by using the ``bb.build.exec_func()`` function. Here is an example: ::
854 bb.build.exec_func("my_bitbake_style_function", d) 1060
1061 bb.build.exec_func("my_bitbake_style_function", d)
855 1062
856 .. note:: 1063 .. note::
857 1064
858 bb.build.exec_func() 1065 ``bb.build.exec_func()`` can also be used to run shell functions from Python
859 can also be used to run shell functions from Python code. If you 1066 code. If you want to run a shell function before a Python function within
860 want to run a shell function before a Python function within the 1067 the same task, then you can use a parent helper Python function that
861 same task, then you can use a parent helper Python function that 1068 starts by running the shell function with ``bb.build.exec_func()`` and then
862 starts by running the shell function with 1069 runs the Python code.
863 bb.build.exec_func()
864 and then runs the Python code.
865 1070
866 To detect errors from functions executed with 1071 To detect errors from functions executed with
867 ``bb.build.exec_func()``, you can catch the ``bb.build.FuncFailed`` 1072 ``bb.build.exec_func()``, you can catch the ``bb.build.FuncFailed``
@@ -869,20 +1074,12 @@ functions and regular Python functions defined with "def":
869 1074
870 .. note:: 1075 .. note::
871 1076
872 Functions in metadata (recipes and classes) should not themselves 1077 Functions in metadata (recipes and classes) should not themselves raise
873 raise 1078 ``bb.build.FuncFailed``. Rather, ``bb.build.FuncFailed`` should be viewed as a
874 bb.build.FuncFailed 1079 general indicator that the called function failed by raising an
875 . Rather, 1080 exception. For example, an exception raised by ``bb.fatal()`` will be caught
876 bb.build.FuncFailed 1081 inside ``bb.build.exec_func()``, and a ``bb.build.FuncFailed`` will be raised in
877 should be viewed as a general indicator that the called function 1082 response.
878 failed by raising an exception. For example, an exception raised
879 by
880 bb.fatal()
881 will be caught inside
882 bb.build.exec_func()
883 , and a
884 bb.build.FuncFailed
885 will be raised in response.
886 1083
887Due to their simplicity, you should prefer regular Python functions over 1084Due to their simplicity, you should prefer regular Python functions over
888BitBake-style Python functions unless you need a feature specific to 1085BitBake-style Python functions unless you need a feature specific to
@@ -897,32 +1094,62 @@ Sometimes it is useful to set variables or perform other operations
897programmatically during parsing. To do this, you can define special 1094programmatically during parsing. To do this, you can define special
898Python functions, called anonymous Python functions, that run at the end 1095Python functions, called anonymous Python functions, that run at the end
899of parsing. For example, the following conditionally sets a variable 1096of parsing. For example, the following conditionally sets a variable
900based on the value of another variable: python () { if 1097based on the value of another variable: ::
901d.getVar('SOMEVAR') == 'value': d.setVar('ANOTHERVAR', 'value2') } An 1098
902equivalent way to mark a function as an anonymous function is to give it 1099 python () {
1100 if d.getVar('SOMEVAR') == 'value':
1101 d.setVar('ANOTHERVAR', 'value2')
1102 }
1103
1104An equivalent way to mark a function as an anonymous function is to give it
903the name "__anonymous", rather than no name. 1105the name "__anonymous", rather than no name.
904 1106
905Anonymous Python functions always run at the end of parsing, regardless 1107Anonymous Python functions always run at the end of parsing, regardless
906of where they are defined. If a recipe contains many anonymous 1108of where they are defined. If a recipe contains many anonymous
907functions, they run in the same order as they are defined within the 1109functions, they run in the same order as they are defined within the
908recipe. As an example, consider the following snippet: python () { 1110recipe. As an example, consider the following snippet: ::
909d.setVar('FOO', 'foo 2') } FOO = "foo 1" python () { d.appendVar('BAR', 1111
910' bar 2') } BAR = "bar 1" The previous example is conceptually 1112 python () {
911equivalent to the following snippet: FOO = "foo 1" BAR = "bar 1" FOO = 1113 d.setVar('FOO', 'foo 2')
912"foo 2" BAR += "bar 2" ``FOO`` ends up with the value "foo 2", and 1114 }
1115
1116 FOO = "foo 1"
1117
1118 python () {
1119 d.appendVar('BAR',' bar 2')
1120 }
1121
1122 BAR = "bar 1"
1123
1124The previous example is conceptually
1125equivalent to the following snippet: ::
1126
1127 FOO = "foo 1"
1128 BAR = "bar 1"
1129 FOO = "foo 2"
1130 BAR += "bar 2"
1131
1132``FOO`` ends up with the value "foo 2", and
913``BAR`` with the value "bar 1 bar 2". Just as in the second snippet, the 1133``BAR`` with the value "bar 1 bar 2". Just as in the second snippet, the
914values set for the variables within the anonymous functions become 1134values set for the variables within the anonymous functions become
915available to tasks, which always run after parsing. 1135available to tasks, which always run after parsing.
916 1136
917Overrides and override-style operators such as "``_append``" are applied 1137Overrides and override-style operators such as "``_append``" are applied
918before anonymous functions run. In the following example, ``FOO`` ends 1138before anonymous functions run. In the following example, ``FOO`` ends
919up with the value "foo from anonymous": FOO = "foo" FOO_append = " from 1139up with the value "foo from anonymous": ::
920outside" python () { d.setVar("FOO", "foo from anonymous") } For methods 1140
921you can use with anonymous Python functions, see the "`Functions You Can 1141 FOO = "foo"
922Call From Within Python <#functions-you-can-call-from-within-python>`__" 1142 FOO_append = " from outside"
1143
1144 python () {
1145 d.setVar("FOO", "foo from anonymous")
1146 }
1147
1148For methods
1149you can use with anonymous Python functions, see the
1150":ref:`bitbake-user-manual/bitbake-user-manual-metadata:functions you can call from within python`"
923section. For a different method to run Python code during parsing, see 1151section. For a different method to run Python code during parsing, see
924the "`Inline Python Variable 1152the ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:inline python variable expansion`" section.
925Expansion <#inline-python-variable-expansion>`__" section.
926 1153
927Flexible Inheritance for Class Functions 1154Flexible Inheritance for Class Functions
928---------------------------------------- 1155----------------------------------------
@@ -946,24 +1173,43 @@ version of the function.
946 1173
947To make use of this technique, you need the following things in place: 1174To make use of this technique, you need the following things in place:
948 1175
949- The class needs to define the function as follows: 1176- The class needs to define the function as follows: ::
950 classname\ ``_``\ functionname For example, if you have a class file 1177
1178 classname_functionname
1179
1180 For example, if you have a class file
951 ``bar.bbclass`` and a function named ``do_foo``, the class must 1181 ``bar.bbclass`` and a function named ``do_foo``, the class must
952 define the function as follows: bar_do_foo 1182 define the function as follows: ::
1183
1184 bar_do_foo
953 1185
954- The class needs to contain the ``EXPORT_FUNCTIONS`` statement as 1186- The class needs to contain the ``EXPORT_FUNCTIONS`` statement as
955 follows: EXPORT_FUNCTIONS functionname For example, continuing with 1187 follows: ::
1188
1189 EXPORT_FUNCTIONS functionname
1190
1191 For example, continuing with
956 the same example, the statement in the ``bar.bbclass`` would be as 1192 the same example, the statement in the ``bar.bbclass`` would be as
957 follows: EXPORT_FUNCTIONS do_foo 1193 follows: ::
1194
1195 EXPORT_FUNCTIONS do_foo
958 1196
959- You need to call the function appropriately from within your recipe. 1197- You need to call the function appropriately from within your recipe.
960 Continuing with the same example, if your recipe needs to call the 1198 Continuing with the same example, if your recipe needs to call the
961 class version of the function, it should call ``bar_do_foo``. 1199 class version of the function, it should call ``bar_do_foo``.
962 Assuming ``do_foo`` was a shell function and ``EXPORT_FUNCTIONS`` was 1200 Assuming ``do_foo`` was a shell function and ``EXPORT_FUNCTIONS`` was
963 used as above, the recipe's function could conditionally call the 1201 used as above, the recipe's function could conditionally call the
964 class version of the function as follows: do_foo() { if [ 1202 class version of the function as follows: ::
965 somecondition ] ; then bar_do_foo else # Do something else fi } To 1203
966 call your modified version of the function as defined in your recipe, 1204 do_foo() {
1205 if [ somecondition ] ; then
1206 bar_do_foo
1207 else
1208 # Do something else
1209 fi
1210 }
1211
1212 To call your modified version of the function as defined in your recipe,
967 call it as ``do_foo``. 1213 call it as ``do_foo``.
968 1214
969With these conditions met, your single recipe can freely choose between 1215With these conditions met, your single recipe can freely choose between
@@ -982,14 +1228,20 @@ classes (i.e. in ``.bb`` files and files included or inherited from
982Promoting a Function to a Task 1228Promoting a Function to a Task
983------------------------------ 1229------------------------------
984 1230
985Tasks are either `shell functions <#shell-functions>`__ or 1231Tasks are either :ref:`shell functions <bitbake-user-manual/bitbake-user-manual-metadata:shell functions>` or
986`BitBake-style Python functions <#bitbake-style-python-functions>`__ 1232:ref:`BitBake-style Python functions <bitbake-user-manual/bitbake-user-manual-metadata:bitbake-style python functions>`
987that have been promoted to tasks by using the ``addtask`` command. The 1233that have been promoted to tasks by using the ``addtask`` command. The
988``addtask`` command can also optionally describe dependencies between 1234``addtask`` command can also optionally describe dependencies between
989the task and other tasks. Here is an example that shows how to define a 1235the task and other tasks. Here is an example that shows how to define a
990task and declare some dependencies: python do_printdate () { import time 1236task and declare some dependencies: ::
991print time.strftime('%Y%m%d', time.gmtime()) } addtask printdate after 1237
992do_fetch before do_build The first argument to ``addtask`` is the name 1238 python do_printdate () {
1239 import time
1240 print time.strftime('%Y%m%d', time.gmtime())
1241 }
1242 addtask printdate after do_fetch before do_build
1243
1244The first argument to ``addtask`` is the name
993of the function to promote to a task. If the name does not start with 1245of the function to promote to a task. If the name does not start with
994"do\_", "do\_" is implicitly added, which enforces the convention that all 1246"do\_", "do\_" is implicitly added, which enforces the convention that all
995task names start with "do\_". 1247task names start with "do\_".
@@ -1004,49 +1256,44 @@ Additionally, the ``do_printdate`` task becomes dependent upon the
1004.. note:: 1256.. note::
1005 1257
1006 If you try out the previous example, you might see that the 1258 If you try out the previous example, you might see that the
1007 do_printdate 1259 ``do_printdate``
1008 task is only run the first time you build the recipe with the 1260 task is only run the first time you build the recipe with the
1009 bitbake 1261 ``bitbake``
1010 command. This is because BitBake considers the task "up-to-date" 1262 command. This is because BitBake considers the task "up-to-date"
1011 after that initial run. If you want to force the task to always be 1263 after that initial run. If you want to force the task to always be
1012 rerun for experimentation purposes, you can make BitBake always 1264 rerun for experimentation purposes, you can make BitBake always
1013 consider the task "out-of-date" by using the 1265 consider the task "out-of-date" by using the
1014 :ref:`[nostamp] <bitbake-user-manual/bitbake-user-manual-metadata:Variable Flags>` 1266 :ref:`[nostamp] <bitbake-user-manual/bitbake-user-manual-metadata:Variable Flags>`
1015 variable flag, as follows: 1267 variable flag, as follows: ::
1016 ::
1017 1268
1018 do_printdate[nostamp] = "1" 1269 do_printdate[nostamp] = "1"
1019
1020 1270
1021 You can also explicitly run the task and provide the 1271 You can also explicitly run the task and provide the
1022 -f 1272 -f option as follows: ::
1023 option as follows: 1273
1024 :: 1274 $ bitbake recipe -c printdate -f
1025 1275
1026 $ bitbake recipe -c printdate -f 1276 When manually selecting a task to run with the bitbake ``recipe
1027 1277 -c task`` command, you can omit the "do\_" prefix as part of the task
1028 1278 name.
1029 When manually selecting a task to run with the
1030 bitbake
1031 NBSP
1032 recipe
1033 NBSP
1034 -c
1035 NBSP
1036 task
1037 command, you can omit the "do\_" prefix as part of the task name.
1038 1279
1039You might wonder about the practical effects of using ``addtask`` 1280You might wonder about the practical effects of using ``addtask``
1040without specifying any dependencies as is done in the following example: 1281without specifying any dependencies as is done in the following example: ::
1041addtask printdate In this example, assuming dependencies have not been 1282
1283 addtask printdate
1284
1285In this example, assuming dependencies have not been
1042added through some other means, the only way to run the task is by 1286added through some other means, the only way to run the task is by
1043explicitly selecting it with ``bitbake`` recipe ``-c printdate``. You 1287explicitly selecting it with ``bitbake`` recipe ``-c printdate``. You
1044can use the ``do_listtasks`` task to list all tasks defined in a recipe 1288can use the ``do_listtasks`` task to list all tasks defined in a recipe
1045as shown in the following example: $ bitbake recipe -c listtasks For 1289as shown in the following example: ::
1046more information on task dependencies, see the
1047"`Dependencies <#dependencies>`__" section.
1048 1290
1049See the "`Variable Flags <#variable-flags>`__" section for information 1291 $ bitbake recipe -c listtasks
1292
1293For more information on task dependencies, see the
1294":ref:`bitbake-user-manual/bitbake-user-manual-execution:dependencies`" section.
1295
1296See the ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:variable flags`" section for information
1050on variable flags you can use with tasks. 1297on variable flags you can use with tasks.
1051 1298
1052Deleting a Task 1299Deleting a Task
@@ -1054,8 +1301,11 @@ Deleting a Task
1054 1301
1055As well as being able to add tasks, you can delete them. Simply use the 1302As well as being able to add tasks, you can delete them. Simply use the
1056``deltask`` command to delete a task. For example, to delete the example 1303``deltask`` command to delete a task. For example, to delete the example
1057task used in the previous sections, you would use: deltask printdate If 1304task used in the previous sections, you would use: ::
1058you delete a task using the ``deltask`` command and the task has 1305
1306 deltask printdate
1307
1308If you delete a task using the ``deltask`` command and the task has
1059dependencies, the dependencies are not reconnected. For example, suppose 1309dependencies, the dependencies are not reconnected. For example, suppose
1060you have three tasks named ``do_a``, ``do_b``, and ``do_c``. 1310you have three tasks named ``do_a``, ``do_b``, and ``do_c``.
1061Furthermore, ``do_c`` is dependent on ``do_b``, which in turn is 1311Furthermore, ``do_c`` is dependent on ``do_b``, which in turn is
@@ -1067,7 +1317,9 @@ to run before ``do_a``.
1067 1317
1068If you want dependencies such as these to remain intact, use the 1318If you want dependencies such as these to remain intact, use the
1069``[noexec]`` varflag to disable the task instead of using the 1319``[noexec]`` varflag to disable the task instead of using the
1070``deltask`` command to delete it: do_b[noexec] = "1" 1320``deltask`` command to delete it: ::
1321
1322 do_b[noexec] = "1"
1071 1323
1072Passing Information Into the Build Task Environment 1324Passing Information Into the Build Task Environment
1073--------------------------------------------------- 1325---------------------------------------------------
@@ -1081,30 +1333,31 @@ the build machine cannot influence the build.
1081 By default, BitBake cleans the environment to include only those 1333 By default, BitBake cleans the environment to include only those
1082 things exported or listed in its whitelist to ensure that the build 1334 things exported or listed in its whitelist to ensure that the build
1083 environment is reproducible and consistent. You can prevent this 1335 environment is reproducible and consistent. You can prevent this
1084 "cleaning" by setting the 1336 "cleaning" by setting the :term:`BB_PRESERVE_ENV` variable.
1085 :term:`BB_PRESERVE_ENV`
1086 variable.
1087 1337
1088Consequently, if you do want something to get passed into the build task 1338Consequently, if you do want something to get passed into the build task
1089environment, you must take these two steps: 1339environment, you must take these two steps:
1090 1340
10911. Tell BitBake to load what you want from the environment into the 1341#. Tell BitBake to load what you want from the environment into the
1092 datastore. You can do so through the 1342 datastore. You can do so through the
1093 :term:`BB_ENV_WHITELIST` and 1343 :term:`BB_ENV_WHITELIST` and
1094 :term:`BB_ENV_EXTRAWHITE` variables. For 1344 :term:`BB_ENV_EXTRAWHITE` variables. For
1095 example, assume you want to prevent the build system from accessing 1345 example, assume you want to prevent the build system from accessing
1096 your ``$HOME/.ccache`` directory. The following command "whitelists" 1346 your ``$HOME/.ccache`` directory. The following command "whitelists"
1097 the environment variable ``CCACHE_DIR`` causing BitBake to allow that 1347 the environment variable ``CCACHE_DIR`` causing BitBake to allow that
1098 variable into the datastore: export 1348 variable into the datastore: ::
1099 BB_ENV_EXTRAWHITE="$BB_ENV_EXTRAWHITE CCACHE_DIR" 1349
1350 export BB_ENV_EXTRAWHITE="$BB_ENV_EXTRAWHITE CCACHE_DIR"
1100 1351
11012. Tell BitBake to export what you have loaded into the datastore to the 1352#. Tell BitBake to export what you have loaded into the datastore to the
1102 task environment of every running task. Loading something from the 1353 task environment of every running task. Loading something from the
1103 environment into the datastore (previous step) only makes it 1354 environment into the datastore (previous step) only makes it
1104 available in the datastore. To export it to the task environment of 1355 available in the datastore. To export it to the task environment of
1105 every running task, use a command similar to the following in your 1356 every running task, use a command similar to the following in your
1106 local configuration file ``local.conf`` or your distribution 1357 local configuration file ``local.conf`` or your distribution
1107 configuration file: export CCACHE_DIR 1358 configuration file: ::
1359
1360 export CCACHE_DIR
1108 1361
1109 .. note:: 1362 .. note::
1110 1363
@@ -1116,15 +1369,17 @@ environment, you must take these two steps:
1116 1369
1117Sometimes, it is useful to be able to obtain information from the 1370Sometimes, it is useful to be able to obtain information from the
1118original execution environment. BitBake saves a copy of the original 1371original execution environment. BitBake saves a copy of the original
1119environment into a special variable named 1372environment into a special variable named :term:`BB_ORIGENV`.
1120:term:`BB_ORIGENV`.
1121 1373
1122The ``BB_ORIGENV`` variable returns a datastore object that can be 1374The ``BB_ORIGENV`` variable returns a datastore object that can be
1123queried using the standard datastore operators such as 1375queried using the standard datastore operators such as
1124``getVar(, False)``. The datastore object is useful, for example, to 1376``getVar(, False)``. The datastore object is useful, for example, to
1125find the original ``DISPLAY`` variable. Here is an example: origenv = 1377find the original ``DISPLAY`` variable. Here is an example: ::
1126d.getVar("BB_ORIGENV", False) bar = origenv.getVar("BAR", False) The 1378
1127previous example returns ``BAR`` from the original execution 1379 origenv = d.getVar("BB_ORIGENV", False)
1380 bar = origenv.getVar("BAR", False)
1381
1382The previous example returns ``BAR`` from the original execution
1128environment. 1383environment.
1129 1384
1130Variable Flags 1385Variable Flags
@@ -1132,71 +1387,70 @@ Variable Flags
1132 1387
1133Variable flags (varflags) help control a task's functionality and 1388Variable flags (varflags) help control a task's functionality and
1134dependencies. BitBake reads and writes varflags to the datastore using 1389dependencies. BitBake reads and writes varflags to the datastore using
1135the following command forms: variable = d.getVarFlags("variable") 1390the following command forms: ::
1136self.d.setVarFlags("FOO", {"func": True}) 1391
1392 variable = d.getVarFlags("variable")
1393 self.d.setVarFlags("FOO", {"func": True})
1137 1394
1138When working with varflags, the same syntax, with the exception of 1395When working with varflags, the same syntax, with the exception of
1139overrides, applies. In other words, you can set, append, and prepend 1396overrides, applies. In other words, you can set, append, and prepend
1140varflags just like variables. See the "`Variable Flag 1397varflags just like variables. See the
1141Syntax <#variable-flag-syntax>`__" section for details. 1398":ref:`bitbake-user-manual/bitbake-user-manual-metadata:variable flag syntax`" section for details.
1142 1399
1143BitBake has a defined set of varflags available for recipes and classes. 1400BitBake has a defined set of varflags available for recipes and classes.
1144Tasks support a number of these flags which control various 1401Tasks support a number of these flags which control various
1145functionality of the task: 1402functionality of the task:
1146 1403
1147- *``[cleandirs]``:* Empty directories that should be created before 1404- ``[cleandirs]``: Empty directories that should be created before
1148 the task runs. Directories that already exist are removed and 1405 the task runs. Directories that already exist are removed and
1149 recreated to empty them. 1406 recreated to empty them.
1150 1407
1151- *``[depends]``:* Controls inter-task dependencies. See the 1408- ``[depends]``: Controls inter-task dependencies. See the
1152 :term:`DEPENDS` variable and the "`Inter-Task 1409 :term:`DEPENDS` variable and the
1153 Dependencies <#inter-task-dependencies>`__" section for more 1410 ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:inter-task
1154 information. 1411 dependencies`" section for more information.
1155 1412
1156- *``[deptask]``:* Controls task build-time dependencies. See the 1413- ``[deptask]``: Controls task build-time dependencies. See the
1157 :term:`DEPENDS` variable and the "`Build 1414 :term:`DEPENDS` variable and the ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:build dependencies`" section for more information.
1158 Dependencies <#build-dependencies>`__" section for more information.
1159 1415
1160- *``[dirs]``:* Directories that should be created before the task 1416- ``[dirs]``: Directories that should be created before the task
1161 runs. Directories that already exist are left as is. The last 1417 runs. Directories that already exist are left as is. The last
1162 directory listed is used as the current working directory for the 1418 directory listed is used as the current working directory for the
1163 task. 1419 task.
1164 1420
1165- *``[lockfiles]``:* Specifies one or more lockfiles to lock while the 1421- ``[lockfiles]``: Specifies one or more lockfiles to lock while the
1166 task executes. Only one task may hold a lockfile, and any task that 1422 task executes. Only one task may hold a lockfile, and any task that
1167 attempts to lock an already locked file will block until the lock is 1423 attempts to lock an already locked file will block until the lock is
1168 released. You can use this variable flag to accomplish mutual 1424 released. You can use this variable flag to accomplish mutual
1169 exclusion. 1425 exclusion.
1170 1426
1171- *``[noexec]``:* When set to "1", marks the task as being empty, with 1427- ``[noexec]``: When set to "1", marks the task as being empty, with
1172 no execution required. You can use the ``[noexec]`` flag to set up 1428 no execution required. You can use the ``[noexec]`` flag to set up
1173 tasks as dependency placeholders, or to disable tasks defined 1429 tasks as dependency placeholders, or to disable tasks defined
1174 elsewhere that are not needed in a particular recipe. 1430 elsewhere that are not needed in a particular recipe.
1175 1431
1176- *``[nostamp]``:* When set to "1", tells BitBake to not generate a 1432- ``[nostamp]``: When set to "1", tells BitBake to not generate a
1177 stamp file for a task, which implies the task should always be 1433 stamp file for a task, which implies the task should always be
1178 executed. 1434 executed.
1179 1435
1180 .. note:: 1436 .. caution::
1181 1437
1182 Any task that depends (possibly indirectly) on a 1438 Any task that depends (possibly indirectly) on a ``[nostamp]`` task will
1183 [nostamp] 1439 always be executed as well. This can cause unnecessary rebuilding if you
1184 task will always be executed as well. This can cause unnecessary 1440 are not careful.
1185 rebuilding if you are not careful.
1186 1441
1187- *``[number_threads]``:* Limits tasks to a specific number of 1442- ``[number_threads]``: Limits tasks to a specific number of
1188 simultaneous threads during execution. This varflag is useful when 1443 simultaneous threads during execution. This varflag is useful when
1189 your build host has a large number of cores but certain tasks need to 1444 your build host has a large number of cores but certain tasks need to
1190 be rate-limited due to various kinds of resource constraints (e.g. to 1445 be rate-limited due to various kinds of resource constraints (e.g. to
1191 avoid network throttling). ``number_threads`` works similarly to the 1446 avoid network throttling). ``number_threads`` works similarly to the
1192 :term:`BB_NUMBER_THREADS` variable but is 1447 :term:`BB_NUMBER_THREADS` variable but is task-specific.
1193 task-specific.
1194 1448
1195 Set the value globally. For example, the following makes sure the 1449 Set the value globally. For example, the following makes sure the
1196 ``do_fetch`` task uses no more than two simultaneous execution 1450 ``do_fetch`` task uses no more than two simultaneous execution
1197 threads: do_fetch[number_threads] = "2" 1451 threads: do_fetch[number_threads] = "2"
1198 1452
1199 .. note:: 1453 .. warning::
1200 1454
1201 - Setting the varflag in individual recipes rather than globally 1455 - Setting the varflag in individual recipes rather than globally
1202 can result in unpredictable behavior. 1456 can result in unpredictable behavior.
@@ -1205,59 +1459,59 @@ functionality of the task:
1205 the ``BB_NUMBER_THREADS`` variable causes ``number_threads`` to 1459 the ``BB_NUMBER_THREADS`` variable causes ``number_threads`` to
1206 have no effect. 1460 have no effect.
1207 1461
1208- *``[postfuncs]``:* List of functions to call after the completion of 1462- ``[postfuncs]``: List of functions to call after the completion of
1209 the task. 1463 the task.
1210 1464
1211- *``[prefuncs]``:* List of functions to call before the task executes. 1465- ``[prefuncs]``: List of functions to call before the task executes.
1212 1466
1213- *``[rdepends]``:* Controls inter-task runtime dependencies. See the 1467- ``[rdepends]``: Controls inter-task runtime dependencies. See the
1214 :term:`RDEPENDS` variable, the 1468 :term:`RDEPENDS` variable, the
1215 :term:`RRECOMMENDS` variable, and the 1469 :term:`RRECOMMENDS` variable, and the
1216 "`Inter-Task Dependencies <#inter-task-dependencies>`__" section for 1470 ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:inter-task dependencies`" section for
1217 more information. 1471 more information.
1218 1472
1219- *``[rdeptask]``:* Controls task runtime dependencies. See the 1473- ``[rdeptask]``: Controls task runtime dependencies. See the
1220 :term:`RDEPENDS` variable, the 1474 :term:`RDEPENDS` variable, the
1221 :term:`RRECOMMENDS` variable, and the "`Runtime 1475 :term:`RRECOMMENDS` variable, and the
1222 Dependencies <#runtime-dependencies>`__" section for more 1476 ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:runtime dependencies`" section for more
1223 information. 1477 information.
1224 1478
1225- *``[recideptask]``:* When set in conjunction with ``recrdeptask``, 1479- ``[recideptask]``: When set in conjunction with ``recrdeptask``,
1226 specifies a task that should be inspected for additional 1480 specifies a task that should be inspected for additional
1227 dependencies. 1481 dependencies.
1228 1482
1229- *``[recrdeptask]``:* Controls task recursive runtime dependencies. 1483- ``[recrdeptask]``: Controls task recursive runtime dependencies.
1230 See the :term:`RDEPENDS` variable, the 1484 See the :term:`RDEPENDS` variable, the
1231 :term:`RRECOMMENDS` variable, and the 1485 :term:`RRECOMMENDS` variable, and the
1232 "`Recursive Dependencies <#recursive-dependencies>`__" section for 1486 ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:recursive dependencies`" section for
1233 more information. 1487 more information.
1234 1488
1235- *``[stamp-extra-info]``:* Extra stamp information to append to the 1489- ``[stamp-extra-info]``: Extra stamp information to append to the
1236 task's stamp. As an example, OpenEmbedded uses this flag to allow 1490 task's stamp. As an example, OpenEmbedded uses this flag to allow
1237 machine-specific tasks. 1491 machine-specific tasks.
1238 1492
1239- *``[umask]``:* The umask to run the task under. 1493- ``[umask]``: The umask to run the task under.
1240 1494
1241Several varflags are useful for controlling how signatures are 1495Several varflags are useful for controlling how signatures are
1242calculated for variables. For more information on this process, see the 1496calculated for variables. For more information on this process, see the
1243"`Checksums (Signatures) <#checksums>`__" section. 1497":ref:`bitbake-user-manual/bitbake-user-manual-execution:checksums (signatures)`" section.
1244 1498
1245- *``[vardeps]``:* Specifies a space-separated list of additional 1499- ``[vardeps]``: Specifies a space-separated list of additional
1246 variables to add to a variable's dependencies for the purposes of 1500 variables to add to a variable's dependencies for the purposes of
1247 calculating its signature. Adding variables to this list is useful, 1501 calculating its signature. Adding variables to this list is useful,
1248 for example, when a function refers to a variable in a manner that 1502 for example, when a function refers to a variable in a manner that
1249 does not allow BitBake to automatically determine that the variable 1503 does not allow BitBake to automatically determine that the variable
1250 is referred to. 1504 is referred to.
1251 1505
1252- *``[vardepsexclude]``:* Specifies a space-separated list of variables 1506- ``[vardepsexclude]``: Specifies a space-separated list of variables
1253 that should be excluded from a variable's dependencies for the 1507 that should be excluded from a variable's dependencies for the
1254 purposes of calculating its signature. 1508 purposes of calculating its signature.
1255 1509
1256- *``[vardepvalue]``:* If set, instructs BitBake to ignore the actual 1510- ``[vardepvalue]``: If set, instructs BitBake to ignore the actual
1257 value of the variable and instead use the specified value when 1511 value of the variable and instead use the specified value when
1258 calculating the variable's signature. 1512 calculating the variable's signature.
1259 1513
1260- *``[vardepvalueexclude]``:* Specifies a pipe-separated list of 1514- ``[vardepvalueexclude]``: Specifies a pipe-separated list of
1261 strings to exclude from the variable's value when calculating the 1515 strings to exclude from the variable's value when calculating the
1262 variable's signature. 1516 variable's signature.
1263 1517
@@ -1272,12 +1526,18 @@ intent is to make it easy to do things like email notification on build
1272failures. 1526failures.
1273 1527
1274Following is an example event handler that prints the name of the event 1528Following is an example event handler that prints the name of the event
1275and the content of the ``FILE`` variable: addhandler 1529and the content of the ``FILE`` variable: ::
1276myclass_eventhandler python myclass_eventhandler() { from bb.event 1530
1277import getName print("The name of the Event is %s" % getName(e)) 1531 addhandler myclass_eventhandler
1278print("The file we run for is %s" % d.getVar('FILE')) } 1532 python myclass_eventhandler() {
1279myclass_eventhandler[eventmask] = "bb.event.BuildStarted 1533 from bb.event import getName
1280bb.event.BuildCompleted" In the previous example, an eventmask has been 1534 print("The name of the Event is %s" % getName(e))
1535 print("The file we run for is %s" % d.getVar('FILE'))
1536 }
1537 myclass_eventhandler[eventmask] = "bb.event.BuildStarted
1538 bb.event.BuildCompleted"
1539
1540In the previous example, an eventmask has been
1281set so that the handler only sees the "BuildStarted" and 1541set so that the handler only sees the "BuildStarted" and
1282"BuildCompleted" events. This event handler gets called every time an 1542"BuildCompleted" events. This event handler gets called every time an
1283event matching the eventmask is triggered. A global variable "e" is 1543event matching the eventmask is triggered. A global variable "e" is
@@ -1365,21 +1625,13 @@ information from the BitBake server to other parts of BitBake such as
1365user interfaces: 1625user interfaces:
1366 1626
1367- ``bb.event.TreeDataPreparationStarted()`` 1627- ``bb.event.TreeDataPreparationStarted()``
1368
1369- ``bb.event.TreeDataPreparationProgress()`` 1628- ``bb.event.TreeDataPreparationProgress()``
1370
1371- ``bb.event.TreeDataPreparationCompleted()`` 1629- ``bb.event.TreeDataPreparationCompleted()``
1372
1373- ``bb.event.DepTreeGenerated()`` 1630- ``bb.event.DepTreeGenerated()``
1374
1375- ``bb.event.CoreBaseFilesFound()`` 1631- ``bb.event.CoreBaseFilesFound()``
1376
1377- ``bb.event.ConfigFilePathFound()`` 1632- ``bb.event.ConfigFilePathFound()``
1378
1379- ``bb.event.FilesMatchingFound()`` 1633- ``bb.event.FilesMatchingFound()``
1380
1381- ``bb.event.ConfigFilesFound()`` 1634- ``bb.event.ConfigFilesFound()``
1382
1383- ``bb.event.TargetsTreeGenerated()`` 1635- ``bb.event.TargetsTreeGenerated()``
1384 1636
1385.. _variants-class-extension-mechanism: 1637.. _variants-class-extension-mechanism:
@@ -1390,49 +1642,43 @@ Variants - Class Extension Mechanism
1390BitBake supports two features that facilitate creating from a single 1642BitBake supports two features that facilitate creating from a single
1391recipe file multiple incarnations of that recipe file where all 1643recipe file multiple incarnations of that recipe file where all
1392incarnations are buildable. These features are enabled through the 1644incarnations are buildable. These features are enabled through the
1393:term:`BBCLASSEXTEND` and 1645:term:`BBCLASSEXTEND` and :term:`BBVERSIONS` variables.
1394:term:`BBVERSIONS` variables.
1395 1646
1396.. note:: 1647.. note::
1397 1648
1398 The mechanism for this class extension is extremely specific to the 1649 The mechanism for this class extension is extremely specific to the
1399 implementation. Usually, the recipe's 1650 implementation. Usually, the recipe's :term:`PROVIDES` , :term:`PN` , and
1400 :term:`PROVIDES` 1651 :term:`DEPENDS` variables would need to be modified by the extension
1401 , 1652 class. For specific examples, see the OE-Core native , nativesdk , and
1402 :term:`PN` 1653 multilib classes.
1403 , and 1654
1404 :term:`DEPENDS` 1655- ``BBCLASSEXTEND``: This variable is a space separated list of
1405 variables would need to be modified by the extension class. For
1406 specific examples, see the OE-Core
1407 native
1408 ,
1409 nativesdk
1410 , and
1411 multilib
1412 classes.
1413
1414- *``BBCLASSEXTEND``:* This variable is a space separated list of
1415 classes used to "extend" the recipe for each variant. Here is an 1656 classes used to "extend" the recipe for each variant. Here is an
1416 example that results in a second incarnation of the current recipe 1657 example that results in a second incarnation of the current recipe
1417 being available. This second incarnation will have the "native" class 1658 being available. This second incarnation will have the "native" class
1418 inherited. BBCLASSEXTEND = "native" 1659 inherited. ::
1660
1661 BBCLASSEXTEND = "native"
1419 1662
1420- *``BBVERSIONS``:* This variable allows a single recipe to build 1663- ``BBVERSIONS``: This variable allows a single recipe to build
1421 multiple versions of a project from a single recipe file. You can 1664 multiple versions of a project from a single recipe file. You can
1422 also specify conditional metadata (using the 1665 also specify conditional metadata (using the
1423 :term:`OVERRIDES` mechanism) for a single 1666 :term:`OVERRIDES` mechanism) for a single
1424 version, or an optionally named range of versions. Here is an 1667 version, or an optionally named range of versions. Here is an
1425 example: BBVERSIONS = "1.0 2.0 git" SRC_URI_git = 1668 example: ::
1426 "git://someurl/somepath.git" BBVERSIONS = "1.0.[0-6]:1.0.0+ \\ 1669
1427 1.0.[7-9]:1.0.7+" SRC_URI_append_1.0.7+ = 1670 BBVERSIONS = "1.0 2.0 git"
1428 "file://some_patch_which_the_new_versions_need.patch;patch=1" The 1671 SRC_URI_git = "git://someurl/somepath.git"
1429 name of the range defaults to the original version of the recipe. For 1672
1430 example, in OpenEmbedded, the recipe file ``foo_1.0.0+.bb`` creates a 1673 BBVERSIONS = "1.0.[0-6]:1.0.0+ 1.0.[7-9]:1.0.7+"
1431 default name range of ``1.0.0+``. This is useful because the range 1674 SRC_URI_append_1.0.7+ = "file://some_patch_which_the_new_versions_need.patch;patch=1"
1432 name is not only placed into overrides, but it is also made available 1675
1433 for the metadata to use in the variable that defines the base recipe 1676 The name of the range defaults to the original version of the recipe. For
1434 versions for use in ``file://`` search paths 1677 example, in OpenEmbedded, the recipe file ``foo_1.0.0+.bb`` creates a default
1435 (:term:`FILESPATH`). 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`).
1436 1682
1437Dependencies 1683Dependencies
1438============ 1684============
@@ -1462,8 +1708,11 @@ Dependencies Internal to the ``.bb`` File
1462BitBake uses the ``addtask`` directive to manage dependencies that are 1708BitBake uses the ``addtask`` directive to manage dependencies that are
1463internal to a given recipe file. You can use the ``addtask`` directive 1709internal to a given recipe file. You can use the ``addtask`` directive
1464to indicate when a task is dependent on other tasks or when other tasks 1710to indicate when a task is dependent on other tasks or when other tasks
1465depend on that recipe. Here is an example: addtask printdate after 1711depend on that recipe. Here is an example: ::
1466do_fetch before do_build In this example, the ``do_printdate`` task 1712
1713 addtask printdate after do_fetch before do_build
1714
1715In this example, the ``do_printdate`` task
1467depends on the completion of the ``do_fetch`` task, and the ``do_build`` 1716depends on the completion of the ``do_fetch`` task, and the ``do_build``
1468task depends on the completion of the ``do_printdate`` task. 1717task depends on the completion of the ``do_printdate`` task.
1469 1718
@@ -1476,16 +1725,19 @@ task depends on the completion of the ``do_printdate`` task.
1476 1725
1477 - The directive ``addtask mytask before do_configure`` causes 1726 - The directive ``addtask mytask before do_configure`` causes
1478 ``do_mytask`` to run before ``do_configure`` runs. Be aware that 1727 ``do_mytask`` to run before ``do_configure`` runs. Be aware that
1479 ``do_mytask`` still only runs if its `input 1728 ``do_mytask`` still only runs if its :ref:`input
1480 checksum <#checksums>`__ has changed since the last time it was 1729 checksum <bitbake-user-manual/bitbake-user-manual-execution:checksums (signatures)>` has changed since the last time it was
1481 run. Changes to the input checksum of ``do_mytask`` also 1730 run. Changes to the input checksum of ``do_mytask`` also
1482 indirectly cause ``do_configure`` to run. 1731 indirectly cause ``do_configure`` to run.
1483 1732
1484 - The directive ``addtask mytask after do_configure`` by itself 1733 - The directive ``addtask mytask after do_configure`` by itself
1485 never causes ``do_mytask`` to run. ``do_mytask`` can still be run 1734 never causes ``do_mytask`` to run. ``do_mytask`` can still be run
1486 manually as follows: $ bitbake recipe -c mytask Declaring 1735 manually as follows: ::
1487 ``do_mytask`` as a dependency of some other task that is scheduled 1736
1488 to run also causes it to run. Regardless, the task runs after 1737 $ bitbake recipe -c mytask
1738
1739 Declaring ``do_mytask`` as a dependency of some other task that is
1740 scheduled to run also causes it to run. Regardless, the task runs after
1489 ``do_configure``. 1741 ``do_configure``.
1490 1742
1491Build Dependencies 1743Build Dependencies
@@ -1494,24 +1746,29 @@ Build Dependencies
1494BitBake uses the :term:`DEPENDS` variable to manage 1746BitBake uses the :term:`DEPENDS` variable to manage
1495build time dependencies. The ``[deptask]`` varflag for tasks signifies 1747build time dependencies. The ``[deptask]`` varflag for tasks signifies
1496the task of each item listed in ``DEPENDS`` that must complete before 1748the task of each item listed in ``DEPENDS`` that must complete before
1497that task can be executed. Here is an example: do_configure[deptask] = 1749that task can be executed. Here is an example: ::
1498"do_populate_sysroot" In this example, the ``do_populate_sysroot`` task 1750
1751 do_configure[deptask] = "do_populate_sysroot"
1752
1753In this example, the ``do_populate_sysroot`` task
1499of each item in ``DEPENDS`` must complete before ``do_configure`` can 1754of each item in ``DEPENDS`` must complete before ``do_configure`` can
1500execute. 1755execute.
1501 1756
1502Runtime Dependencies 1757Runtime Dependencies
1503-------------------- 1758--------------------
1504 1759
1505BitBake uses the :term:`PACKAGES`, 1760BitBake uses the :term:`PACKAGES`, :term:`RDEPENDS`, and :term:`RRECOMMENDS`
1506:term:`RDEPENDS`, and 1761variables to manage runtime dependencies.
1507:term:`RRECOMMENDS` variables to manage runtime
1508dependencies.
1509 1762
1510The ``PACKAGES`` variable lists runtime packages. Each of those packages 1763The ``PACKAGES`` variable lists runtime packages. Each of those packages
1511can have ``RDEPENDS`` and ``RRECOMMENDS`` runtime dependencies. The 1764can have ``RDEPENDS`` and ``RRECOMMENDS`` runtime dependencies. The
1512``[rdeptask]`` flag for tasks is used to signify the task of each item 1765``[rdeptask]`` flag for tasks is used to signify the task of each item
1513runtime dependency which must have completed before that task can be 1766runtime dependency which must have completed before that task can be
1514executed. do_package_qa[rdeptask] = "do_packagedata" In the previous 1767executed. ::
1768
1769 do_package_qa[rdeptask] = "do_packagedata"
1770
1771In the previous
1515example, the ``do_packagedata`` task of each item in ``RDEPENDS`` must 1772example, the ``do_packagedata`` task of each item in ``RDEPENDS`` must
1516have completed before ``do_package_qa`` can execute. 1773have completed before ``do_package_qa`` can execute.
1517Although ``RDEPENDS`` contains entries from the 1774Although ``RDEPENDS`` contains entries from the
@@ -1531,14 +1788,18 @@ dependencies are discovered and added.
1531 1788
1532The ``[recrdeptask]`` flag is most commonly used in high-level recipes 1789The ``[recrdeptask]`` flag is most commonly used in high-level recipes
1533that need to wait for some task to finish "globally". For example, 1790that need to wait for some task to finish "globally". For example,
1534``image.bbclass`` has the following: do_rootfs[recrdeptask] += 1791``image.bbclass`` has the following: ::
1535"do_packagedata" This statement says that the ``do_packagedata`` task of 1792
1793 do_rootfs[recrdeptask] += "do_packagedata"
1794
1795This statement says that the ``do_packagedata`` task of
1536the current recipe and all recipes reachable (by way of dependencies) 1796the current recipe and all recipes reachable (by way of dependencies)
1537from the image recipe must run before the ``do_rootfs`` task can run. 1797from the image recipe must run before the ``do_rootfs`` task can run.
1538 1798
1539BitBake allows a task to recursively depend on itself by 1799BitBake allows a task to recursively depend on itself by
1540referencing itself in the task list: 1800referencing itself in the task list: ::
1541do_a[recrdeptask] = "do_a do_b" 1801
1802 do_a[recrdeptask] = "do_a do_b"
1542 1803
1543In the same way as before, this means that the ``do_a`` 1804In the same way as before, this means that the ``do_a``
1544and ``do_b`` tasks of the current recipe and all 1805and ``do_b`` tasks of the current recipe and all
@@ -1553,10 +1814,12 @@ Inter-Task Dependencies
1553BitBake uses the ``[depends]`` flag in a more generic form to manage 1814BitBake uses the ``[depends]`` flag in a more generic form to manage
1554inter-task dependencies. This more generic form allows for 1815inter-task dependencies. This more generic form allows for
1555inter-dependency checks for specific tasks rather than checks for the 1816inter-dependency checks for specific tasks rather than checks for the
1556data in ``DEPENDS``. Here is an example: do_patch[depends] = 1817data in ``DEPENDS``. Here is an example: ::
1557"quilt-native:do_populate_sysroot" In this example, the 1818
1558``do_populate_sysroot`` task of the target ``quilt-native`` must have 1819 do_patch[depends] = "quilt-native:do_populate_sysroot"
1559completed before the ``do_patch`` task can execute. 1820
1821In this example, the ``do_populate_sysroot`` task of the target ``quilt-native``
1822must have completed before the ``do_patch`` task can execute.
1560 1823
1561The ``[rdepends]`` flag works in a similar way but takes targets in the 1824The ``[rdepends]`` flag works in a similar way but takes targets in the
1562runtime namespace instead of the build-time dependency namespace. 1825runtime namespace instead of the build-time dependency namespace.
@@ -1575,83 +1838,58 @@ It is often necessary to access variables in the BitBake datastore using
1575Python functions. The BitBake datastore has an API that allows you this 1838Python functions. The BitBake datastore has an API that allows you this
1576access. Here is a list of available operations: 1839access. Here is a list of available operations:
1577 1840
1578+-----------------------------------+-----------------------------------+ 1841.. list-table::
1579| *Operation* | *Description* | 1842 :widths: auto
1580+===================================+===================================+ 1843 :header-rows: 1
1581| ``d.getVar("X", expand)`` | Returns the value of variable | 1844
1582| | "X". Using "expand=True" expands | 1845 * - *Operation*
1583| | the value. Returns "None" if the | 1846 - *Description*
1584| | variable "X" does not exist. | 1847 * - ``d.getVar("X", expand)``
1585+-----------------------------------+-----------------------------------+ 1848 - Returns the value of variable "X". Using "expand=True" expands the
1586| ``d.setVar("X", "value")`` | Sets the variable "X" to "value". | 1849 value. Returns "None" if the variable "X" does not exist.
1587+-----------------------------------+-----------------------------------+ 1850 * - ``d.setVar("X", "value")``
1588| ``d.appendVar("X", "value")`` | Adds "value" to the end of the | 1851 - Sets the variable "X" to "value"
1589| | variable "X". Acts like | 1852 * - ``d.appendVar("X", "value")``
1590| | ``d.setVar("X", "value")`` if the | 1853 - Adds "value" to the end of the variable "X". Acts like ``d.setVar("X",
1591| | variable "X" does not exist. | 1854 "value")`` if the variable "X" does not exist.
1592+-----------------------------------+-----------------------------------+ 1855 * - ``d.prependVar("X", "value")``
1593| ``d.prependVar("X", "value")`` | Adds "value" to the start of the | 1856 - Adds "value" to the start of the variable "X". Acts like
1594| | variable "X". Acts like | 1857 ``d.setVar("X","value")`` if the variable "X" does not exist.
1595| | ``d.setVar("X", "value")`` if the | 1858 * - ``d.delVar("X")``
1596| | variable "X" does not exist. | 1859 - Deletes the variable "X" from the datastore. Does nothing if the variable
1597+-----------------------------------+-----------------------------------+ 1860 "X" does not exist.
1598| ``d.delVar("X")`` | Deletes the variable "X" from the | 1861 * - ``d.renameVar("X", "Y")``
1599| | datastore. Does nothing if the | 1862 - Renames the variable "X" to "Y". Does nothing if the variable "X" does
1600| | variable "X" does not exist. | 1863 not exist.
1601+-----------------------------------+-----------------------------------+ 1864 * - ``d.getVarFlag("X", flag, expand)``
1602| ``d.renameVar("X", "Y")`` | Renames the variable "X" to "Y". | 1865 - Returns the value of variable "X". Using "expand=True" expands the
1603| | Does nothing if the variable "X" | 1866 value. Returns "None" if either the variable "X" or the named flag does
1604| | does not exist. | 1867 not exist.
1605+-----------------------------------+-----------------------------------+ 1868 * - ``d.setVarFlag("X", flag, "value")``
1606| `` | Returns the value of variable | 1869 - Sets the named flag for variable "X" to "value".
1607| d.getVarFlag("X", flag, expand)`` | "X". Using "expand=True" expands | 1870 * - ``d.appendVarFlag("X", flag, "value")``
1608| | the value. Returns "None" if | 1871 - Appends "value" to the named flag on the variable "X". Acts like
1609| | either the variable "X" or the | 1872 ``d.setVarFlag("X", flag, "value")`` if the named flag does not exist.
1610| | named flag does not exist. | 1873 * - ``d.prependVarFlag("X", flag, "value")``
1611+-----------------------------------+-----------------------------------+ 1874 - Prepends "value" to the named flag on the variable "X". Acts like
1612| ``d | Sets the named flag for variable | 1875 ``d.setVarFlag("X", flag, "value")`` if the named flag does not exist.
1613| .setVarFlag("X", flag, "value")`` | "X" to "value". | 1876 * - ``d.delVarFlag("X", flag)``
1614+-----------------------------------+-----------------------------------+ 1877 - Deletes the named flag on the variable "X" from the datastore.
1615| ``d.ap | Appends "value" to the named flag | 1878 * - ``d.setVarFlags("X", flagsdict)``
1616| pendVarFlag("X", flag, "value")`` | on the variable "X". Acts like | 1879 - Sets the flags specified in the ``flagsdict()``
1617| | ``d | 1880 parameter. ``setVarFlags`` does not clear previous flags. Think of this
1618| | .setVarFlag("X", flag, "value")`` | 1881 operation as ``addVarFlags``.
1619| | if the named flag does not exist. | 1882 * - ``d.getVarFlags("X")``
1620+-----------------------------------+-----------------------------------+ 1883 - Returns a ``flagsdict`` of the flags for the variable "X". Returns "None"
1621| ``d.pre | Prepends "value" to the named | 1884 if the variable "X" does not exist.
1622| pendVarFlag("X", flag, "value")`` | flag on the variable "X". Acts | 1885 * - ``d.delVarFlags("X")``
1623| | like | 1886 - Deletes all the flags for the variable "X". Does nothing if the variable
1624| | ``d | 1887 "X" does not exist.
1625| | .setVarFlag("X", flag, "value")`` | 1888 * - ``d.expand(expression)``
1626| | if the named flag does not exist. | 1889 - Expands variable references in the specified string
1627+-----------------------------------+-----------------------------------+ 1890 expression. References to variables that do not exist are left as is. For
1628| ``d.delVarFlag("X", flag)`` | Deletes the named flag on the | 1891 example, ``d.expand("foo ${X}")`` expands to the literal string "foo
1629| | variable "X" from the datastore. | 1892 ${X}" if the variable "X" does not exist.
1630+-----------------------------------+-----------------------------------+
1631| ``d.setVarFlags("X", flagsdict)`` | Sets the flags specified in the |
1632| | ``flagsdict()`` parameter. |
1633| | ``setVarFlags`` does not clear |
1634| | previous flags. Think of this |
1635| | operation as ``addVarFlags``. |
1636+-----------------------------------+-----------------------------------+
1637| ``d.getVarFlags("X")`` | Returns a ``flagsdict`` of the |
1638| | flags for the variable "X". |
1639| | Returns "None" if the variable |
1640| | "X" does not exist. |
1641+-----------------------------------+-----------------------------------+
1642| ``d.delVarFlags("X")`` | Deletes all the flags for the |
1643| | variable "X". Does nothing if the |
1644| | variable "X" does not exist. |
1645+-----------------------------------+-----------------------------------+
1646| ``d.expand(expression)`` | Expands variable references in |
1647| | the specified string expression. |
1648| | References to variables that do |
1649| | not exist are left as is. For |
1650| | example, ``d.expand("foo ${X}")`` |
1651| | expands to the literal string |
1652| | "foo ${X}" if the variable "X" |
1653| | does not exist. |
1654+-----------------------------------+-----------------------------------+
1655 1893
1656Other Functions 1894Other Functions
1657--------------- 1895---------------
@@ -1671,8 +1909,11 @@ To help understand how BitBake does this, the section assumes an
1671OpenEmbedded metadata-based example. 1909OpenEmbedded metadata-based example.
1672 1910
1673These checksums are stored in :term:`STAMP`. You can 1911These checksums are stored in :term:`STAMP`. You can
1674examine the checksums using the following BitBake command: $ 1912examine the checksums using the following BitBake command: ::
1675bitbake-dumpsigs This command returns the signature data in a readable 1913
1914 $ bitbake-dumpsigs
1915
1916This command returns the signature data in a readable
1676format that allows you to examine the inputs used when the OpenEmbedded 1917format that allows you to examine the inputs used when the OpenEmbedded
1677build system generates signatures. For example, using 1918build system generates signatures. For example, using
1678``bitbake-dumpsigs`` allows you to examine the ``do_compile`` task's 1919``bitbake-dumpsigs`` allows you to examine the ``do_compile`` task's
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 61516a0115..b82661c697 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
@@ -55,9 +55,11 @@ overview of their function and contents.
55 - Limited support for the "``*``" wildcard character for matching 55 - Limited support for the "``*``" wildcard character for matching
56 against the beginning of host names exists. For example, the 56 against the beginning of host names exists. For example, the
57 following setting matches ``git.gnu.org``, ``ftp.gnu.org``, and 57 following setting matches ``git.gnu.org``, ``ftp.gnu.org``, and
58 ``foo.git.gnu.org``. BB_ALLOWED_NETWORKS = "\*.gnu.org" 58 ``foo.git.gnu.org``. ::
59 59
60 .. note:: 60 BB_ALLOWED_NETWORKS = "\*.gnu.org"
61
62 .. important::
61 63
62 The use of the "``*``" character only works at the beginning of 64 The use of the "``*``" character only works at the beginning of
63 a host name and it must be isolated from the remainder of the 65 a host name and it must be isolated from the remainder of the
@@ -111,26 +113,48 @@ overview of their function and contents.
111 you to control the build based on these parameters. 113 you to control the build based on these parameters.
112 114
113 Disk space monitoring is disabled by default. When setting this 115 Disk space monitoring is disabled by default. When setting this
114 variable, use the following form: BB_DISKMON_DIRS = 116 variable, use the following form: ::
115 "<action>,<dir>,<threshold> [...]" where: <action> is: ABORT: 117
116 Immediately abort the build when a threshold is broken. STOPTASKS: 118 BB_DISKMON_DIRS = "<action>,<dir>,<threshold> [...]"
117 Stop the build after the currently executing tasks have finished when 119
118 a threshold is broken. WARN: Issue a warning but continue the build 120 where:
119 when a threshold is broken. Subsequent warnings are issued as defined 121
120 by the :term:`BB_DISKMON_WARNINTERVAL` 122 <action> is:
121 variable, which must be defined. <dir> is: Any directory you choose. 123 ABORT: Immediately abort the build when
122 You can specify one or more directories to monitor by separating the 124 a threshold is broken.
123 groupings with a space. If two directories are on the same device, 125 STOPTASKS: Stop the build after the currently
124 only the first directory is monitored. <threshold> is: Either the 126 executing tasks have finished when
125 minimum available disk space, the minimum number of free inodes, or 127 a threshold is broken.
126 both. You must specify at least one. To omit one or the other, simply 128 WARN: Issue a warning but continue the
127 omit the value. Specify the threshold using G, M, K for Gbytes, 129 build when a threshold is broken.
128 Mbytes, and Kbytes, respectively. If you do not specify G, M, or K, 130 Subsequent warnings are issued as
129 Kbytes is assumed by default. Do not use GB, MB, or KB. 131 defined by the
130 132 BB_DISKMON_WARNINTERVAL variable,
131 Here are some examples: BB_DISKMON_DIRS = "ABORT,${TMPDIR},1G,100K 133 which must be defined.
132 WARN,${SSTATE_DIR},1G,100K" BB_DISKMON_DIRS = 134
133 "STOPTASKS,${TMPDIR},1G" BB_DISKMON_DIRS = "ABORT,${TMPDIR},,100K" 135 <dir> is:
136 Any directory you choose. You can specify one or
137 more directories to monitor by separating the
138 groupings with a space. If two directories are
139 on the same device, only the first directory
140 is monitored.
141
142 <threshold> is:
143 Either the minimum available disk space,
144 the minimum number of free inodes, or
145 both. You must specify at least one. To
146 omit one or the other, simply omit the value.
147 Specify the threshold using G, M, K for Gbytes,
148 Mbytes, and Kbytes, respectively. If you do
149 not specify G, M, or K, Kbytes is assumed by
150 default. Do not use GB, MB, or KB.
151
152 Here are some examples: ::
153
154 BB_DISKMON_DIRS = "ABORT,${TMPDIR},1G,100K WARN,${SSTATE_DIR},1G,100K"
155 BB_DISKMON_DIRS = "STOPTASKS,${TMPDIR},1G"
156 BB_DISKMON_DIRS = "ABORT,${TMPDIR},,100K"
157
134 The first example works only if you also set the 158 The first example works only if you also set the
135 :term:`BB_DISKMON_WARNINTERVAL` 159 :term:`BB_DISKMON_WARNINTERVAL`
136 variable. This example causes the build system to immediately abort 160 variable. This example causes the build system to immediately abort
@@ -166,16 +190,28 @@ overview of their function and contents.
166 BB_DISKMON_WARNINTERVAL = "50M,5K" 190 BB_DISKMON_WARNINTERVAL = "50M,5K"
167 191
168 When specifying the variable in your configuration file, use the 192 When specifying the variable in your configuration file, use the
169 following form: BB_DISKMON_WARNINTERVAL = 193 following form: ::
170 "<disk_space_interval>,<disk_inode_interval>" where: 194
171 <disk_space_interval> is: An interval of memory expressed in either 195 BB_DISKMON_WARNINTERVAL = "<disk_space_interval>,<disk_inode_interval>"
172 G, M, or K for Gbytes, Mbytes, or Kbytes, respectively. You cannot 196
173 use GB, MB, or KB. <disk_inode_interval> is: An interval of free 197 where:
174 inodes expressed in either G, M, or K for Gbytes, Mbytes, or Kbytes, 198
175 respectively. You cannot use GB, MB, or KB. 199 <disk_space_interval> is:
176 200 An interval of memory expressed in either
177 Here is an example: BB_DISKMON_DIRS = "WARN,${SSTATE_DIR},1G,100K" 201 G, M, or K for Gbytes, Mbytes, or Kbytes,
178 BB_DISKMON_WARNINTERVAL = "50M,5K" These variables cause BitBake to 202 respectively. You cannot use GB, MB, or KB.
203
204 <disk_inode_interval> is:
205 An interval of free inodes expressed in either
206 G, M, or K for Gbytes, Mbytes, or Kbytes,
207 respectively. You cannot use GB, MB, or KB.
208
209 Here is an example: ::
210
211 BB_DISKMON_DIRS = "WARN,${SSTATE_DIR},1G,100K"
212 BB_DISKMON_WARNINTERVAL = "50M,5K"
213
214 These variables cause BitBake to
179 issue subsequent warnings each time the available disk space further 215 issue subsequent warnings each time the available disk space further
180 reduces by 50 Mbytes or the number of free inodes further reduces by 216 reduces by 50 Mbytes or the number of free inodes further reduces by
181 5 Kbytes in the ``${SSTATE_DIR}`` directory. Subsequent warnings 217 5 Kbytes in the ``${SSTATE_DIR}`` directory. Subsequent warnings
@@ -186,10 +222,8 @@ overview of their function and contents.
186 Specifies the internal whitelist of variables to allow through from 222 Specifies the internal whitelist of variables to allow through from
187 the external environment into BitBake's datastore. If the value of 223 the external environment into BitBake's datastore. If the value of
188 this variable is not specified (which is the default), the following 224 this variable is not specified (which is the default), the following
189 list is used: :term:`BBPATH`, 225 list is used: :term:`BBPATH`, :term:`BB_PRESERVE_ENV`,
190 :term:`BB_PRESERVE_ENV`, 226 :term:`BB_ENV_WHITELIST`, and :term:`BB_ENV_EXTRAWHITE`.
191 :term:`BB_ENV_WHITELIST`, and
192 :term:`BB_ENV_EXTRAWHITE`.
193 227
194 .. note:: 228 .. note::
195 229
@@ -264,8 +298,9 @@ overview of their function and contents.
264 wishing to create a source mirror would want to enable this variable. 298 wishing to create a source mirror would want to enable this variable.
265 299
266 For performance reasons, creating and placing tarballs of the Git 300 For performance reasons, creating and placing tarballs of the Git
267 repositories is not the default action by BitBake. 301 repositories is not the default action by BitBake. ::
268 BB_GENERATE_MIRROR_TARBALLS = "1" 302
303 BB_GENERATE_MIRROR_TARBALLS = "1"
269 304
270 BB_HASHCONFIG_WHITELIST 305 BB_HASHCONFIG_WHITELIST
271 Lists variables that are excluded from base configuration checksum, 306 Lists variables that are excluded from base configuration checksum,
@@ -308,21 +343,25 @@ overview of their function and contents.
308 343
309 BB_LOGCONFIG 344 BB_LOGCONFIG
310 Specifies the name of a config file that contains the user logging 345 Specifies the name of a config file that contains the user logging
311 configuration. See `Logging <#logging>`__ for additional information 346 configuration. See
347 :ref:`bitbake-user-manual/bitbake-user-manual-execution:logging`
348 for additional information
312 349
313 BB_LOGFMT 350 BB_LOGFMT
314 Specifies the name of the log files saved into 351 Specifies the name of the log files saved into
315 ``${``\ :term:`T`\ ``}``. By default, the ``BB_LOGFMT`` 352 ``${``\ :term:`T`\ ``}``. By default, the ``BB_LOGFMT``
316 variable is undefined and the log file names get created using the 353 variable is undefined and the log file names get created using the
317 following form: log.{task}.{pid} If you want to force log files to 354 following form: ::
318 take a specific name, you can set this variable in a configuration 355
319 file. 356 log.{task}.{pid}
357
358 If you want to force log files to take a specific name, you can set this
359 variable in a configuration file.
320 360
321 BB_NICE_LEVEL 361 BB_NICE_LEVEL
322 Allows BitBake to run at a specific priority (i.e. nice level). 362 Allows BitBake to run at a specific priority (i.e. nice level).
323 System permissions usually mean that BitBake can reduce its priority 363 System permissions usually mean that BitBake can reduce its priority
324 but not raise it again. See 364 but not raise it again. See :term:`BB_TASK_NICE_LEVEL` for
325 :term:`BB_TASK_NICE_LEVEL` for
326 additional information. 365 additional information.
327 366
328 BB_NO_NETWORK 367 BB_NO_NETWORK
@@ -366,9 +405,12 @@ overview of their function and contents.
366 Specifies the name of the executable script files (i.e. run files) 405 Specifies the name of the executable script files (i.e. run files)
367 saved into ``${``\ :term:`T`\ ``}``. By default, the 406 saved into ``${``\ :term:`T`\ ``}``. By default, the
368 ``BB_RUNFMT`` variable is undefined and the run file names get 407 ``BB_RUNFMT`` variable is undefined and the run file names get
369 created using the following form: run.{task}.{pid} If you want to 408 created using the following form: ::
370 force run files to take a specific name, you can set this variable in 409
371 a configuration file. 410 run.{task}.{pid}
411
412 If you want to force run files to take a specific name, you can set this
413 variable in a configuration file.
372 414
373 BB_RUNTASK 415 BB_RUNTASK
374 Contains the name of the currently executing task. The value includes 416 Contains the name of the currently executing task. The value includes
@@ -423,8 +465,9 @@ overview of their function and contents.
423 generating checksum or dependency data for keys in the datastore, the 465 generating checksum or dependency data for keys in the datastore, the
424 flags set against that key are normally included in the checksum. 466 flags set against that key are normally included in the checksum.
425 467
426 For more information on varflags, see the "`Variable 468 For more information on varflags, see the
427 Flags <#variable-flags>`__" section. 469 ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:variable flags`"
470 section.
428 471
429 BB_SIGNATURE_HANDLER 472 BB_SIGNATURE_HANDLER
430 Defines the name of the signature handler BitBake uses. The signature 473 Defines the name of the signature handler BitBake uses. The signature
@@ -487,32 +530,30 @@ overview of their function and contents.
487 530
488 .. note:: 531 .. note::
489 532
490 This variable works similarly to the 533 This variable works similarly to the :term:`BB_TASK_NICE_LEVEL`
491 :term:`BB_TASK_NICE_LEVEL`
492 variable except with a task's I/O priorities. 534 variable except with a task's I/O priorities.
493 535
494 Set the variable as follows: BB_TASK_IONICE_LEVEL = "class.prio" For 536 Set the variable as follows: ::
495 class, the default value is "2", which is a best effort. You can use 537
538 BB_TASK_IONICE_LEVEL = "class.prio"
539
540 For *class*, the default value is "2", which is a best effort. You can use
496 "1" for realtime and "3" for idle. If you want to use realtime, you 541 "1" for realtime and "3" for idle. If you want to use realtime, you
497 must have superuser privileges. 542 must have superuser privileges.
498 543
499 For prio, you can use any value from "0", which is the highest 544 For *prio*, you can use any value from "0", which is the highest
500 priority, to "7", which is the lowest. The default value is "4". You 545 priority, to "7", which is the lowest. The default value is "4". You
501 do not need any special privileges to use this range of priority 546 do not need any special privileges to use this range of priority
502 values. 547 values.
503 548
504 .. note:: 549 .. note::
505 550
506 In order for your I/O priority settings to take effect, you need 551 In order for your I/O priority settings to take effect, you need the
507 the Completely Fair Queuing (CFQ) Scheduler selected for the 552 Completely Fair Queuing (CFQ) Scheduler selected for the backing block
508 backing block device. To select the scheduler, use the following 553 device. To select the scheduler, use the following command form where
509 command form where 554 device is the device (e.g. sda, sdb, and so forth): ::
510 device
511 is the device (e.g. sda, sdb, and so forth):
512 ::
513
514 $ sudo sh -c “echo cfq > /sys/block/device/queu/scheduler
515 555
556 $ sudo sh -c “echo cfq > /sys/block/device/queu/scheduler
516 557
517 BB_TASK_NICE_LEVEL 558 BB_TASK_NICE_LEVEL
518 Allows specific tasks to change their priority (i.e. nice level). 559 Allows specific tasks to change their priority (i.e. nice level).
@@ -551,8 +592,10 @@ overview of their function and contents.
551 To build a different variant of the recipe with a minimal amount of 592 To build a different variant of the recipe with a minimal amount of
552 code, it usually is as simple as adding the variable to your recipe. 593 code, it usually is as simple as adding the variable to your recipe.
553 Here are two examples. The "native" variants are from the 594 Here are two examples. The "native" variants are from the
554 OpenEmbedded-Core metadata: BBCLASSEXTEND =+ "native nativesdk" 595 OpenEmbedded-Core metadata: ::
555 BBCLASSEXTEND =+ "multilib:multilib_name" 596
597 BBCLASSEXTEND =+ "native nativesdk"
598 BBCLASSEXTEND =+ "multilib:multilib_name"
556 599
557 .. note:: 600 .. note::
558 601
@@ -612,9 +655,8 @@ overview of their function and contents.
612 655
613 .. tip:: 656 .. tip::
614 657
615 You can use the command 658 You can use the command bitbake-layers show-layers to list all
616 bitbake-layers show-layers 659 configured layers along with their priorities.
617 to list all configured layers along with their priorities.
618 660
619 BBFILES 661 BBFILES
620 A space-separated list of recipe files BitBake uses to build 662 A space-separated list of recipe files BitBake uses to build
@@ -642,11 +684,17 @@ overview of their function and contents.
642 BBLAYERS 684 BBLAYERS
643 Lists the layers to enable during the build. This variable is defined 685 Lists the layers to enable during the build. This variable is defined
644 in the ``bblayers.conf`` configuration file in the build directory. 686 in the ``bblayers.conf`` configuration file in the build directory.
645 Here is an example: BBLAYERS = " \\ /home/scottrif/poky/meta \\ 687 Here is an example: ::
646 /home/scottrif/poky/meta-yocto \\ /home/scottrif/poky/meta-yocto-bsp 688
647 \\ /home/scottrif/poky/meta-mykernel \\ " This example enables four 689 BBLAYERS = " \
648 layers, one of which is a custom, user-defined layer named 690 /home/scottrif/poky/meta \
649 ``meta-mykernel``. 691 /home/scottrif/poky/meta-yocto \
692 /home/scottrif/poky/meta-yocto-bsp \
693 /home/scottrif/poky/meta-mykernel \
694 "
695
696 This example enables four layers, one of which is a custom, user-defined
697 layer named ``meta-mykernel``.
650 698
651 BBLAYERS_FETCH_DIR 699 BBLAYERS_FETCH_DIR
652 Sets the base location where layers are stored. This setting is used 700 Sets the base location where layers are stored. This setting is used
@@ -670,13 +718,19 @@ overview of their function and contents.
670 718
671 The following example uses a complete regular expression to tell 719 The following example uses a complete regular expression to tell
672 BitBake to ignore all recipe and recipe append files in the 720 BitBake to ignore all recipe and recipe append files in the
673 ``meta-ti/recipes-misc/`` directory: BBMASK = "meta-ti/recipes-misc/" 721 ``meta-ti/recipes-misc/`` directory: ::
722
723 BBMASK = "meta-ti/recipes-misc/"
724
674 If you want to mask out multiple directories or recipes, you can 725 If you want to mask out multiple directories or recipes, you can
675 specify multiple regular expression fragments. This next example 726 specify multiple regular expression fragments. This next example
676 masks out multiple directories and individual recipes: BBMASK += 727 masks out multiple directories and individual recipes: ::
677 "/meta-ti/recipes-misc/ meta-ti/recipes-ti/packagegroup/" BBMASK += 728
678 "/meta-oe/recipes-support/" BBMASK += "/meta-foo/.*/openldap" BBMASK 729 BBMASK += "/meta-ti/recipes-misc/ meta-ti/recipes-ti/packagegroup/"
679 += "opencv.*\.bbappend" BBMASK += "lzma" 730 BBMASK += "/meta-oe/recipes-support/"
731 BBMASK += "/meta-foo/.*/openldap"
732 BBMASK += "opencv.*\.bbappend"
733 BBMASK += "lzma"
680 734
681 .. note:: 735 .. note::
682 736
@@ -691,15 +745,18 @@ overview of their function and contents.
691 ``conf/local.conf`` configuration file. 745 ``conf/local.conf`` configuration file.
692 746
693 As an example, the following line specifies three multiconfigs, each 747 As an example, the following line specifies three multiconfigs, each
694 having a separate configuration file: BBMULTIFONFIG = "configA 748 having a separate configuration file: ::
695 configB configC" Each configuration file you use must reside in the 749
750 BBMULTIFONFIG = "configA configB configC"
751
752 Each configuration file you use must reside in the
696 build directory within a directory named ``conf/multiconfig`` (e.g. 753 build directory within a directory named ``conf/multiconfig`` (e.g.
697 build_directory\ ``/conf/multiconfig/configA.conf``). 754 build_directory\ ``/conf/multiconfig/configA.conf``).
698 755
699 For information on how to use ``BBMULTICONFIG`` in an environment 756 For information on how to use ``BBMULTICONFIG`` in an environment
700 that supports building targets with multiple configurations, see the 757 that supports building targets with multiple configurations, see the
701 "`Executing a Multiple Configuration 758 ":ref:`bitbake-user-manual/bitbake-user-manual-intro:executing a multiple configuration build`"
702 Build <#executing-a-multiple-configuration-build>`__" section. 759 section.
703 760
704 BBPATH 761 BBPATH
705 Used by BitBake to locate class (``.bbclass``) and configuration 762 Used by BitBake to locate class (``.bbclass``) and configuration
@@ -709,7 +766,11 @@ overview of their function and contents.
709 If you run BitBake from a directory outside of the build directory, 766 If you run BitBake from a directory outside of the build directory,
710 you must be sure to set ``BBPATH`` to point to the build directory. 767 you must be sure to set ``BBPATH`` to point to the build directory.
711 Set the variable as you would any environment variable and then run 768 Set the variable as you would any environment variable and then run
712 BitBake: $ BBPATH="build_directory" $ export BBPATH $ bitbake target 769 BitBake: ::
770
771 $ BBPATH="build_directory"
772 $ export BBPATH
773 $ bitbake target
713 774
714 BBSERVER 775 BBSERVER
715 Points to the server that runs memory-resident BitBake. The variable 776 Points to the server that runs memory-resident BitBake. The variable
@@ -725,8 +786,8 @@ overview of their function and contents.
725 using the :term:`OVERRIDES` mechanism for a 786 using the :term:`OVERRIDES` mechanism for a
726 single version or for an optionally named range of versions. 787 single version or for an optionally named range of versions.
727 788
728 For more information on ``BBVERSIONS``, see the "`Variants - Class 789 For more information on ``BBVERSIONS``, see the
729 Extension Mechanism <#variants-class-extension-mechanism>`__" 790 ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:variants - class extension mechanism`"
730 section. 791 section.
731 792
732 BITBAKE_UI 793 BITBAKE_UI
@@ -765,37 +826,35 @@ overview of their function and contents.
765 826
766 .. note:: 827 .. note::
767 828
768 The bias provided by 829 The bias provided by DEFAULT_PREFERENCE is weak and is overridden by
769 DEFAULT_PREFERENCE 830 :term:`BBFILE_PRIORITY` if that variable is different between two
770 is weak and is overridden by 831 layers that contain different versions of the same recipe.
771 :term:`BBFILE_PRIORITY`
772 if that variable is different between two layers that contain
773 different versions of the same recipe.
774 832
775 DEPENDS 833 DEPENDS
776 Lists a recipe's build-time dependencies (i.e. other recipe files). 834 Lists a recipe's build-time dependencies (i.e. other recipe files).
777 835
778 Consider this simple example for two recipes named "a" and "b" that 836 Consider this simple example for two recipes named "a" and "b" that
779 produce similarly named packages. In this example, the ``DEPENDS`` 837 produce similarly named packages. In this example, the ``DEPENDS``
780 statement appears in the "a" recipe: DEPENDS = "b" Here, the 838 statement appears in the "a" recipe: ::
781 dependency is such that the ``do_configure`` task for recipe "a" 839
840 DEPENDS = "b"
841
842 Here, the dependency is such that the ``do_configure`` task for recipe "a"
782 depends on the ``do_populate_sysroot`` task of recipe "b". This means 843 depends on the ``do_populate_sysroot`` task of recipe "b". This means
783 anything that recipe "b" puts into sysroot is available when recipe 844 anything that recipe "b" puts into sysroot is available when recipe "a" is
784 "a" is configuring itself. 845 configuring itself.
785 846
786 For information on runtime dependencies, see the 847 For information on runtime dependencies, see the :term:`RDEPENDS`
787 :term:`RDEPENDS` variable. 848 variable.
788 849
789 DESCRIPTION 850 DESCRIPTION
790 A long description for the recipe. 851 A long description for the recipe.
791 852
792 DL_DIR 853 DL_DIR
793 The central download directory used by the build process to store 854 The central download directory used by the build process to store
794 downloads. By default, ``DL_DIR`` gets files suitable for mirroring 855 downloads. By default, ``DL_DIR`` gets files suitable for mirroring for
795 for everything except Git repositories. If you want tarballs of Git 856 everything except Git repositories. If you want tarballs of Git
796 repositories, use the 857 repositories, use the :term:`BB_GENERATE_MIRROR_TARBALLS` variable.
797 :term:`BB_GENERATE_MIRROR_TARBALLS`
798 variable.
799 858
800 EXCLUDE_FROM_WORLD 859 EXCLUDE_FROM_WORLD
801 Directs BitBake to exclude a recipe from world builds (i.e. 860 Directs BitBake to exclude a recipe from world builds (i.e.
@@ -808,13 +867,10 @@ overview of their function and contents.
808 867
809 .. note:: 868 .. note::
810 869
811 Recipes added to 870 Recipes added to ``EXCLUDE_FROM_WORLD`` may still be built during a world
812 EXCLUDE_FROM_WORLD 871 build in order to satisfy dependencies of other recipes. Adding a
813 may still be built during a world build in order to satisfy 872 recipe to ``EXCLUDE_FROM_WORLD`` only ensures that the recipe is not
814 dependencies of other recipes. Adding a recipe to 873 explicitly added to the list of build targets in a world build.
815 EXCLUDE_FROM_WORLD
816 only ensures that the recipe is not explicitly added to the list
817 of build targets in a world build.
818 874
819 FAKEROOT 875 FAKEROOT
820 Contains the command to use when running a shell script in a fakeroot 876 Contains the command to use when running a shell script in a fakeroot
@@ -883,8 +939,8 @@ overview of their function and contents.
883 configuration and in each individual recipe. The OpenEmbedded build 939 configuration and in each individual recipe. The OpenEmbedded build
884 system ignores changes to ``INHERIT`` in individual recipes. 940 system ignores changes to ``INHERIT`` in individual recipes.
885 941
886 For more information on ``INHERIT``, see the "```INHERIT`` 942 For more information on ``INHERIT``, see the
887 Configuration Directive <#inherit-configuration-directive>`__" 943 ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:\`\`inherit\`\` configuration directive`"
888 section. 944 section.
889 945
890 LAYERDEPENDS 946 LAYERDEPENDS
@@ -953,8 +1009,9 @@ overview of their function and contents.
953 1009
954 Following is a simple example that uses an overrides list based on 1010 Following is a simple example that uses an overrides list based on
955 machine architectures: OVERRIDES = "arm:x86:mips:powerpc" You can 1011 machine architectures: OVERRIDES = "arm:x86:mips:powerpc" You can
956 find information on how to use ``OVERRIDES`` in the "`Conditional 1012 find information on how to use ``OVERRIDES`` in the
957 Syntax (Overrides) <#conditional-syntax-overrides>`__" section. 1013 ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:conditional syntax
1014 (overrides)`" section.
958 1015
959 P4DIR 1016 P4DIR
960 The directory in which a local copy of a Perforce depot is stored 1017 The directory in which a local copy of a Perforce depot is stored
@@ -1000,20 +1057,26 @@ overview of their function and contents.
1000 recipes provide the same item. You should always suffix the variable 1057 recipes provide the same item. You should always suffix the variable
1001 with the name of the provided item, and you should set it to the 1058 with the name of the provided item, and you should set it to the
1002 :term:`PN` of the recipe to which you want to give 1059 :term:`PN` of the recipe to which you want to give
1003 precedence. Some examples: PREFERRED_PROVIDER_virtual/kernel ?= 1060 precedence. Some examples: ::
1004 "linux-yocto" PREFERRED_PROVIDER_virtual/xserver = "xserver-xf86" 1061
1005 PREFERRED_PROVIDER_virtual/libgl ?= "mesa" 1062 PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto"
1063 PREFERRED_PROVIDER_virtual/xserver = "xserver-xf86"
1064 PREFERRED_PROVIDER_virtual/libgl ?= "mesa"
1006 1065
1007 PREFERRED_PROVIDERS 1066 PREFERRED_PROVIDERS
1008 Determines which recipe should be given preference for cases where 1067 Determines which recipe should be given preference for cases where
1009 multiple recipes provide the same item. Functionally, 1068 multiple recipes provide the same item. Functionally,
1010 ``PREFERRED_PROVIDERS`` is identical to 1069 ``PREFERRED_PROVIDERS`` is identical to
1011 :term:`PREFERRED_PROVIDER`. However, the 1070 :term:`PREFERRED_PROVIDER`. However, the ``PREFERRED_PROVIDERS`` variable
1012 ``PREFERRED_PROVIDERS`` variable lets you define preferences for 1071 lets you define preferences for multiple situations using the following
1013 multiple situations using the following form: PREFERRED_PROVIDERS = 1072 form: ::
1014 "xxx:yyy aaa:bbb ..." This form is a convenient replacement for the 1073
1015 following: PREFERRED_PROVIDER_xxx = "yyy" PREFERRED_PROVIDER_aaa = 1074 PREFERRED_PROVIDERS = "xxx:yyy aaa:bbb ..."
1016 "bbb" 1075
1076 This form is a convenient replacement for the following: ::
1077
1078 PREFERRED_PROVIDER_xxx = "yyy"
1079 PREFERRED_PROVIDER_aaa = "bbb"
1017 1080
1018 PREFERRED_VERSION 1081 PREFERRED_VERSION
1019 If there are multiple versions of recipes available, this variable 1082 If there are multiple versions of recipes available, this variable
@@ -1026,15 +1089,15 @@ overview of their function and contents.
1026 through the "``%``" character. You can use the character to match any 1089 through the "``%``" character. You can use the character to match any
1027 number of characters, which can be useful when specifying versions 1090 number of characters, which can be useful when specifying versions
1028 that contain long revision numbers that potentially change. Here are 1091 that contain long revision numbers that potentially change. Here are
1029 two examples: PREFERRED_VERSION_python = "2.7.3" 1092 two examples: ::
1030 PREFERRED_VERSION_linux-yocto = "4.12%"
1031 1093
1032 .. note:: 1094 PREFERRED_VERSION_python = "2.7.3"
1095 PREFERRED_VERSION_linux-yocto = "4.12%"
1033 1096
1034 The use of the " 1097 .. important::
1035 % 1098
1036 " character is limited in that it only works at the end of the 1099 The use of the " % " character is limited in that it only works at the
1037 string. You cannot use the wildcard character in any other 1100 end of the string. You cannot use the wildcard character in any other
1038 location of the string. 1101 location of the string.
1039 1102
1040 PREMIRRORS 1103 PREMIRRORS
@@ -1042,19 +1105,21 @@ overview of their function and contents.
1042 the build system searches for source code, it first tries the local 1105 the build system searches for source code, it first tries the local
1043 download directory. If that location fails, the build system tries 1106 download directory. If that location fails, the build system tries
1044 locations defined by ``PREMIRRORS``, the upstream source, and then 1107 locations defined by ``PREMIRRORS``, the upstream source, and then
1045 locations specified by :term:`MIRRORS` in that 1108 locations specified by :term:`MIRRORS` in that order.
1046 order.
1047 1109
1048 Typically, you would add a specific server for the build system to 1110 Typically, you would add a specific server for the build system to
1049 attempt before any others by adding something like the following to 1111 attempt before any others by adding something like the following to
1050 your configuration: PREMIRRORS_prepend = "\\ git://.*/.\* 1112 your configuration: ::
1051 http://www.yoctoproject.org/sources/ \\n \\ ftp://.*/.\* 1113
1052 http://www.yoctoproject.org/sources/ \\n \\ http://.*/.\* 1114 PREMIRRORS_prepend = "\
1053 http://www.yoctoproject.org/sources/ \\n \\ https://.*/.\* 1115 git://.*/.* http://www.yoctoproject.org/sources/ \n \
1054 http://www.yoctoproject.org/sources/ \\n" These changes cause the 1116 ftp://.*/.* http://www.yoctoproject.org/sources/ \n \
1055 build system to intercept Git, FTP, HTTP, and HTTPS requests and 1117 http://.*/.* http://www.yoctoproject.org/sources/ \n \
1056 direct them to the ``http://`` sources mirror. You can use 1118 https://.*/.* http://www.yoctoproject.org/sources/ \n"
1057 ``file://`` URLs to point to local directories or network shares as 1119
1120 These changes cause the build system to intercept Git, FTP, HTTP, and
1121 HTTPS requests and direct them to the ``http://`` sources mirror. You can
1122 use ``file://`` URLs to point to local directories or network shares as
1058 well. 1123 well.
1059 1124
1060 PROVIDES 1125 PROVIDES
@@ -1066,9 +1131,12 @@ overview of their function and contents.
1066 ``DEPENDS``. 1131 ``DEPENDS``.
1067 1132
1068 Consider the following example ``PROVIDES`` statement from a recipe 1133 Consider the following example ``PROVIDES`` statement from a recipe
1069 file ``libav_0.8.11.bb``: PROVIDES += "libpostproc" The ``PROVIDES`` 1134 file ``libav_0.8.11.bb``: ::
1070 statement results in the "libav" recipe also being known as 1135
1071 "libpostproc". 1136 PROVIDES += "libpostproc"
1137
1138 The ``PROVIDES`` statement results in the "libav" recipe also being known
1139 as "libpostproc".
1072 1140
1073 In addition to providing recipes under alternate names, the 1141 In addition to providing recipes under alternate names, the
1074 ``PROVIDES`` mechanism is also used to implement virtual targets. A 1142 ``PROVIDES`` mechanism is also used to implement virtual targets. A
@@ -1086,10 +1154,13 @@ overview of their function and contents.
1086 PRSERV_HOST 1154 PRSERV_HOST
1087 The network based :term:`PR` service host and port. 1155 The network based :term:`PR` service host and port.
1088 1156
1089 Following is an example of how the ``PRSERV_HOST`` variable is set: 1157 Following is an example of how the ``PRSERV_HOST`` variable is set: ::
1090 PRSERV_HOST = "localhost:0" You must set the variable if you want to 1158
1091 automatically start a local PR service. You can set ``PRSERV_HOST`` 1159 PRSERV_HOST = "localhost:0"
1092 to other values to use a remote PR service. 1160
1161 You must set the variable if you want to automatically start a local PR
1162 service. You can set ``PRSERV_HOST`` to other values to use a remote PR
1163 service.
1093 1164
1094 PV 1165 PV
1095 The version of the recipe. 1166 The version of the recipe.
@@ -1104,21 +1175,36 @@ overview of their function and contents.
1104 you should always use the variable in a form with an attached package 1175 you should always use the variable in a form with an attached package
1105 name. For example, suppose you are building a development package 1176 name. For example, suppose you are building a development package
1106 that depends on the ``perl`` package. In this case, you would use the 1177 that depends on the ``perl`` package. In this case, you would use the
1107 following ``RDEPENDS`` statement: RDEPENDS_${PN}-dev += "perl" In the 1178 following ``RDEPENDS`` statement: ::
1108 example, the development package depends on the ``perl`` package. 1179
1109 Thus, the ``RDEPENDS`` variable has the ``${PN}-dev`` package name as 1180 RDEPENDS_${PN}-dev += "perl"
1110 part of the variable. 1181
1182 In the example, the development package depends on the ``perl`` package.
1183 Thus, the ``RDEPENDS`` variable has the ``${PN}-dev`` package name as part
1184 of the variable.
1111 1185
1112 BitBake supports specifying versioned dependencies. Although the 1186 BitBake supports specifying versioned dependencies. Although the
1113 syntax varies depending on the packaging format, BitBake hides these 1187 syntax varies depending on the packaging format, BitBake hides these
1114 differences from you. Here is the general syntax to specify versions 1188 differences from you. Here is the general syntax to specify versions
1115 with the ``RDEPENDS`` variable: RDEPENDS_${PN} = "package (operator 1189 with the ``RDEPENDS`` variable: ::
1116 version)" For ``operator``, you can specify the following: = < > <= 1190
1117 >= For example, the following sets up a dependency on version 1.2 or 1191 RDEPENDS_${PN} = "package (operator version)"
1118 greater of the package ``foo``: RDEPENDS_${PN} = "foo (>= 1.2)"
1119 1192
1120 For information on build-time dependencies, see the 1193 For ``operator``, you can specify the following: ::
1121 :term:`DEPENDS` variable. 1194
1195 =
1196 <
1197 >
1198 <=
1199 >=
1200
1201 For example, the following sets up a dependency on version 1.2 or
1202 greater of the package ``foo``: ::
1203
1204 RDEPENDS_${PN} = "foo (>= 1.2)"
1205
1206 For information on build-time dependencies, see the :term:`DEPENDS`
1207 variable.
1122 1208
1123 REPODIR 1209 REPODIR
1124 The directory in which a local copy of a ``google-repo`` directory is 1210 The directory in which a local copy of a ``google-repo`` directory is
@@ -1132,7 +1218,9 @@ overview of their function and contents.
1132 1218
1133 As with all package-controlling variables, you must always use the 1219 As with all package-controlling variables, you must always use the
1134 variable in conjunction with a package name override. Here is an 1220 variable in conjunction with a package name override. Here is an
1135 example: RPROVIDES_${PN} = "widget-abi-2" 1221 example: ::
1222
1223 RPROVIDES_${PN} = "widget-abi-2"
1136 1224
1137 RRECOMMENDS 1225 RRECOMMENDS
1138 A list of packages that extends the usability of a package being 1226 A list of packages that extends the usability of a package being
@@ -1144,11 +1232,22 @@ overview of their function and contents.
1144 BitBake supports specifying versioned recommends. Although the syntax 1232 BitBake supports specifying versioned recommends. Although the syntax
1145 varies depending on the packaging format, BitBake hides these 1233 varies depending on the packaging format, BitBake hides these
1146 differences from you. Here is the general syntax to specify versions 1234 differences from you. Here is the general syntax to specify versions
1147 with the ``RRECOMMENDS`` variable: RRECOMMENDS_${PN} = "package 1235 with the ``RRECOMMENDS`` variable: ::
1148 (operator version)" For ``operator``, you can specify the following: 1236
1149 = < > <= >= For example, the following sets up a recommend on version 1237 RRECOMMENDS_${PN} = "package (operator version)"
1150 1.2 or greater of the package ``foo``: RRECOMMENDS_${PN} = "foo (>= 1238
1151 1.2)" 1239 For ``operator``, you can specify the following: ::
1240
1241 =
1242 <
1243 >
1244 <=
1245 >=
1246
1247 For example, the following sets up a recommend on version
1248 1.2 or greater of the package ``foo``: ::
1249
1250 RRECOMMENDS_${PN} = "foo (>= 1.2)"
1152 1251
1153 SECTION 1252 SECTION
1154 The section in which packages should be categorized. 1253 The section in which packages should be categorized.
@@ -1165,56 +1264,56 @@ overview of their function and contents.
1165 1264
1166 The following list explains the available URI protocols: 1265 The following list explains the available URI protocols:
1167 1266
1168 - *``file://`` -* Fetches files, which are usually files shipped 1267 - ``file://`` : Fetches files, which are usually files shipped
1169 with the metadata, from the local machine. The path is relative to 1268 with the metadata, from the local machine. The path is relative to
1170 the :term:`FILESPATH` variable. 1269 the :term:`FILESPATH` variable.
1171 1270
1172 - *``bzr://`` -* Fetches files from a Bazaar revision control 1271 - ``bzr://`` : Fetches files from a Bazaar revision control
1173 repository. 1272 repository.
1174 1273
1175 - *``git://`` -* Fetches files from a Git revision control 1274 - ``git://`` : Fetches files from a Git revision control
1176 repository. 1275 repository.
1177 1276
1178 - *``osc://`` -* Fetches files from an OSC (OpenSUSE Build service) 1277 - ``osc://`` : Fetches files from an OSC (OpenSUSE Build service)
1179 revision control repository. 1278 revision control repository.
1180 1279
1181 - *``repo://`` -* Fetches files from a repo (Git) repository. 1280 - ``repo://`` : Fetches files from a repo (Git) repository.
1182 1281
1183 - *``http://`` -* Fetches files from the Internet using HTTP. 1282 - ``http://`` : Fetches files from the Internet using HTTP.
1184 1283
1185 - *``https://`` -* Fetches files from the Internet using HTTPS. 1284 - ``https://`` : Fetches files from the Internet using HTTPS.
1186 1285
1187 - *``ftp://`` -* Fetches files from the Internet using FTP. 1286 - ``ftp://`` : Fetches files from the Internet using FTP.
1188 1287
1189 - *``cvs://`` -* Fetches files from a CVS revision control 1288 - ``cvs://`` : Fetches files from a CVS revision control
1190 repository. 1289 repository.
1191 1290
1192 - *``hg://`` -* Fetches files from a Mercurial (``hg``) revision 1291 - ``hg://`` : Fetches files from a Mercurial (``hg``) revision
1193 control repository. 1292 control repository.
1194 1293
1195 - *``p4://`` -* Fetches files from a Perforce (``p4``) revision 1294 - ``p4://`` : Fetches files from a Perforce (``p4``) revision
1196 control repository. 1295 control repository.
1197 1296
1198 - *``ssh://`` -* Fetches files from a secure shell. 1297 - ``ssh://`` : Fetches files from a secure shell.
1199 1298
1200 - *``svn://`` -* Fetches files from a Subversion (``svn``) revision 1299 - ``svn://`` : Fetches files from a Subversion (``svn``) revision
1201 control repository. 1300 control repository.
1202 1301
1203 Here are some additional options worth mentioning: 1302 Here are some additional options worth mentioning:
1204 1303
1205 - *``unpack`` -* Controls whether or not to unpack the file if it is 1304 - ``unpack`` : Controls whether or not to unpack the file if it is
1206 an archive. The default action is to unpack the file. 1305 an archive. The default action is to unpack the file.
1207 1306
1208 - *``subdir`` -* Places the file (or extracts its contents) into the 1307 - ``subdir`` : Places the file (or extracts its contents) into the
1209 specified subdirectory. This option is useful for unusual tarballs 1308 specified subdirectory. This option is useful for unusual tarballs
1210 or other archives that do not have their files already in a 1309 or other archives that do not have their files already in a
1211 subdirectory within the archive. 1310 subdirectory within the archive.
1212 1311
1213 - *``name`` -* Specifies a name to be used for association with 1312 - ``name`` : Specifies a name to be used for association with
1214 ``SRC_URI`` checksums when you have more than one file specified 1313 ``SRC_URI`` checksums when you have more than one file specified
1215 in ``SRC_URI``. 1314 in ``SRC_URI``.
1216 1315
1217 - *``downloadfilename`` -* Specifies the filename used when storing 1316 - ``downloadfilename`` : Specifies the filename used when storing
1218 the downloaded file. 1317 the downloaded file.
1219 1318
1220 SRCDATE 1319 SRCDATE