summaryrefslogtreecommitdiffstats
path: root/bitbake/doc
diff options
context:
space:
mode:
Diffstat (limited to 'bitbake/doc')
-rw-r--r--bitbake/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst2438
1 files changed, 1236 insertions, 1202 deletions
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 41a77b3bce..efc4960399 100644
--- a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst
+++ b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst
@@ -23,1213 +23,1247 @@ overview of their function and contents.
23 not appear in the BitBake glossary. These other variables are 23 not appear in the BitBake glossary. These other variables are
24 variables used in systems that use BitBake. 24 variables used in systems that use BitBake.
25 25
26`A <#var-bb-ASSUME_PROVIDED>`__ `B <#var-bb-B>`__ `C <#var-bb-CACHE>`__ 26.. glossary::
27`D <#var-bb-DEFAULT_PREFERENCE>`__ `E <#var-bb-EXCLUDE_FROM_WORLD>`__ 27
28`F <#var-bb-FAKEROOT>`__ `G <#var-bb-GITDIR>`__ `H <#var-bb-HGDIR>`__ 28 ASSUME_PROVIDED
29`I <#var-bb-INHERIT>`__ `L <#var-bb-LAYERDEPENDS>`__ 29 Lists recipe names (```PN`` <#var-bb-PN>`__ values) BitBake does not
30`M <#var-bb-MIRRORS>`__ `O <#var-bb-OVERRIDES>`__ `P <#var-bb-P4DIR>`__ 30 attempt to build. Instead, BitBake assumes these recipes have already
31`R <#var-bb-RDEPENDS>`__ `S <#var-bb-SECTION>`__ `T <#var-bb-T>`__ 31 been built.
32 32
33ASSUME_PROVIDED 33 In OpenEmbedded-Core, ``ASSUME_PROVIDED`` mostly specifies native
34 Lists recipe names (```PN`` <#var-bb-PN>`__ values) BitBake does not 34 tools that should not be built. An example is ``git-native``, which
35 attempt to build. Instead, BitBake assumes these recipes have already 35 when specified allows for the Git binary from the host to be used
36 been built. 36 rather than building ``git-native``.
37 37
38 In OpenEmbedded-Core, ``ASSUME_PROVIDED`` mostly specifies native 38 B
39 tools that should not be built. An example is ``git-native``, which 39 The directory in which BitBake executes functions during a recipe's
40 when specified allows for the Git binary from the host to be used 40 build process.
41 rather than building ``git-native``. 41
42 42 BB_ALLOWED_NETWORKS
43B 43 Specifies a space-delimited list of hosts that the fetcher is allowed
44 The directory in which BitBake executes functions during a recipe's 44 to use to obtain the required source code. Following are
45 build process. 45 considerations surrounding this variable:
46 46
47BB_ALLOWED_NETWORKS 47 - This host list is only used if
48 Specifies a space-delimited list of hosts that the fetcher is allowed 48 ```BB_NO_NETWORK`` <#var-bb-BB_NO_NETWORK>`__ is either not set or
49 to use to obtain the required source code. Following are 49 set to "0".
50 considerations surrounding this variable: 50
51 51 - Limited support for the "``*``" wildcard character for matching
52 - This host list is only used if 52 against the beginning of host names exists. For example, the
53 ```BB_NO_NETWORK`` <#var-bb-BB_NO_NETWORK>`__ is either not set or 53 following setting matches ``git.gnu.org``, ``ftp.gnu.org``, and
54 set to "0". 54 ``foo.git.gnu.org``. BB_ALLOWED_NETWORKS = "*.gnu.org"
55 55
56 - Limited support for the "``*``" wildcard character for matching 56 .. note::
57 against the beginning of host names exists. For example, the 57
58 following setting matches ``git.gnu.org``, ``ftp.gnu.org``, and 58 The use of the "``*``" character only works at the beginning of
59 ``foo.git.gnu.org``. BB_ALLOWED_NETWORKS = "*.gnu.org" 59 a host name and it must be isolated from the remainder of the
60 host name. You cannot use the wildcard character in any other
61 location of the name or combined with the front part of the
62 name.
63
64 For example, ``*.foo.bar`` is supported, while ``*aa.foo.bar``
65 is not.
66
67 - Mirrors not in the host list are skipped and logged in debug.
68
69 - Attempts to access networks not in the host list cause a failure.
70
71 Using ``BB_ALLOWED_NETWORKS`` in conjunction with
72 ```PREMIRRORS`` <#var-bb-PREMIRRORS>`__ is very useful. Adding the
73 host you want to use to ``PREMIRRORS`` results in the source code
74 being fetched from an allowed location and avoids raising an error
75 when a host that is not allowed is in a
76 ```SRC_URI`` <#var-bb-SRC_URI>`__ statement. This is because the
77 fetcher does not attempt to use the host listed in ``SRC_URI`` after
78 a successful fetch from the ``PREMIRRORS`` occurs.
79
80 BB_CONSOLELOG
81 Specifies the path to a log file into which BitBake's user interface
82 writes output during the build.
83
84 BB_CURRENTTASK
85 Contains the name of the currently running task. The name does not
86 include the ``do_`` prefix.
87
88 BB_DANGLINGAPPENDS_WARNONLY
89 Defines how BitBake handles situations where an append file
90 (``.bbappend``) has no corresponding recipe file (``.bb``). This
91 condition often occurs when layers get out of sync (e.g. ``oe-core``
92 bumps a recipe version and the old recipe no longer exists and the
93 other layer has not been updated to the new version of the recipe
94 yet).
95
96 The default fatal behavior is safest because it is the sane reaction
97 given something is out of sync. It is important to realize when your
98 changes are no longer being applied.
99
100 BB_DEFAULT_TASK
101 The default task to use when none is specified (e.g. with the ``-c``
102 command line option). The task name specified should not include the
103 ``do_`` prefix.
104
105 BB_DISKMON_DIRS
106 Monitors disk space and available inodes during the build and allows
107 you to control the build based on these parameters.
108
109 Disk space monitoring is disabled by default. When setting this
110 variable, use the following form: BB_DISKMON_DIRS =
111 "<action>,<dir>,<threshold> [...]" where: <action> is: ABORT:
112 Immediately abort the build when a threshold is broken. STOPTASKS:
113 Stop the build after the currently executing tasks have finished when
114 a threshold is broken. WARN: Issue a warning but continue the build
115 when a threshold is broken. Subsequent warnings are issued as defined
116 by the `BB_DISKMON_WARNINTERVAL <#var-bb-BB_DISKMON_WARNINTERVAL>`__
117 variable, which must be defined. <dir> is: Any directory you choose.
118 You can specify one or more directories to monitor by separating the
119 groupings with a space. If two directories are on the same device,
120 only the first directory is monitored. <threshold> is: Either the
121 minimum available disk space, the minimum number of free inodes, or
122 both. You must specify at least one. To omit one or the other, simply
123 omit the value. Specify the threshold using G, M, K for Gbytes,
124 Mbytes, and Kbytes, respectively. If you do not specify G, M, or K,
125 Kbytes is assumed by default. Do not use GB, MB, or KB.
126
127 Here are some examples: BB_DISKMON_DIRS = "ABORT,${TMPDIR},1G,100K
128 WARN,${SSTATE_DIR},1G,100K" BB_DISKMON_DIRS =
129 "STOPTASKS,${TMPDIR},1G" BB_DISKMON_DIRS = "ABORT,${TMPDIR},,100K"
130 The first example works only if you also set the
131 ```BB_DISKMON_WARNINTERVAL`` <#var-bb-BB_DISKMON_WARNINTERVAL>`__
132 variable. This example causes the build system to immediately abort
133 when either the disk space in ``${TMPDIR}`` drops below 1 Gbyte or
134 the available free inodes drops below 100 Kbytes. Because two
135 directories are provided with the variable, the build system also
136 issues a warning when the disk space in the ``${SSTATE_DIR}``
137 directory drops below 1 Gbyte or the number of free inodes drops
138 below 100 Kbytes. Subsequent warnings are issued during intervals as
139 defined by the ``BB_DISKMON_WARNINTERVAL`` variable.
140
141 The second example stops the build after all currently executing
142 tasks complete when the minimum disk space in the ``${TMPDIR}``
143 directory drops below 1 Gbyte. No disk monitoring occurs for the free
144 inodes in this case.
145
146 The final example immediately aborts the build when the number of
147 free inodes in the ``${TMPDIR}`` directory drops below 100 Kbytes. No
148 disk space monitoring for the directory itself occurs in this case.
149
150 BB_DISKMON_WARNINTERVAL
151 Defines the disk space and free inode warning intervals.
152
153 If you are going to use the ``BB_DISKMON_WARNINTERVAL`` variable, you
154 must also use the ```BB_DISKMON_DIRS`` <#var-bb-BB_DISKMON_DIRS>`__
155 variable and define its action as "WARN". During the build,
156 subsequent warnings are issued each time disk space or number of free
157 inodes further reduces by the respective interval.
158
159 If you do not provide a ``BB_DISKMON_WARNINTERVAL`` variable and you
160 do use ``BB_DISKMON_DIRS`` with the "WARN" action, the disk
161 monitoring interval defaults to the following:
162 BB_DISKMON_WARNINTERVAL = "50M,5K"
163
164 When specifying the variable in your configuration file, use the
165 following form: BB_DISKMON_WARNINTERVAL =
166 "<disk_space_interval>,<disk_inode_interval>" where:
167 <disk_space_interval> is: An interval of memory expressed in either
168 G, M, or K for Gbytes, Mbytes, or Kbytes, respectively. You cannot
169 use GB, MB, or KB. <disk_inode_interval> is: An interval of free
170 inodes expressed in either G, M, or K for Gbytes, Mbytes, or Kbytes,
171 respectively. You cannot use GB, MB, or KB.
172
173 Here is an example: BB_DISKMON_DIRS = "WARN,${SSTATE_DIR},1G,100K"
174 BB_DISKMON_WARNINTERVAL = "50M,5K" These variables cause BitBake to
175 issue subsequent warnings each time the available disk space further
176 reduces by 50 Mbytes or the number of free inodes further reduces by
177 5 Kbytes in the ``${SSTATE_DIR}`` directory. Subsequent warnings
178 based on the interval occur each time a respective interval is
179 reached beyond the initial warning (i.e. 1 Gbytes and 100 Kbytes).
180
181 BB_ENV_WHITELIST
182 Specifies the internal whitelist of variables to allow through from
183 the external environment into BitBake's datastore. If the value of
184 this variable is not specified (which is the default), the following
185 list is used: ```BBPATH`` <#var-bb-BBPATH>`__,
186 ```BB_PRESERVE_ENV`` <#var-bb-BB_PRESERVE_ENV>`__,
187 ```BB_ENV_WHITELIST`` <#var-bb-BB_ENV_WHITELIST>`__, and
188 ```BB_ENV_EXTRAWHITE`` <#var-bb-BB_ENV_EXTRAWHITE>`__.
60 189
61 .. note:: 190 .. note::
62 191
63 The use of the "``*``" character only works at the beginning of 192 You must set this variable in the external environment in order
64 a host name and it must be isolated from the remainder of the 193 for it to work.
65 host name. You cannot use the wildcard character in any other
66 location of the name or combined with the front part of the
67 name.
68
69 For example, ``*.foo.bar`` is supported, while ``*aa.foo.bar``
70 is not.
71
72 - Mirrors not in the host list are skipped and logged in debug.
73
74 - Attempts to access networks not in the host list cause a failure.
75
76 Using ``BB_ALLOWED_NETWORKS`` in conjunction with
77 ```PREMIRRORS`` <#var-bb-PREMIRRORS>`__ is very useful. Adding the
78 host you want to use to ``PREMIRRORS`` results in the source code
79 being fetched from an allowed location and avoids raising an error
80 when a host that is not allowed is in a
81 ```SRC_URI`` <#var-bb-SRC_URI>`__ statement. This is because the
82 fetcher does not attempt to use the host listed in ``SRC_URI`` after
83 a successful fetch from the ``PREMIRRORS`` occurs.
84
85BB_CONSOLELOG
86 Specifies the path to a log file into which BitBake's user interface
87 writes output during the build.
88
89BB_CURRENTTASK
90 Contains the name of the currently running task. The name does not
91 include the ``do_`` prefix.
92
93BB_DANGLINGAPPENDS_WARNONLY
94 Defines how BitBake handles situations where an append file
95 (``.bbappend``) has no corresponding recipe file (``.bb``). This
96 condition often occurs when layers get out of sync (e.g. ``oe-core``
97 bumps a recipe version and the old recipe no longer exists and the
98 other layer has not been updated to the new version of the recipe
99 yet).
100
101 The default fatal behavior is safest because it is the sane reaction
102 given something is out of sync. It is important to realize when your
103 changes are no longer being applied.
104
105BB_DEFAULT_TASK
106 The default task to use when none is specified (e.g. with the ``-c``
107 command line option). The task name specified should not include the
108 ``do_`` prefix.
109
110BB_DISKMON_DIRS
111 Monitors disk space and available inodes during the build and allows
112 you to control the build based on these parameters.
113
114 Disk space monitoring is disabled by default. When setting this
115 variable, use the following form: BB_DISKMON_DIRS =
116 "<action>,<dir>,<threshold> [...]" where: <action> is: ABORT:
117 Immediately abort the build when a threshold is broken. STOPTASKS:
118 Stop the build after the currently executing tasks have finished when
119 a threshold is broken. WARN: Issue a warning but continue the build
120 when a threshold is broken. Subsequent warnings are issued as defined
121 by the `BB_DISKMON_WARNINTERVAL <#var-bb-BB_DISKMON_WARNINTERVAL>`__
122 variable, which must be defined. <dir> is: Any directory you choose.
123 You can specify one or more directories to monitor by separating the
124 groupings with a space. If two directories are on the same device,
125 only the first directory is monitored. <threshold> is: Either the
126 minimum available disk space, the minimum number of free inodes, or
127 both. You must specify at least one. To omit one or the other, simply
128 omit the value. Specify the threshold using G, M, K for Gbytes,
129 Mbytes, and Kbytes, respectively. If you do not specify G, M, or K,
130 Kbytes is assumed by default. Do not use GB, MB, or KB.
131
132 Here are some examples: BB_DISKMON_DIRS = "ABORT,${TMPDIR},1G,100K
133 WARN,${SSTATE_DIR},1G,100K" BB_DISKMON_DIRS =
134 "STOPTASKS,${TMPDIR},1G" BB_DISKMON_DIRS = "ABORT,${TMPDIR},,100K"
135 The first example works only if you also set the
136 ```BB_DISKMON_WARNINTERVAL`` <#var-bb-BB_DISKMON_WARNINTERVAL>`__
137 variable. This example causes the build system to immediately abort
138 when either the disk space in ``${TMPDIR}`` drops below 1 Gbyte or
139 the available free inodes drops below 100 Kbytes. Because two
140 directories are provided with the variable, the build system also
141 issues a warning when the disk space in the ``${SSTATE_DIR}``
142 directory drops below 1 Gbyte or the number of free inodes drops
143 below 100 Kbytes. Subsequent warnings are issued during intervals as
144 defined by the ``BB_DISKMON_WARNINTERVAL`` variable.
145
146 The second example stops the build after all currently executing
147 tasks complete when the minimum disk space in the ``${TMPDIR}``
148 directory drops below 1 Gbyte. No disk monitoring occurs for the free
149 inodes in this case.
150
151 The final example immediately aborts the build when the number of
152 free inodes in the ``${TMPDIR}`` directory drops below 100 Kbytes. No
153 disk space monitoring for the directory itself occurs in this case.
154
155BB_DISKMON_WARNINTERVAL
156 Defines the disk space and free inode warning intervals.
157
158 If you are going to use the ``BB_DISKMON_WARNINTERVAL`` variable, you
159 must also use the ```BB_DISKMON_DIRS`` <#var-bb-BB_DISKMON_DIRS>`__
160 variable and define its action as "WARN". During the build,
161 subsequent warnings are issued each time disk space or number of free
162 inodes further reduces by the respective interval.
163
164 If you do not provide a ``BB_DISKMON_WARNINTERVAL`` variable and you
165 do use ``BB_DISKMON_DIRS`` with the "WARN" action, the disk
166 monitoring interval defaults to the following:
167 BB_DISKMON_WARNINTERVAL = "50M,5K"
168
169 When specifying the variable in your configuration file, use the
170 following form: BB_DISKMON_WARNINTERVAL =
171 "<disk_space_interval>,<disk_inode_interval>" where:
172 <disk_space_interval> is: An interval of memory expressed in either
173 G, M, or K for Gbytes, Mbytes, or Kbytes, respectively. You cannot
174 use GB, MB, or KB. <disk_inode_interval> is: An interval of free
175 inodes expressed in either G, M, or K for Gbytes, Mbytes, or Kbytes,
176 respectively. You cannot use GB, MB, or KB.
177
178 Here is an example: BB_DISKMON_DIRS = "WARN,${SSTATE_DIR},1G,100K"
179 BB_DISKMON_WARNINTERVAL = "50M,5K" These variables cause BitBake to
180 issue subsequent warnings each time the available disk space further
181 reduces by 50 Mbytes or the number of free inodes further reduces by
182 5 Kbytes in the ``${SSTATE_DIR}`` directory. Subsequent warnings
183 based on the interval occur each time a respective interval is
184 reached beyond the initial warning (i.e. 1 Gbytes and 100 Kbytes).
185
186BB_ENV_WHITELIST
187 Specifies the internal whitelist of variables to allow through from
188 the external environment into BitBake's datastore. If the value of
189 this variable is not specified (which is the default), the following
190 list is used: ```BBPATH`` <#var-bb-BBPATH>`__,
191 ```BB_PRESERVE_ENV`` <#var-bb-BB_PRESERVE_ENV>`__,
192 ```BB_ENV_WHITELIST`` <#var-bb-BB_ENV_WHITELIST>`__, and
193 ```BB_ENV_EXTRAWHITE`` <#var-bb-BB_ENV_EXTRAWHITE>`__.
194
195 .. note::
196
197 You must set this variable in the external environment in order
198 for it to work.
199
200BB_ENV_EXTRAWHITE
201 Specifies an additional set of variables to allow through (whitelist)
202 from the external environment into BitBake's datastore. This list of
203 variables are on top of the internal list set in
204 ```BB_ENV_WHITELIST`` <#var-bb-BB_ENV_WHITELIST>`__.
205
206 .. note::
207
208 You must set this variable in the external environment in order
209 for it to work.
210
211BB_FETCH_PREMIRRORONLY
212 When set to "1", causes BitBake's fetcher module to only search
213 ```PREMIRRORS`` <#var-bb-PREMIRRORS>`__ for files. BitBake will not
214 search the main ```SRC_URI`` <#var-bb-SRC_URI>`__ or
215 ```MIRRORS`` <#var-bb-MIRRORS>`__.
216
217BB_FILENAME
218 Contains the filename of the recipe that owns the currently running
219 task. For example, if the ``do_fetch`` task that resides in the
220 ``my-recipe.bb`` is executing, the ``BB_FILENAME`` variable contains
221 "/foo/path/my-recipe.bb".
222
223BB_GENERATE_MIRROR_TARBALLS
224 Causes tarballs of the Git repositories, including the Git metadata,
225 to be placed in the ```DL_DIR`` <#var-bb-DL_DIR>`__ directory. Anyone
226 wishing to create a source mirror would want to enable this variable.
227
228 For performance reasons, creating and placing tarballs of the Git
229 repositories is not the default action by BitBake.
230 BB_GENERATE_MIRROR_TARBALLS = "1"
231
232BB_HASHCONFIG_WHITELIST
233 Lists variables that are excluded from base configuration checksum,
234 which is used to determine if the cache can be reused.
235
236 One of the ways BitBake determines whether to re-parse the main
237 metadata is through checksums of the variables in the datastore of
238 the base configuration data. There are variables that you typically
239 want to exclude when checking whether or not to re-parse and thus
240 rebuild the cache. As an example, you would usually exclude ``TIME``
241 and ``DATE`` because these variables are always changing. If you did
242 not exclude them, BitBake would never reuse the cache.
243
244BB_HASHBASE_WHITELIST
245 Lists variables that are excluded from checksum and dependency data.
246 Variables that are excluded can therefore change without affecting
247 the checksum mechanism. A common example would be the variable for
248 the path of the build. BitBake's output should not (and usually does
249 not) depend on the directory in which it was built.
250
251BB_HASHCHECK_FUNCTION
252 Specifies the name of the function to call during the "setscene" part
253 of the task's execution in order to validate the list of task hashes.
254 The function returns the list of setscene tasks that should be
255 executed.
256
257 At this point in the execution of the code, the objective is to
258 quickly verify if a given setscene function is likely to work or not.
259 It's easier to check the list of setscene functions in one pass than
260 to call many individual tasks. The returned list need not be
261 completely accurate. A given setscene task can still later fail.
262 However, the more accurate the data returned, the more efficient the
263 build will be.
264
265BB_INVALIDCONF
266 Used in combination with the ``ConfigParsed`` event to trigger
267 re-parsing the base metadata (i.e. all the recipes). The
268 ``ConfigParsed`` event can set the variable to trigger the re-parse.
269 You must be careful to avoid recursive loops with this functionality.
270
271BB_LOGCONFIG
272 Specifies the name of a config file that contains the user logging
273 configuration. See `Logging <#logging>`__ for additional information
274
275BB_LOGFMT
276 Specifies the name of the log files saved into
277 ``${``\ ```T`` <#var-bb-T>`__\ ``}``. By default, the ``BB_LOGFMT``
278 variable is undefined and the log file names get created using the
279 following form: log.{task}.{pid} If you want to force log files to
280 take a specific name, you can set this variable in a configuration
281 file.
282
283BB_NICE_LEVEL
284 Allows BitBake to run at a specific priority (i.e. nice level).
285 System permissions usually mean that BitBake can reduce its priority
286 but not raise it again. See
287 ```BB_TASK_NICE_LEVEL`` <#var-bb-BB_TASK_NICE_LEVEL>`__ for
288 additional information.
289
290BB_NO_NETWORK
291 Disables network access in the BitBake fetcher modules. With this
292 access disabled, any command that attempts to access the network
293 becomes an error.
294
295 Disabling network access is useful for testing source mirrors,
296 running builds when not connected to the Internet, and when operating
297 in certain kinds of firewall environments.
298
299BB_NUMBER_THREADS
300 The maximum number of tasks BitBake should run in parallel at any one
301 time. If your host development system supports multiple cores, a good
302 rule of thumb is to set this variable to twice the number of cores.
303
304BB_NUMBER_PARSE_THREADS
305 Sets the number of threads BitBake uses when parsing. By default, the
306 number of threads is equal to the number of cores on the system.
307
308BB_ORIGENV
309 Contains a copy of the original external environment in which BitBake
310 was run. The copy is taken before any whitelisted variable values are
311 filtered into BitBake's datastore.
312
313 .. note::
314
315 The contents of this variable is a datastore object that can be
316 queried using the normal datastore operations.
317
318BB_PRESERVE_ENV
319 Disables whitelisting and instead allows all variables through from
320 the external environment into BitBake's datastore.
321
322 .. note::
323
324 You must set this variable in the external environment in order
325 for it to work.
326
327BB_RUNFMT
328 Specifies the name of the executable script files (i.e. run files)
329 saved into ``${``\ ```T`` <#var-bb-T>`__\ ``}``. By default, the
330 ``BB_RUNFMT`` variable is undefined and the run file names get
331 created using the following form: run.{task}.{pid} If you want to
332 force run files to take a specific name, you can set this variable in
333 a configuration file.
334
335BB_RUNTASK
336 Contains the name of the currently executing task. The value includes
337 the "do_" prefix. For example, if the currently executing task is
338 ``do_config``, the value is "do_config".
339
340BB_SCHEDULER
341 Selects the name of the scheduler to use for the scheduling of
342 BitBake tasks. Three options exist:
343
344 - *basic* - The basic framework from which everything derives. Using
345 this option causes tasks to be ordered numerically as they are
346 parsed.
347
348 - *speed* - Executes tasks first that have more tasks depending on
349 them. The "speed" option is the default.
350
351 - *completion* - Causes the scheduler to try to complete a given
352 recipe once its build has started.
353
354BB_SCHEDULERS
355 Defines custom schedulers to import. Custom schedulers need to be
356 derived from the ``RunQueueScheduler`` class.
357
358 For information how to select a scheduler, see the
359 ```BB_SCHEDULER`` <#var-bb-BB_SCHEDULER>`__ variable.
360
361BB_SETSCENE_DEPVALID
362 Specifies a function BitBake calls that determines whether BitBake
363 requires a setscene dependency to be met.
364
365 When running a setscene task, BitBake needs to know which
366 dependencies of that setscene task also need to be run. Whether
367 dependencies also need to be run is highly dependent on the metadata.
368 The function specified by this variable returns a "True" or "False"
369 depending on whether the dependency needs to be met.
370
371BB_SETSCENE_VERIFY_FUNCTION2
372 Specifies a function to call that verifies the list of planned task
373 execution before the main task execution happens. The function is
374 called once BitBake has a list of setscene tasks that have run and
375 either succeeded or failed.
376
377 The function allows for a task list check to see if they make sense.
378 Even if BitBake was planning to skip a task, the returned value of
379 the function can force BitBake to run the task, which is necessary
380 under certain metadata defined circumstances.
381
382BB_SIGNATURE_EXCLUDE_FLAGS
383 Lists variable flags (varflags) that can be safely excluded from
384 checksum and dependency data for keys in the datastore. When
385 generating checksum or dependency data for keys in the datastore, the
386 flags set against that key are normally included in the checksum.
387
388 For more information on varflags, see the "`Variable
389 Flags <#variable-flags>`__" section.
390
391BB_SIGNATURE_HANDLER
392 Defines the name of the signature handler BitBake uses. The signature
393 handler defines the way stamp files are created and handled, if and
394 how the signature is incorporated into the stamps, and how the
395 signature itself is generated.
396
397 A new signature handler can be added by injecting a class derived
398 from the ``SignatureGenerator`` class into the global namespace.
399
400BB_SRCREV_POLICY
401 Defines the behavior of the fetcher when it interacts with source
402 control systems and dynamic source revisions. The
403 ``BB_SRCREV_POLICY`` variable is useful when working without a
404 network.
405
406 The variable can be set using one of two policies:
407
408 - *cache* - Retains the value the system obtained previously rather
409 than querying the source control system each time.
410
411 - *clear* - Queries the source controls system every time. With this
412 policy, there is no cache. The "clear" policy is the default.
413
414BB_STAMP_POLICY
415 Defines the mode used for how timestamps of stamp files are compared.
416 You can set the variable to one of the following modes:
417
418 - *perfile* - Timestamp comparisons are only made between timestamps
419 of a specific recipe. This is the default mode.
420
421 - *full* - Timestamp comparisons are made for all dependencies.
422
423 - *whitelist* - Identical to "full" mode except timestamp
424 comparisons are made for recipes listed in the
425 ```BB_STAMP_WHITELIST`` <#var-bb-BB_STAMP_WHITELIST>`__ variable.
426
427 .. note::
428
429 Stamp policies are largely obsolete with the introduction of
430 setscene tasks.
431
432BB_STAMP_WHITELIST
433 Lists files whose stamp file timestamps are compared when the stamp
434 policy mode is set to "whitelist". For information on stamp policies,
435 see the ```BB_STAMP_POLICY`` <#var-bb-BB_STAMP_POLICY>`__ variable.
436
437BB_STRICT_CHECKSUM
438 Sets a more strict checksum mechanism for non-local URLs. Setting
439 this variable to a value causes BitBake to report an error if it
440 encounters a non-local URL that does not have at least one checksum
441 specified.
442
443BB_TASK_IONICE_LEVEL
444 Allows adjustment of a task's Input/Output priority. During
445 Autobuilder testing, random failures can occur for tasks due to I/O
446 starvation. These failures occur during various QEMU runtime
447 timeouts. You can use the ``BB_TASK_IONICE_LEVEL`` variable to adjust
448 the I/O priority of these tasks.
449
450 .. note::
451
452 This variable works similarly to the
453 BB_TASK_NICE_LEVEL
454 variable except with a task's I/O priorities.
455
456 Set the variable as follows: BB_TASK_IONICE_LEVEL = "class.prio" For
457 class, the default value is "2", which is a best effort. You can use
458 "1" for realtime and "3" for idle. If you want to use realtime, you
459 must have superuser privileges.
460
461 For prio, you can use any value from "0", which is the highest
462 priority, to "7", which is the lowest. The default value is "4". You
463 do not need any special privileges to use this range of priority
464 values.
465
466 .. note::
467
468 In order for your I/O priority settings to take effect, you need
469 the Completely Fair Queuing (CFQ) Scheduler selected for the
470 backing block device. To select the scheduler, use the following
471 command form where
472 device
473 is the device (e.g. sda, sdb, and so forth):
474 ::
475
476 $ sudo sh -c “echo cfq > /sys/block/device/queu/scheduler
477
478
479BB_TASK_NICE_LEVEL
480 Allows specific tasks to change their priority (i.e. nice level).
481
482 You can use this variable in combination with task overrides to raise
483 or lower priorities of specific tasks. For example, on the `Yocto
484 Project <http://www.yoctoproject.org>`__ autobuilder, QEMU emulation
485 in images is given a higher priority as compared to build tasks to
486 ensure that images do not suffer timeouts on loaded systems.
487
488BB_TASKHASH
489 Within an executing task, this variable holds the hash of the task as
490 returned by the currently enabled signature generator.
491
492BB_VERBOSE_LOGS
493 Controls how verbose BitBake is during builds. If set, shell scripts
494 echo commands and shell script output appears on standard out
495 (stdout).
496
497BB_WORKERCONTEXT
498 Specifies if the current context is executing a task. BitBake sets
499 this variable to "1" when a task is being executed. The value is not
500 set when the task is in server context during parsing or event
501 handling.
502
503BBCLASSEXTEND
504 Allows you to extend a recipe so that it builds variants of the
505 software. Some examples of these variants for recipes from the
506 OpenEmbedded-Core metadata are "natives" such as ``quilt-native``,
507 which is a copy of Quilt built to run on the build system; "crosses"
508 such as ``gcc-cross``, which is a compiler built to run on the build
509 machine but produces binaries that run on the target ``MACHINE``;
510 "nativesdk", which targets the SDK machine instead of ``MACHINE``;
511 and "mulitlibs" in the form "``multilib:``\ multilib_name".
512
513 To build a different variant of the recipe with a minimal amount of
514 code, it usually is as simple as adding the variable to your recipe.
515 Here are two examples. The "native" variants are from the
516 OpenEmbedded-Core metadata: BBCLASSEXTEND =+ "native nativesdk"
517 BBCLASSEXTEND =+ "multilib:multilib_name"
518
519 .. note::
520
521 Internally, the ``BBCLASSEXTEND`` mechanism generates recipe
522 variants by rewriting variable values and applying overrides such
523 as ``_class-native``. For example, to generate a native version of
524 a recipe, a ```DEPENDS`` <#var-bb-DEPENDS>`__ on "foo" is
525 rewritten to a ``DEPENDS`` on "foo-native".
526
527 Even when using ``BBCLASSEXTEND``, the recipe is only parsed once.
528 Parsing once adds some limitations. For example, it is not
529 possible to include a different file depending on the variant,
530 since ``include`` statements are processed when the recipe is
531 parsed.
532
533BBDEBUG
534 Sets the BitBake debug output level to a specific value as
535 incremented by the ``-D`` command line option.
536
537 .. note::
538
539 You must set this variable in the external environment in order
540 for it to work.
541
542BBFILE_COLLECTIONS
543 Lists the names of configured layers. These names are used to find
544 the other ``BBFILE_*`` variables. Typically, each layer appends its
545 name to this variable in its ``conf/layer.conf`` file.
546
547BBFILE_PATTERN
548 Variable that expands to match files from
549 ```BBFILES`` <#var-bb-BBFILES>`__ in a particular layer. This
550 variable is used in the ``conf/layer.conf`` file and must be suffixed
551 with the name of the specific layer (e.g.
552 ``BBFILE_PATTERN_emenlow``).
553
554BBFILE_PRIORITY
555 Assigns the priority for recipe files in each layer.
556
557 This variable is useful in situations where the same recipe appears
558 in more than one layer. Setting this variable allows you to
559 prioritize a layer against other layers that contain the same recipe
560 - effectively letting you control the precedence for the multiple
561 layers. The precedence established through this variable stands
562 regardless of a recipe's version (```PV`` <#var-bb-PV>`__ variable).
563 For example, a layer that has a recipe with a higher ``PV`` value but
564 for which the ``BBFILE_PRIORITY`` is set to have a lower precedence
565 still has a lower precedence.
566
567 A larger value for the ``BBFILE_PRIORITY`` variable results in a
568 higher precedence. For example, the value 6 has a higher precedence
569 than the value 5. If not specified, the ``BBFILE_PRIORITY`` variable
570 is set based on layer dependencies (see the ``LAYERDEPENDS`` variable
571 for more information. The default priority, if unspecified for a
572 layer with no dependencies, is the lowest defined priority + 1 (or 1
573 if no priorities are defined).
574
575 .. tip::
576
577 You can use the command
578 bitbake-layers show-layers
579 to list all configured layers along with their priorities.
580
581BBFILES
582 A space-separated list of recipe files BitBake uses to build
583 software.
584
585 When specifying recipe files, you can pattern match using Python's
586 ```glob`` <https://docs.python.org/3/library/glob.html>`__ syntax.
587 For details on the syntax, see the documentation by following the
588 previous link.
589
590BBINCLUDED
591 Contains a space-separated list of all of all files that BitBake's
592 parser included during parsing of the current file.
593
594BBINCLUDELOGS
595 If set to a value, enables printing the task log when reporting a
596 failed task.
597
598BBINCLUDELOGS_LINES
599 If ```BBINCLUDELOGS`` <#var-bb-BBINCLUDELOGS>`__ is set, specifies
600 the maximum number of lines from the task log file to print when
601 reporting a failed task. If you do not set ``BBINCLUDELOGS_LINES``,
602 the entire log is printed.
603
604BBLAYERS
605 Lists the layers to enable during the build. This variable is defined
606 in the ``bblayers.conf`` configuration file in the build directory.
607 Here is an example: BBLAYERS = " \\ /home/scottrif/poky/meta \\
608 /home/scottrif/poky/meta-yocto \\ /home/scottrif/poky/meta-yocto-bsp
609 \\ /home/scottrif/poky/meta-mykernel \\ " This example enables four
610 layers, one of which is a custom, user-defined layer named
611 ``meta-mykernel``.
612
613BBLAYERS_FETCH_DIR
614 Sets the base location where layers are stored. This setting is used
615 in conjunction with ``bitbake-layers layerindex-fetch`` and tells
616 ``bitbake-layers`` where to place the fetched layers.
617
618BBMASK
619 Prevents BitBake from processing recipes and recipe append files.
620
621 You can use the ``BBMASK`` variable to "hide" these ``.bb`` and
622 ``.bbappend`` files. BitBake ignores any recipe or recipe append
623 files that match any of the expressions. It is as if BitBake does not
624 see them at all. Consequently, matching files are not parsed or
625 otherwise used by BitBake.
626
627 The values you provide are passed to Python's regular expression
628 compiler. Consequently, the syntax follows Python's Regular
629 Expression (re) syntax. The expressions are compared against the full
630 paths to the files. For complete syntax information, see Python's
631 documentation at ` <http://docs.python.org/3/library/re.html#re>`__.
632
633 The following example uses a complete regular expression to tell
634 BitBake to ignore all recipe and recipe append files in the
635 ``meta-ti/recipes-misc/`` directory: BBMASK = "meta-ti/recipes-misc/"
636 If you want to mask out multiple directories or recipes, you can
637 specify multiple regular expression fragments. This next example
638 masks out multiple directories and individual recipes: BBMASK +=
639 "/meta-ti/recipes-misc/ meta-ti/recipes-ti/packagegroup/" BBMASK +=
640 "/meta-oe/recipes-support/" BBMASK += "/meta-foo/.*/openldap" BBMASK
641 += "opencv.*\.bbappend" BBMASK += "lzma"
642
643 .. note::
644
645 When specifying a directory name, use the trailing slash character
646 to ensure you match just that directory name.
647
648BBMULTICONFIG
649 Enables BitBake to perform multiple configuration builds and lists
650 each separate configuration (multiconfig). You can use this variable
651 to cause BitBake to build multiple targets where each target has a
652 separate configuration. Define ``BBMULTICONFIG`` in your
653 ``conf/local.conf`` configuration file.
654
655 As an example, the following line specifies three multiconfigs, each
656 having a separate configuration file: BBMULTIFONFIG = "configA
657 configB configC" Each configuration file you use must reside in the
658 build directory within a directory named ``conf/multiconfig`` (e.g.
659 build_directory\ ``/conf/multiconfig/configA.conf``).
660
661 For information on how to use ``BBMULTICONFIG`` in an environment
662 that supports building targets with multiple configurations, see the
663 "`Executing a Multiple Configuration
664 Build <#executing-a-multiple-configuration-build>`__" section.
665
666BBPATH
667 Used by BitBake to locate class (``.bbclass``) and configuration
668 (``.conf``) files. This variable is analogous to the ``PATH``
669 variable.
670
671 If you run BitBake from a directory outside of the build directory,
672 you must be sure to set ``BBPATH`` to point to the build directory.
673 Set the variable as you would any environment variable and then run
674 BitBake: $ BBPATH="build_directory" $ export BBPATH $ bitbake target
675
676BBSERVER
677 Points to the server that runs memory-resident BitBake. The variable
678 is only used when you employ memory-resident BitBake.
679
680BBTARGETS
681 Allows you to use a configuration file to add to the list of
682 command-line target recipes you want to build.
683
684BBVERSIONS
685 Allows a single recipe to build multiple versions of a project from a
686 single recipe file. You also able to specify conditional metadata
687 using the ```OVERRIDES`` <#var-bb-OVERRIDES>`__ mechanism for a
688 single version or for an optionally named range of versions.
689
690 For more information on ``BBVERSIONS``, see the "`Variants - Class
691 Extension Mechanism <#variants-class-extension-mechanism>`__"
692 section.
693
694BITBAKE_UI
695 Used to specify the UI module to use when running BitBake. Using this
696 variable is equivalent to using the ``-u`` command-line option.
697
698 .. note::
699
700 You must set this variable in the external environment in order
701 for it to work.
702
703BUILDNAME
704 A name assigned to the build. The name defaults to a datetime stamp
705 of when the build was started but can be defined by the metadata.
706
707BZRDIR
708 The directory in which files checked out of a Bazaar system are
709 stored.
710
711CACHE
712 Specifies the directory BitBake uses to store a cache of the metadata
713 so it does not need to be parsed every time BitBake is started.
714
715CVSDIR
716 The directory in which files checked out under the CVS system are
717 stored.
718
719DEFAULT_PREFERENCE
720 Specifies a weak bias for recipe selection priority.
721
722 The most common usage of this is variable is to set it to "-1" within
723 a recipe for a development version of a piece of software. Using the
724 variable in this way causes the stable version of the recipe to build
725 by default in the absence of ``PREFERRED_VERSION`` being used to
726 build the development version.
727
728 .. note::
729
730 The bias provided by
731 DEFAULT_PREFERENCE
732 is weak and is overridden by
733 BBFILE_PRIORITY
734 if that variable is different between two layers that contain
735 different versions of the same recipe.
736
737DEPENDS
738 Lists a recipe's build-time dependencies (i.e. other recipe files).
739
740 Consider this simple example for two recipes named "a" and "b" that
741 produce similarly named packages. In this example, the ``DEPENDS``
742 statement appears in the "a" recipe: DEPENDS = "b" Here, the
743 dependency is such that the ``do_configure`` task for recipe "a"
744 depends on the ``do_populate_sysroot`` task of recipe "b". This means
745 anything that recipe "b" puts into sysroot is available when recipe
746 "a" is configuring itself.
747
748 For information on runtime dependencies, see the
749 ```RDEPENDS`` <#var-bb-RDEPENDS>`__ variable.
750
751DESCRIPTION
752 A long description for the recipe.
753
754DL_DIR
755 The central download directory used by the build process to store
756 downloads. By default, ``DL_DIR`` gets files suitable for mirroring
757 for everything except Git repositories. If you want tarballs of Git
758 repositories, use the
759 ```BB_GENERATE_MIRROR_TARBALLS`` <#var-bb-BB_GENERATE_MIRROR_TARBALLS>`__
760 variable.
761
762EXCLUDE_FROM_WORLD
763 Directs BitBake to exclude a recipe from world builds (i.e.
764 ``bitbake world``). During world builds, BitBake locates, parses and
765 builds all recipes found in every layer exposed in the
766 ``bblayers.conf`` configuration file.
767
768 To exclude a recipe from a world build using this variable, set the
769 variable to "1" in the recipe.
770
771 .. note::
772
773 Recipes added to
774 EXCLUDE_FROM_WORLD
775 may still be built during a world build in order to satisfy
776 dependencies of other recipes. Adding a recipe to
777 EXCLUDE_FROM_WORLD
778 only ensures that the recipe is not explicitly added to the list
779 of build targets in a world build.
780
781FAKEROOT
782 Contains the command to use when running a shell script in a fakeroot
783 environment. The ``FAKEROOT`` variable is obsolete and has been
784 replaced by the other ``FAKEROOT*`` variables. See these entries in
785 the glossary for more information.
786
787FAKEROOTBASEENV
788 Lists environment variables to set when executing the command defined
789 by ```FAKEROOTCMD`` <#var-bb-FAKEROOTCMD>`__ that starts the
790 bitbake-worker process in the fakeroot environment.
791
792FAKEROOTCMD
793 Contains the command that starts the bitbake-worker process in the
794 fakeroot environment.
795
796FAKEROOTDIRS
797 Lists directories to create before running a task in the fakeroot
798 environment.
799
800FAKEROOTENV
801 Lists environment variables to set when running a task in the
802 fakeroot environment. For additional information on environment
803 variables and the fakeroot environment, see the
804 ```FAKEROOTBASEENV`` <#var-bb-FAKEROOTBASEENV>`__ variable.
805
806FAKEROOTNOENV
807 Lists environment variables to set when running a task that is not in
808 the fakeroot environment. For additional information on environment
809 variables and the fakeroot environment, see the
810 ```FAKEROOTENV`` <#var-bb-FAKEROOTENV>`__ variable.
811
812FETCHCMD
813 Defines the command the BitBake fetcher module executes when running
814 fetch operations. You need to use an override suffix when you use the
815 variable (e.g. ``FETCHCMD_git`` or ``FETCHCMD_svn``).
816
817FILE
818 Points at the current file. BitBake sets this variable during the
819 parsing process to identify the file being parsed. BitBake also sets
820 this variable when a recipe is being executed to identify the recipe
821 file.
822
823FILESPATH
824 Specifies directories BitBake uses when searching for patches and
825 files. The "local" fetcher module uses these directories when
826 handling ``file://`` URLs. The variable behaves like a shell ``PATH``
827 environment variable. The value is a colon-separated list of
828 directories that are searched left-to-right in order.
829
830GITDIR
831 The directory in which a local copy of a Git repository is stored
832 when it is cloned.
833
834HGDIR
835 The directory in which files checked out of a Mercurial system are
836 stored.
837
838HOMEPAGE
839 Website where more information about the software the recipe is
840 building can be found.
841
842INHERIT
843 Causes the named class or classes to be inherited globally. Anonymous
844 functions in the class or classes are not executed for the base
845 configuration and in each individual recipe. The OpenEmbedded build
846 system ignores changes to ``INHERIT`` in individual recipes.
847
848 For more information on ``INHERIT``, see the "```INHERIT``
849 Configuration Directive <#inherit-configuration-directive>`__"
850 section.
851
852LAYERDEPENDS
853 Lists the layers, separated by spaces, upon which this recipe
854 depends. Optionally, you can specify a specific layer version for a
855 dependency by adding it to the end of the layer name with a colon,
856 (e.g. "anotherlayer:3" to be compared against
857 ```LAYERVERSION`` <#var-bb-LAYERVERSION>`__\ ``_anotherlayer`` in
858 this case). BitBake produces an error if any dependency is missing or
859 the version numbers do not match exactly (if specified).
860
861 You use this variable in the ``conf/layer.conf`` file. You must also
862 use the specific layer name as a suffix to the variable (e.g.
863 ``LAYERDEPENDS_mylayer``).
864
865LAYERDIR
866 When used inside the ``layer.conf`` configuration file, this variable
867 provides the path of the current layer. This variable is not
868 available outside of ``layer.conf`` and references are expanded
869 immediately when parsing of the file completes.
870
871LAYERDIR_RE
872 When used inside the ``layer.conf`` configuration file, this variable
873 provides the path of the current layer, escaped for use in a regular
874 expression (```BBFILE_PATTERN`` <#var-bb-BBFILE_PATTERN>`__). This
875 variable is not available outside of ``layer.conf`` and references
876 are expanded immediately when parsing of the file completes.
877
878LAYERVERSION
879 Optionally specifies the version of a layer as a single number. You
880 can use this variable within
881 ```LAYERDEPENDS`` <#var-bb-LAYERDEPENDS>`__ for another layer in
882 order to depend on a specific version of the layer.
883
884 You use this variable in the ``conf/layer.conf`` file. You must also
885 use the specific layer name as a suffix to the variable (e.g.
886 ``LAYERDEPENDS_mylayer``).
887
888LICENSE
889 The list of source licenses for the recipe.
890
891MIRRORS
892 Specifies additional paths from which BitBake gets source code. When
893 the build system searches for source code, it first tries the local
894 download directory. If that location fails, the build system tries
895 locations defined by ```PREMIRRORS`` <#var-bb-PREMIRRORS>`__, the
896 upstream source, and then locations specified by ``MIRRORS`` in that
897 order.
898
899MULTI_PROVIDER_WHITELIST
900 Allows you to suppress BitBake warnings caused when building two
901 separate recipes that provide the same output.
902
903 BitBake normally issues a warning when building two different recipes
904 where each provides the same output. This scenario is usually
905 something the user does not want. However, cases do exist where it
906 makes sense, particularly in the ``virtual/*`` namespace. You can use
907 this variable to suppress BitBake's warnings.
908
909 To use the variable, list provider names (e.g. recipe names,
910 ``virtual/kernel``, and so forth).
911
912OVERRIDES
913 BitBake uses ``OVERRIDES`` to control what variables are overridden
914 after BitBake parses recipes and configuration files.
915
916 Following is a simple example that uses an overrides list based on
917 machine architectures: OVERRIDES = "arm:x86:mips:powerpc" You can
918 find information on how to use ``OVERRIDES`` in the "`Conditional
919 Syntax (Overrides) <#conditional-syntax-overrides>`__" section.
920
921P4DIR
922 The directory in which a local copy of a Perforce depot is stored
923 when it is fetched.
924
925PACKAGES
926 The list of packages the recipe creates.
927
928PACKAGES_DYNAMIC
929 A promise that your recipe satisfies runtime dependencies for
930 optional modules that are found in other recipes.
931 ``PACKAGES_DYNAMIC`` does not actually satisfy the dependencies, it
932 only states that they should be satisfied. For example, if a hard,
933 runtime dependency (```RDEPENDS`` <#var-bb-RDEPENDS>`__) of another
934 package is satisfied during the build through the
935 ``PACKAGES_DYNAMIC`` variable, but a package with the module name is
936 never actually produced, then the other package will be broken.
937
938PE
939 The epoch of the recipe. By default, this variable is unset. The
940 variable is used to make upgrades possible when the versioning scheme
941 changes in some backwards incompatible way.
942
943PERSISTENT_DIR
944 Specifies the directory BitBake uses to store data that should be
945 preserved between builds. In particular, the data stored is the data
946 that uses BitBake's persistent data API and the data used by the PR
947 Server and PR Service.
948
949PF
950 Specifies the recipe or package name and includes all version and
951 revision numbers (i.e. ``eglibc-2.13-r20+svnr15508/`` and
952 ``bash-4.2-r1/``).
953
954PN
955 The recipe name.
956
957PR
958 The revision of the recipe.
959
960PREFERRED_PROVIDER
961 Determines which recipe should be given preference when multiple
962 recipes provide the same item. You should always suffix the variable
963 with the name of the provided item, and you should set it to the
964 ```PN`` <#var-bb-PN>`__ of the recipe to which you want to give
965 precedence. Some examples: PREFERRED_PROVIDER_virtual/kernel ?=
966 "linux-yocto" PREFERRED_PROVIDER_virtual/xserver = "xserver-xf86"
967 PREFERRED_PROVIDER_virtual/libgl ?= "mesa"
968
969PREFERRED_PROVIDERS
970 Determines which recipe should be given preference for cases where
971 multiple recipes provide the same item. Functionally,
972 ``PREFERRED_PROVIDERS`` is identical to
973 ```PREFERRED_PROVIDER`` <#var-bb-PREFERRED_PROVIDER>`__. However, the
974 ``PREFERRED_PROVIDERS`` variable lets you define preferences for
975 multiple situations using the following form: PREFERRED_PROVIDERS =
976 "xxx:yyy aaa:bbb ..." This form is a convenient replacement for the
977 following: PREFERRED_PROVIDER_xxx = "yyy" PREFERRED_PROVIDER_aaa =
978 "bbb"
979
980PREFERRED_VERSION
981 If there are multiple versions of recipes available, this variable
982 determines which recipe should be given preference. You must always
983 suffix the variable with the ```PN`` <#var-bb-PN>`__ you want to
984 select, and you should set ```PV`` <#var-bb-PV>`__ accordingly for
985 precedence.
986
987 The ``PREFERRED_VERSION`` variable supports limited wildcard use
988 through the "``%``" character. You can use the character to match any
989 number of characters, which can be useful when specifying versions
990 that contain long revision numbers that potentially change. Here are
991 two examples: PREFERRED_VERSION_python = "2.7.3"
992 PREFERRED_VERSION_linux-yocto = "4.12%"
993
994 .. note::
995
996 The use of the "
997 %
998 " character is limited in that it only works at the end of the
999 string. You cannot use the wildcard character in any other
1000 location of the string.
1001
1002PREMIRRORS
1003 Specifies additional paths from which BitBake gets source code. When
1004 the build system searches for source code, it first tries the local
1005 download directory. If that location fails, the build system tries
1006 locations defined by ``PREMIRRORS``, the upstream source, and then
1007 locations specified by ```MIRRORS`` <#var-bb-MIRRORS>`__ in that
1008 order.
1009
1010 Typically, you would add a specific server for the build system to
1011 attempt before any others by adding something like the following to
1012 your configuration: PREMIRRORS_prepend = "\\ git://.*/.\*
1013 http://www.yoctoproject.org/sources/ \\n \\ ftp://.*/.\*
1014 http://www.yoctoproject.org/sources/ \\n \\ http://.*/.\*
1015 http://www.yoctoproject.org/sources/ \\n \\ https://.*/.\*
1016 http://www.yoctoproject.org/sources/ \\n" These changes cause the
1017 build system to intercept Git, FTP, HTTP, and HTTPS requests and
1018 direct them to the ``http://`` sources mirror. You can use
1019 ``file://`` URLs to point to local directories or network shares as
1020 well.
1021
1022PROVIDES
1023 A list of aliases by which a particular recipe can be known. By
1024 default, a recipe's own ``PN`` is implicitly already in its
1025 ``PROVIDES`` list. If a recipe uses ``PROVIDES``, the additional
1026 aliases are synonyms for the recipe and can be useful satisfying
1027 dependencies of other recipes during the build as specified by
1028 ``DEPENDS``.
1029
1030 Consider the following example ``PROVIDES`` statement from a recipe
1031 file ``libav_0.8.11.bb``: PROVIDES += "libpostproc" The ``PROVIDES``
1032 statement results in the "libav" recipe also being known as
1033 "libpostproc".
1034
1035 In addition to providing recipes under alternate names, the
1036 ``PROVIDES`` mechanism is also used to implement virtual targets. A
1037 virtual target is a name that corresponds to some particular
1038 functionality (e.g. a Linux kernel). Recipes that provide the
1039 functionality in question list the virtual target in ``PROVIDES``.
1040 Recipes that depend on the functionality in question can include the
1041 virtual target in ```DEPENDS`` <#var-bb-DEPENDS>`__ to leave the
1042 choice of provider open.
1043
1044 Conventionally, virtual targets have names on the form
1045 "virtual/function" (e.g. "virtual/kernel"). The slash is simply part
1046 of the name and has no syntactical significance.
1047
1048PRSERV_HOST
1049 The network based ```PR`` <#var-bb-PR>`__ service host and port.
1050
1051 Following is an example of how the ``PRSERV_HOST`` variable is set:
1052 PRSERV_HOST = "localhost:0" You must set the variable if you want to
1053 automatically start a local PR service. You can set ``PRSERV_HOST``
1054 to other values to use a remote PR service.
1055
1056PV
1057 The version of the recipe.
1058
1059RDEPENDS
1060 Lists a package's runtime dependencies (i.e. other packages) that
1061 must be installed in order for the built package to run correctly. If
1062 a package in this list cannot be found during the build, you will get
1063 a build error.
1064
1065 Because the ``RDEPENDS`` variable applies to packages being built,
1066 you should always use the variable in a form with an attached package
1067 name. For example, suppose you are building a development package
1068 that depends on the ``perl`` package. In this case, you would use the
1069 following ``RDEPENDS`` statement: RDEPENDS_${PN}-dev += "perl" In the
1070 example, the development package depends on the ``perl`` package.
1071 Thus, the ``RDEPENDS`` variable has the ``${PN}-dev`` package name as
1072 part of the variable.
1073
1074 BitBake supports specifying versioned dependencies. Although the
1075 syntax varies depending on the packaging format, BitBake hides these
1076 differences from you. Here is the general syntax to specify versions
1077 with the ``RDEPENDS`` variable: RDEPENDS_${PN} = "package (operator
1078 version)" For ``operator``, you can specify the following: = < > <=
1079 >= For example, the following sets up a dependency on version 1.2 or
1080 greater of the package ``foo``: RDEPENDS_${PN} = "foo (>= 1.2)"
1081
1082 For information on build-time dependencies, see the
1083 ```DEPENDS`` <#var-bb-DEPENDS>`__ variable.
1084
1085REPODIR
1086 The directory in which a local copy of a ``google-repo`` directory is
1087 stored when it is synced.
1088
1089RPROVIDES
1090 A list of package name aliases that a package also provides. These
1091 aliases are useful for satisfying runtime dependencies of other
1092 packages both during the build and on the target (as specified by
1093 ``RDEPENDS``).
1094
1095 As with all package-controlling variables, you must always use the
1096 variable in conjunction with a package name override. Here is an
1097 example: RPROVIDES_${PN} = "widget-abi-2"
1098
1099RRECOMMENDS
1100 A list of packages that extends the usability of a package being
1101 built. The package being built does not depend on this list of
1102 packages in order to successfully build, but needs them for the
1103 extended usability. To specify runtime dependencies for packages, see
1104 the ``RDEPENDS`` variable.
1105
1106 BitBake supports specifying versioned recommends. Although the syntax
1107 varies depending on the packaging format, BitBake hides these
1108 differences from you. Here is the general syntax to specify versions
1109 with the ``RRECOMMENDS`` variable: RRECOMMENDS_${PN} = "package
1110 (operator version)" For ``operator``, you can specify the following:
1111 = < > <= >= For example, the following sets up a recommend on version
1112 1.2 or greater of the package ``foo``: RRECOMMENDS_${PN} = "foo (>=
1113 1.2)"
1114
1115SECTION
1116 The section in which packages should be categorized.
1117
1118SRC_URI
1119 The list of source files - local or remote. This variable tells
1120 BitBake which bits to pull for the build and how to pull them. For
1121 example, if the recipe or append file needs to fetch a single tarball
1122 from the Internet, the recipe or append file uses a ``SRC_URI`` entry
1123 that specifies that tarball. On the other hand, if the recipe or
1124 append file needs to fetch a tarball and include a custom file, the
1125 recipe or append file needs an ``SRC_URI`` variable that specifies
1126 all those sources.
1127
1128 The following list explains the available URI protocols:
1129
1130 - *``file://`` -* Fetches files, which are usually files shipped
1131 with the metadata, from the local machine. The path is relative to
1132 the ```FILESPATH`` <#var-bb-FILESPATH>`__ variable.
1133
1134 - *``bzr://`` -* Fetches files from a Bazaar revision control
1135 repository.
1136
1137 - *``git://`` -* Fetches files from a Git revision control
1138 repository.
1139
1140 - *``osc://`` -* Fetches files from an OSC (OpenSUSE Build service)
1141 revision control repository.
1142
1143 - *``repo://`` -* Fetches files from a repo (Git) repository.
1144
1145 - *``http://`` -* Fetches files from the Internet using HTTP.
1146
1147 - *``https://`` -* Fetches files from the Internet using HTTPS.
1148
1149 - *``ftp://`` -* Fetches files from the Internet using FTP.
1150
1151 - *``cvs://`` -* Fetches files from a CVS revision control
1152 repository.
1153
1154 - *``hg://`` -* Fetches files from a Mercurial (``hg``) revision
1155 control repository.
1156
1157 - *``p4://`` -* Fetches files from a Perforce (``p4``) revision
1158 control repository.
1159
1160 - *``ssh://`` -* Fetches files from a secure shell.
1161
1162 - *``svn://`` -* Fetches files from a Subversion (``svn``) revision
1163 control repository.
1164
1165 Here are some additional options worth mentioning:
1166
1167 - *``unpack`` -* Controls whether or not to unpack the file if it is
1168 an archive. The default action is to unpack the file.
1169
1170 - *``subdir`` -* Places the file (or extracts its contents) into the
1171 specified subdirectory. This option is useful for unusual tarballs
1172 or other archives that do not have their files already in a
1173 subdirectory within the archive.
1174
1175 - *``name`` -* Specifies a name to be used for association with
1176 ``SRC_URI`` checksums when you have more than one file specified
1177 in ``SRC_URI``.
1178
1179 - *``downloadfilename`` -* Specifies the filename used when storing
1180 the downloaded file.
1181
1182SRCDATE
1183 The date of the source code used to build the package. This variable
1184 applies only if the source was fetched from a Source Code Manager
1185 (SCM).
1186
1187SRCREV
1188 The revision of the source code used to build the package. This
1189 variable applies only when using Subversion, Git, Mercurial and
1190 Bazaar. If you want to build a fixed revision and you want to avoid
1191 performing a query on the remote repository every time BitBake parses
1192 your recipe, you should specify a ``SRCREV`` that is a full revision
1193 identifier and not just a tag.
1194
1195SRCREV_FORMAT
1196 Helps construct valid ```SRCREV`` <#var-bb-SRCREV>`__ values when
1197 multiple source controlled URLs are used in
1198 ```SRC_URI`` <#var-bb-SRC_URI>`__.
1199
1200 The system needs help constructing these values under these
1201 circumstances. Each component in the ``SRC_URI`` is assigned a name
1202 and these are referenced in the ``SRCREV_FORMAT`` variable. Consider
1203 an example with URLs named "machine" and "meta". In this case,
1204 ``SRCREV_FORMAT`` could look like "machine_meta" and those names
1205 would have the SCM versions substituted into each position. Only one
1206 ``AUTOINC`` placeholder is added and if needed. And, this placeholder
1207 is placed at the start of the returned string.
1208
1209STAMP
1210 Specifies the base path used to create recipe stamp files. The path
1211 to an actual stamp file is constructed by evaluating this string and
1212 then appending additional information.
1213 194
1214STAMPCLEAN 195 BB_ENV_EXTRAWHITE
1215 Specifies the base path used to create recipe stamp files. Unlike the 196 Specifies an additional set of variables to allow through (whitelist)
1216 ```STAMP`` <#var-bb-STAMP>`__ variable, ``STAMPCLEAN`` can contain 197 from the external environment into BitBake's datastore. This list of
1217 wildcards to match the range of files a clean operation should 198 variables are on top of the internal list set in
1218 remove. BitBake uses a clean operation to remove any other stamps it 199 ```BB_ENV_WHITELIST`` <#var-bb-BB_ENV_WHITELIST>`__.
1219 should be removing when creating a new stamp.
1220 200
1221SUMMARY 201 .. note::
1222 A short summary for the recipe, which is 72 characters or less. 202
203 You must set this variable in the external environment in order
204 for it to work.
205
206 BB_FETCH_PREMIRRORONLY
207 When set to "1", causes BitBake's fetcher module to only search
208 ```PREMIRRORS`` <#var-bb-PREMIRRORS>`__ for files. BitBake will not
209 search the main ```SRC_URI`` <#var-bb-SRC_URI>`__ or
210 ```MIRRORS`` <#var-bb-MIRRORS>`__.
211
212 BB_FILENAME
213 Contains the filename of the recipe that owns the currently running
214 task. For example, if the ``do_fetch`` task that resides in the
215 ``my-recipe.bb`` is executing, the ``BB_FILENAME`` variable contains
216 "/foo/path/my-recipe.bb".
217
218 BBFILES_DYNAMIC
219 Activates content depending on presence of identified layers. You
220 identify the layers by the collections that the layers define.
221
222 Use the ``BBFILES_DYNAMIC`` variable to avoid ``.bbappend`` files whose
223 corresponding ``.bb`` file is in a layer that attempts to modify other
224 layers through ``.bbappend`` but does not want to introduce a hard
225 dependency on those other layers.
226
227 Additionally you can prefix the rule with "!" to add ``.bbappend`` and
228 ``.bb`` files in case a layer is not present. Use this avoid hard
229 dependency on those other layers.
230
231 Use the following form for ``BBFILES_DYNAMIC``: ::
232
233 collection_name:filename_pattern
234
235 The following example identifies two collection names and two filename
236 patterns: ::
237
238 BBFILES_DYNAMIC += "\
239 clang-layer:${LAYERDIR}/bbappends/meta-clang/*/*/*.bbappend \
240 core:${LAYERDIR}/bbappends/openembedded-core/meta/*/*/*.bbappend \
241 "
242
243 When the collection name is prefixed with "!" it will add the file pattern in case
244 the layer is absent: ::
245
246 BBFILES_DYNAMIC += "\
247 !clang-layer:${LAYERDIR}/backfill/meta-clang/*/*/*.bb \
248 "
249
250 This next example shows an error message that occurs because invalid
251 entries are found, which cause parsing to abort: ::
252
253 ERROR: BBFILES_DYNAMIC entries must be of the form {!}<collection name>:<filename pattern>, not:
254 /work/my-layer/bbappends/meta-security-isafw/*/*/*.bbappend
255 /work/my-layer/bbappends/openembedded-core/meta/*/*/*.bbappend
256
257 BB_GENERATE_MIRROR_TARBALLS
258 Causes tarballs of the Git repositories, including the Git metadata,
259 to be placed in the ```DL_DIR`` <#var-bb-DL_DIR>`__ directory. Anyone
260 wishing to create a source mirror would want to enable this variable.
261
262 For performance reasons, creating and placing tarballs of the Git
263 repositories is not the default action by BitBake.
264 BB_GENERATE_MIRROR_TARBALLS = "1"
265
266 BB_HASHCONFIG_WHITELIST
267 Lists variables that are excluded from base configuration checksum,
268 which is used to determine if the cache can be reused.
269
270 One of the ways BitBake determines whether to re-parse the main
271 metadata is through checksums of the variables in the datastore of
272 the base configuration data. There are variables that you typically
273 want to exclude when checking whether or not to re-parse and thus
274 rebuild the cache. As an example, you would usually exclude ``TIME``
275 and ``DATE`` because these variables are always changing. If you did
276 not exclude them, BitBake would never reuse the cache.
277
278 BB_HASHBASE_WHITELIST
279 Lists variables that are excluded from checksum and dependency data.
280 Variables that are excluded can therefore change without affecting
281 the checksum mechanism. A common example would be the variable for
282 the path of the build. BitBake's output should not (and usually does
283 not) depend on the directory in which it was built.
284
285 BB_HASHCHECK_FUNCTION
286 Specifies the name of the function to call during the "setscene" part
287 of the task's execution in order to validate the list of task hashes.
288 The function returns the list of setscene tasks that should be
289 executed.
290
291 At this point in the execution of the code, the objective is to
292 quickly verify if a given setscene function is likely to work or not.
293 It's easier to check the list of setscene functions in one pass than
294 to call many individual tasks. The returned list need not be
295 completely accurate. A given setscene task can still later fail.
296 However, the more accurate the data returned, the more efficient the
297 build will be.
298
299 BB_INVALIDCONF
300 Used in combination with the ``ConfigParsed`` event to trigger
301 re-parsing the base metadata (i.e. all the recipes). The
302 ``ConfigParsed`` event can set the variable to trigger the re-parse.
303 You must be careful to avoid recursive loops with this functionality.
304
305 BB_LOGCONFIG
306 Specifies the name of a config file that contains the user logging
307 configuration. See `Logging <#logging>`__ for additional information
308
309 BB_LOGFMT
310 Specifies the name of the log files saved into
311 ``${``\ ```T`` <#var-bb-T>`__\ ``}``. By default, the ``BB_LOGFMT``
312 variable is undefined and the log file names get created using the
313 following form: log.{task}.{pid} If you want to force log files to
314 take a specific name, you can set this variable in a configuration
315 file.
316
317 BB_NICE_LEVEL
318 Allows BitBake to run at a specific priority (i.e. nice level).
319 System permissions usually mean that BitBake can reduce its priority
320 but not raise it again. See
321 ```BB_TASK_NICE_LEVEL`` <#var-bb-BB_TASK_NICE_LEVEL>`__ for
322 additional information.
323
324 BB_NO_NETWORK
325 Disables network access in the BitBake fetcher modules. With this
326 access disabled, any command that attempts to access the network
327 becomes an error.
328
329 Disabling network access is useful for testing source mirrors,
330 running builds when not connected to the Internet, and when operating
331 in certain kinds of firewall environments.
332
333 BB_NUMBER_THREADS
334 The maximum number of tasks BitBake should run in parallel at any one
335 time. If your host development system supports multiple cores, a good
336 rule of thumb is to set this variable to twice the number of cores.
337
338 BB_NUMBER_PARSE_THREADS
339 Sets the number of threads BitBake uses when parsing. By default, the
340 number of threads is equal to the number of cores on the system.
341
342 BB_ORIGENV
343 Contains a copy of the original external environment in which BitBake
344 was run. The copy is taken before any whitelisted variable values are
345 filtered into BitBake's datastore.
346
347 .. note::
348
349 The contents of this variable is a datastore object that can be
350 queried using the normal datastore operations.
351
352 BB_PRESERVE_ENV
353 Disables whitelisting and instead allows all variables through from
354 the external environment into BitBake's datastore.
355
356 .. note::
357
358 You must set this variable in the external environment in order
359 for it to work.
360
361 BB_RUNFMT
362 Specifies the name of the executable script files (i.e. run files)
363 saved into ``${``\ ```T`` <#var-bb-T>`__\ ``}``. By default, the
364 ``BB_RUNFMT`` variable is undefined and the run file names get
365 created using the following form: run.{task}.{pid} If you want to
366 force run files to take a specific name, you can set this variable in
367 a configuration file.
368
369 BB_RUNTASK
370 Contains the name of the currently executing task. The value includes
371 the "do_" prefix. For example, if the currently executing task is
372 ``do_config``, the value is "do_config".
373
374 BB_SCHEDULER
375 Selects the name of the scheduler to use for the scheduling of
376 BitBake tasks. Three options exist:
377
378 - *basic* - The basic framework from which everything derives. Using
379 this option causes tasks to be ordered numerically as they are
380 parsed.
381
382 - *speed* - Executes tasks first that have more tasks depending on
383 them. The "speed" option is the default.
384
385 - *completion* - Causes the scheduler to try to complete a given
386 recipe once its build has started.
387
388 BB_SCHEDULERS
389 Defines custom schedulers to import. Custom schedulers need to be
390 derived from the ``RunQueueScheduler`` class.
391
392 For information how to select a scheduler, see the
393 ```BB_SCHEDULER`` <#var-bb-BB_SCHEDULER>`__ variable.
394
395 BB_SETSCENE_DEPVALID
396 Specifies a function BitBake calls that determines whether BitBake
397 requires a setscene dependency to be met.
398
399 When running a setscene task, BitBake needs to know which
400 dependencies of that setscene task also need to be run. Whether
401 dependencies also need to be run is highly dependent on the metadata.
402 The function specified by this variable returns a "True" or "False"
403 depending on whether the dependency needs to be met.
404
405 BB_SETSCENE_VERIFY_FUNCTION2
406 Specifies a function to call that verifies the list of planned task
407 execution before the main task execution happens. The function is
408 called once BitBake has a list of setscene tasks that have run and
409 either succeeded or failed.
410
411 The function allows for a task list check to see if they make sense.
412 Even if BitBake was planning to skip a task, the returned value of
413 the function can force BitBake to run the task, which is necessary
414 under certain metadata defined circumstances.
415
416 BB_SIGNATURE_EXCLUDE_FLAGS
417 Lists variable flags (varflags) that can be safely excluded from
418 checksum and dependency data for keys in the datastore. When
419 generating checksum or dependency data for keys in the datastore, the
420 flags set against that key are normally included in the checksum.
421
422 For more information on varflags, see the "`Variable
423 Flags <#variable-flags>`__" section.
424
425 BB_SIGNATURE_HANDLER
426 Defines the name of the signature handler BitBake uses. The signature
427 handler defines the way stamp files are created and handled, if and
428 how the signature is incorporated into the stamps, and how the
429 signature itself is generated.
430
431 A new signature handler can be added by injecting a class derived
432 from the ``SignatureGenerator`` class into the global namespace.
433
434 BB_SRCREV_POLICY
435 Defines the behavior of the fetcher when it interacts with source
436 control systems and dynamic source revisions. The
437 ``BB_SRCREV_POLICY`` variable is useful when working without a
438 network.
439
440 The variable can be set using one of two policies:
441
442 - *cache* - Retains the value the system obtained previously rather
443 than querying the source control system each time.
444
445 - *clear* - Queries the source controls system every time. With this
446 policy, there is no cache. The "clear" policy is the default.
447
448 BB_STAMP_POLICY
449 Defines the mode used for how timestamps of stamp files are compared.
450 You can set the variable to one of the following modes:
451
452 - *perfile* - Timestamp comparisons are only made between timestamps
453 of a specific recipe. This is the default mode.
454
455 - *full* - Timestamp comparisons are made for all dependencies.
456
457 - *whitelist* - Identical to "full" mode except timestamp
458 comparisons are made for recipes listed in the
459 ```BB_STAMP_WHITELIST`` <#var-bb-BB_STAMP_WHITELIST>`__ variable.
460
461 .. note::
462
463 Stamp policies are largely obsolete with the introduction of
464 setscene tasks.
465
466 BB_STAMP_WHITELIST
467 Lists files whose stamp file timestamps are compared when the stamp
468 policy mode is set to "whitelist". For information on stamp policies,
469 see the ```BB_STAMP_POLICY`` <#var-bb-BB_STAMP_POLICY>`__ variable.
470
471 BB_STRICT_CHECKSUM
472 Sets a more strict checksum mechanism for non-local URLs. Setting
473 this variable to a value causes BitBake to report an error if it
474 encounters a non-local URL that does not have at least one checksum
475 specified.
476
477 BB_TASK_IONICE_LEVEL
478 Allows adjustment of a task's Input/Output priority. During
479 Autobuilder testing, random failures can occur for tasks due to I/O
480 starvation. These failures occur during various QEMU runtime
481 timeouts. You can use the ``BB_TASK_IONICE_LEVEL`` variable to adjust
482 the I/O priority of these tasks.
483
484 .. note::
485
486 This variable works similarly to the
487 BB_TASK_NICE_LEVEL
488 variable except with a task's I/O priorities.
489
490 Set the variable as follows: BB_TASK_IONICE_LEVEL = "class.prio" For
491 class, the default value is "2", which is a best effort. You can use
492 "1" for realtime and "3" for idle. If you want to use realtime, you
493 must have superuser privileges.
494
495 For prio, you can use any value from "0", which is the highest
496 priority, to "7", which is the lowest. The default value is "4". You
497 do not need any special privileges to use this range of priority
498 values.
499
500 .. note::
501
502 In order for your I/O priority settings to take effect, you need
503 the Completely Fair Queuing (CFQ) Scheduler selected for the
504 backing block device. To select the scheduler, use the following
505 command form where
506 device
507 is the device (e.g. sda, sdb, and so forth):
508 ::
509
510 $ sudo sh -c “echo cfq > /sys/block/device/queu/scheduler
511
512
513 BB_TASK_NICE_LEVEL
514 Allows specific tasks to change their priority (i.e. nice level).
515
516 You can use this variable in combination with task overrides to raise
517 or lower priorities of specific tasks. For example, on the `Yocto
518 Project <http://www.yoctoproject.org>`__ autobuilder, QEMU emulation
519 in images is given a higher priority as compared to build tasks to
520 ensure that images do not suffer timeouts on loaded systems.
521
522 BB_TASKHASH
523 Within an executing task, this variable holds the hash of the task as
524 returned by the currently enabled signature generator.
525
526 BB_VERBOSE_LOGS
527 Controls how verbose BitBake is during builds. If set, shell scripts
528 echo commands and shell script output appears on standard out
529 (stdout).
530
531 BB_WORKERCONTEXT
532 Specifies if the current context is executing a task. BitBake sets
533 this variable to "1" when a task is being executed. The value is not
534 set when the task is in server context during parsing or event
535 handling.
536
537 BBCLASSEXTEND
538 Allows you to extend a recipe so that it builds variants of the
539 software. Some examples of these variants for recipes from the
540 OpenEmbedded-Core metadata are "natives" such as ``quilt-native``,
541 which is a copy of Quilt built to run on the build system; "crosses"
542 such as ``gcc-cross``, which is a compiler built to run on the build
543 machine but produces binaries that run on the target ``MACHINE``;
544 "nativesdk", which targets the SDK machine instead of ``MACHINE``;
545 and "mulitlibs" in the form "``multilib:``\ multilib_name".
546
547 To build a different variant of the recipe with a minimal amount of
548 code, it usually is as simple as adding the variable to your recipe.
549 Here are two examples. The "native" variants are from the
550 OpenEmbedded-Core metadata: BBCLASSEXTEND =+ "native nativesdk"
551 BBCLASSEXTEND =+ "multilib:multilib_name"
552
553 .. note::
554
555 Internally, the ``BBCLASSEXTEND`` mechanism generates recipe
556 variants by rewriting variable values and applying overrides such
557 as ``_class-native``. For example, to generate a native version of
558 a recipe, a ```DEPENDS`` <#var-bb-DEPENDS>`__ on "foo" is
559 rewritten to a ``DEPENDS`` on "foo-native".
560
561 Even when using ``BBCLASSEXTEND``, the recipe is only parsed once.
562 Parsing once adds some limitations. For example, it is not
563 possible to include a different file depending on the variant,
564 since ``include`` statements are processed when the recipe is
565 parsed.
566
567 BBDEBUG
568 Sets the BitBake debug output level to a specific value as
569 incremented by the ``-D`` command line option.
570
571 .. note::
572
573 You must set this variable in the external environment in order
574 for it to work.
575
576 BBFILE_COLLECTIONS
577 Lists the names of configured layers. These names are used to find
578 the other ``BBFILE_*`` variables. Typically, each layer appends its
579 name to this variable in its ``conf/layer.conf`` file.
580
581 BBFILE_PATTERN
582 Variable that expands to match files from
583 ```BBFILES`` <#var-bb-BBFILES>`__ in a particular layer. This
584 variable is used in the ``conf/layer.conf`` file and must be suffixed
585 with the name of the specific layer (e.g.
586 ``BBFILE_PATTERN_emenlow``).
587
588 BBFILE_PRIORITY
589 Assigns the priority for recipe files in each layer.
590
591 This variable is useful in situations where the same recipe appears
592 in more than one layer. Setting this variable allows you to
593 prioritize a layer against other layers that contain the same recipe
594 - effectively letting you control the precedence for the multiple
595 layers. The precedence established through this variable stands
596 regardless of a recipe's version (```PV`` <#var-bb-PV>`__ variable).
597 For example, a layer that has a recipe with a higher ``PV`` value but
598 for which the ``BBFILE_PRIORITY`` is set to have a lower precedence
599 still has a lower precedence.
600
601 A larger value for the ``BBFILE_PRIORITY`` variable results in a
602 higher precedence. For example, the value 6 has a higher precedence
603 than the value 5. If not specified, the ``BBFILE_PRIORITY`` variable
604 is set based on layer dependencies (see the ``LAYERDEPENDS`` variable
605 for more information. The default priority, if unspecified for a
606 layer with no dependencies, is the lowest defined priority + 1 (or 1
607 if no priorities are defined).
608
609 .. tip::
610
611 You can use the command
612 bitbake-layers show-layers
613 to list all configured layers along with their priorities.
614
615 BBFILES
616 A space-separated list of recipe files BitBake uses to build
617 software.
618
619 When specifying recipe files, you can pattern match using Python's
620 ```glob`` <https://docs.python.org/3/library/glob.html>`__ syntax.
621 For details on the syntax, see the documentation by following the
622 previous link.
623
624 BBINCLUDED
625 Contains a space-separated list of all of all files that BitBake's
626 parser included during parsing of the current file.
627
628 BBINCLUDELOGS
629 If set to a value, enables printing the task log when reporting a
630 failed task.
631
632 BBINCLUDELOGS_LINES
633 If ```BBINCLUDELOGS`` <#var-bb-BBINCLUDELOGS>`__ is set, specifies
634 the maximum number of lines from the task log file to print when
635 reporting a failed task. If you do not set ``BBINCLUDELOGS_LINES``,
636 the entire log is printed.
637
638 BBLAYERS
639 Lists the layers to enable during the build. This variable is defined
640 in the ``bblayers.conf`` configuration file in the build directory.
641 Here is an example: BBLAYERS = " \\ /home/scottrif/poky/meta \\
642 /home/scottrif/poky/meta-yocto \\ /home/scottrif/poky/meta-yocto-bsp
643 \\ /home/scottrif/poky/meta-mykernel \\ " This example enables four
644 layers, one of which is a custom, user-defined layer named
645 ``meta-mykernel``.
646
647 BBLAYERS_FETCH_DIR
648 Sets the base location where layers are stored. This setting is used
649 in conjunction with ``bitbake-layers layerindex-fetch`` and tells
650 ``bitbake-layers`` where to place the fetched layers.
651
652 BBMASK
653 Prevents BitBake from processing recipes and recipe append files.
654
655 You can use the ``BBMASK`` variable to "hide" these ``.bb`` and
656 ``.bbappend`` files. BitBake ignores any recipe or recipe append
657 files that match any of the expressions. It is as if BitBake does not
658 see them at all. Consequently, matching files are not parsed or
659 otherwise used by BitBake.
660
661 The values you provide are passed to Python's regular expression
662 compiler. Consequently, the syntax follows Python's Regular
663 Expression (re) syntax. The expressions are compared against the full
664 paths to the files. For complete syntax information, see Python's
665 documentation at ` <http://docs.python.org/3/library/re.html#re>`__.
666
667 The following example uses a complete regular expression to tell
668 BitBake to ignore all recipe and recipe append files in the
669 ``meta-ti/recipes-misc/`` directory: BBMASK = "meta-ti/recipes-misc/"
670 If you want to mask out multiple directories or recipes, you can
671 specify multiple regular expression fragments. This next example
672 masks out multiple directories and individual recipes: BBMASK +=
673 "/meta-ti/recipes-misc/ meta-ti/recipes-ti/packagegroup/" BBMASK +=
674 "/meta-oe/recipes-support/" BBMASK += "/meta-foo/.*/openldap" BBMASK
675 += "opencv.*\.bbappend" BBMASK += "lzma"
676
677 .. note::
678
679 When specifying a directory name, use the trailing slash character
680 to ensure you match just that directory name.
681
682 BBMULTICONFIG
683 Enables BitBake to perform multiple configuration builds and lists
684 each separate configuration (multiconfig). You can use this variable
685 to cause BitBake to build multiple targets where each target has a
686 separate configuration. Define ``BBMULTICONFIG`` in your
687 ``conf/local.conf`` configuration file.
688
689 As an example, the following line specifies three multiconfigs, each
690 having a separate configuration file: BBMULTIFONFIG = "configA
691 configB configC" Each configuration file you use must reside in the
692 build directory within a directory named ``conf/multiconfig`` (e.g.
693 build_directory\ ``/conf/multiconfig/configA.conf``).
694
695 For information on how to use ``BBMULTICONFIG`` in an environment
696 that supports building targets with multiple configurations, see the
697 "`Executing a Multiple Configuration
698 Build <#executing-a-multiple-configuration-build>`__" section.
699
700 BBPATH
701 Used by BitBake to locate class (``.bbclass``) and configuration
702 (``.conf``) files. This variable is analogous to the ``PATH``
703 variable.
704
705 If you run BitBake from a directory outside of the build directory,
706 you must be sure to set ``BBPATH`` to point to the build directory.
707 Set the variable as you would any environment variable and then run
708 BitBake: $ BBPATH="build_directory" $ export BBPATH $ bitbake target
709
710 BBSERVER
711 Points to the server that runs memory-resident BitBake. The variable
712 is only used when you employ memory-resident BitBake.
713
714 BBTARGETS
715 Allows you to use a configuration file to add to the list of
716 command-line target recipes you want to build.
717
718 BBVERSIONS
719 Allows a single recipe to build multiple versions of a project from a
720 single recipe file. You also able to specify conditional metadata
721 using the ```OVERRIDES`` <#var-bb-OVERRIDES>`__ mechanism for a
722 single version or for an optionally named range of versions.
723
724 For more information on ``BBVERSIONS``, see the "`Variants - Class
725 Extension Mechanism <#variants-class-extension-mechanism>`__"
726 section.
727
728 BITBAKE_UI
729 Used to specify the UI module to use when running BitBake. Using this
730 variable is equivalent to using the ``-u`` command-line option.
731
732 .. note::
733
734 You must set this variable in the external environment in order
735 for it to work.
736
737 BUILDNAME
738 A name assigned to the build. The name defaults to a datetime stamp
739 of when the build was started but can be defined by the metadata.
740
741 BZRDIR
742 The directory in which files checked out of a Bazaar system are
743 stored.
744
745 CACHE
746 Specifies the directory BitBake uses to store a cache of the metadata
747 so it does not need to be parsed every time BitBake is started.
748
749 CVSDIR
750 The directory in which files checked out under the CVS system are
751 stored.
752
753 DEFAULT_PREFERENCE
754 Specifies a weak bias for recipe selection priority.
755
756 The most common usage of this is variable is to set it to "-1" within
757 a recipe for a development version of a piece of software. Using the
758 variable in this way causes the stable version of the recipe to build
759 by default in the absence of ``PREFERRED_VERSION`` being used to
760 build the development version.
761
762 .. note::
763
764 The bias provided by
765 DEFAULT_PREFERENCE
766 is weak and is overridden by
767 BBFILE_PRIORITY
768 if that variable is different between two layers that contain
769 different versions of the same recipe.
770
771 DEPENDS
772 Lists a recipe's build-time dependencies (i.e. other recipe files).
773
774 Consider this simple example for two recipes named "a" and "b" that
775 produce similarly named packages. In this example, the ``DEPENDS``
776 statement appears in the "a" recipe: DEPENDS = "b" Here, the
777 dependency is such that the ``do_configure`` task for recipe "a"
778 depends on the ``do_populate_sysroot`` task of recipe "b". This means
779 anything that recipe "b" puts into sysroot is available when recipe
780 "a" is configuring itself.
781
782 For information on runtime dependencies, see the
783 ```RDEPENDS`` <#var-bb-RDEPENDS>`__ variable.
784
785 DESCRIPTION
786 A long description for the recipe.
787
788 DL_DIR
789 The central download directory used by the build process to store
790 downloads. By default, ``DL_DIR`` gets files suitable for mirroring
791 for everything except Git repositories. If you want tarballs of Git
792 repositories, use the
793 ```BB_GENERATE_MIRROR_TARBALLS`` <#var-bb-BB_GENERATE_MIRROR_TARBALLS>`__
794 variable.
795
796 EXCLUDE_FROM_WORLD
797 Directs BitBake to exclude a recipe from world builds (i.e.
798 ``bitbake world``). During world builds, BitBake locates, parses and
799 builds all recipes found in every layer exposed in the
800 ``bblayers.conf`` configuration file.
801
802 To exclude a recipe from a world build using this variable, set the
803 variable to "1" in the recipe.
804
805 .. note::
806
807 Recipes added to
808 EXCLUDE_FROM_WORLD
809 may still be built during a world build in order to satisfy
810 dependencies of other recipes. Adding a recipe to
811 EXCLUDE_FROM_WORLD
812 only ensures that the recipe is not explicitly added to the list
813 of build targets in a world build.
814
815 FAKEROOT
816 Contains the command to use when running a shell script in a fakeroot
817 environment. The ``FAKEROOT`` variable is obsolete and has been
818 replaced by the other ``FAKEROOT*`` variables. See these entries in
819 the glossary for more information.
820
821 FAKEROOTBASEENV
822 Lists environment variables to set when executing the command defined
823 by ```FAKEROOTCMD`` <#var-bb-FAKEROOTCMD>`__ that starts the
824 bitbake-worker process in the fakeroot environment.
825
826 FAKEROOTCMD
827 Contains the command that starts the bitbake-worker process in the
828 fakeroot environment.
829
830 FAKEROOTDIRS
831 Lists directories to create before running a task in the fakeroot
832 environment.
833
834 FAKEROOTENV
835 Lists environment variables to set when running a task in the
836 fakeroot environment. For additional information on environment
837 variables and the fakeroot environment, see the
838 ```FAKEROOTBASEENV`` <#var-bb-FAKEROOTBASEENV>`__ variable.
839
840 FAKEROOTNOENV
841 Lists environment variables to set when running a task that is not in
842 the fakeroot environment. For additional information on environment
843 variables and the fakeroot environment, see the
844 ```FAKEROOTENV`` <#var-bb-FAKEROOTENV>`__ variable.
845
846 FETCHCMD
847 Defines the command the BitBake fetcher module executes when running
848 fetch operations. You need to use an override suffix when you use the
849 variable (e.g. ``FETCHCMD_git`` or ``FETCHCMD_svn``).
850
851 FILE
852 Points at the current file. BitBake sets this variable during the
853 parsing process to identify the file being parsed. BitBake also sets
854 this variable when a recipe is being executed to identify the recipe
855 file.
856
857 FILESPATH
858 Specifies directories BitBake uses when searching for patches and
859 files. The "local" fetcher module uses these directories when
860 handling ``file://`` URLs. The variable behaves like a shell ``PATH``
861 environment variable. The value is a colon-separated list of
862 directories that are searched left-to-right in order.
863
864 GITDIR
865 The directory in which a local copy of a Git repository is stored
866 when it is cloned.
867
868 HGDIR
869 The directory in which files checked out of a Mercurial system are
870 stored.
871
872 HOMEPAGE
873 Website where more information about the software the recipe is
874 building can be found.
875
876 INHERIT
877 Causes the named class or classes to be inherited globally. Anonymous
878 functions in the class or classes are not executed for the base
879 configuration and in each individual recipe. The OpenEmbedded build
880 system ignores changes to ``INHERIT`` in individual recipes.
881
882 For more information on ``INHERIT``, see the "```INHERIT``
883 Configuration Directive <#inherit-configuration-directive>`__"
884 section.
885
886 LAYERDEPENDS
887 Lists the layers, separated by spaces, upon which this recipe
888 depends. Optionally, you can specify a specific layer version for a
889 dependency by adding it to the end of the layer name with a colon,
890 (e.g. "anotherlayer:3" to be compared against
891 ```LAYERVERSION`` <#var-bb-LAYERVERSION>`__\ ``_anotherlayer`` in
892 this case). BitBake produces an error if any dependency is missing or
893 the version numbers do not match exactly (if specified).
894
895 You use this variable in the ``conf/layer.conf`` file. You must also
896 use the specific layer name as a suffix to the variable (e.g.
897 ``LAYERDEPENDS_mylayer``).
898
899 LAYERDIR
900 When used inside the ``layer.conf`` configuration file, this variable
901 provides the path of the current layer. This variable is not
902 available outside of ``layer.conf`` and references are expanded
903 immediately when parsing of the file completes.
904
905 LAYERDIR_RE
906 When used inside the ``layer.conf`` configuration file, this variable
907 provides the path of the current layer, escaped for use in a regular
908 expression (```BBFILE_PATTERN`` <#var-bb-BBFILE_PATTERN>`__). This
909 variable is not available outside of ``layer.conf`` and references
910 are expanded immediately when parsing of the file completes.
911
912 LAYERVERSION
913 Optionally specifies the version of a layer as a single number. You
914 can use this variable within
915 ```LAYERDEPENDS`` <#var-bb-LAYERDEPENDS>`__ for another layer in
916 order to depend on a specific version of the layer.
917
918 You use this variable in the ``conf/layer.conf`` file. You must also
919 use the specific layer name as a suffix to the variable (e.g.
920 ``LAYERDEPENDS_mylayer``).
921
922 LICENSE
923 The list of source licenses for the recipe.
924
925 MIRRORS
926 Specifies additional paths from which BitBake gets source code. When
927 the build system searches for source code, it first tries the local
928 download directory. If that location fails, the build system tries
929 locations defined by ```PREMIRRORS`` <#var-bb-PREMIRRORS>`__, the
930 upstream source, and then locations specified by ``MIRRORS`` in that
931 order.
932
933 MULTI_PROVIDER_WHITELIST
934 Allows you to suppress BitBake warnings caused when building two
935 separate recipes that provide the same output.
936
937 BitBake normally issues a warning when building two different recipes
938 where each provides the same output. This scenario is usually
939 something the user does not want. However, cases do exist where it
940 makes sense, particularly in the ``virtual/*`` namespace. You can use
941 this variable to suppress BitBake's warnings.
942
943 To use the variable, list provider names (e.g. recipe names,
944 ``virtual/kernel``, and so forth).
945
946 OVERRIDES
947 BitBake uses ``OVERRIDES`` to control what variables are overridden
948 after BitBake parses recipes and configuration files.
949
950 Following is a simple example that uses an overrides list based on
951 machine architectures: OVERRIDES = "arm:x86:mips:powerpc" You can
952 find information on how to use ``OVERRIDES`` in the "`Conditional
953 Syntax (Overrides) <#conditional-syntax-overrides>`__" section.
954
955 P4DIR
956 The directory in which a local copy of a Perforce depot is stored
957 when it is fetched.
958
959 PACKAGES
960 The list of packages the recipe creates.
961
962 PACKAGES_DYNAMIC
963 A promise that your recipe satisfies runtime dependencies for
964 optional modules that are found in other recipes.
965 ``PACKAGES_DYNAMIC`` does not actually satisfy the dependencies, it
966 only states that they should be satisfied. For example, if a hard,
967 runtime dependency (```RDEPENDS`` <#var-bb-RDEPENDS>`__) of another
968 package is satisfied during the build through the
969 ``PACKAGES_DYNAMIC`` variable, but a package with the module name is
970 never actually produced, then the other package will be broken.
971
972 PE
973 The epoch of the recipe. By default, this variable is unset. The
974 variable is used to make upgrades possible when the versioning scheme
975 changes in some backwards incompatible way.
976
977 PERSISTENT_DIR
978 Specifies the directory BitBake uses to store data that should be
979 preserved between builds. In particular, the data stored is the data
980 that uses BitBake's persistent data API and the data used by the PR
981 Server and PR Service.
982
983 PF
984 Specifies the recipe or package name and includes all version and
985 revision numbers (i.e. ``eglibc-2.13-r20+svnr15508/`` and
986 ``bash-4.2-r1/``).
987
988 PN
989 The recipe name.
990
991 PR
992 The revision of the recipe.
993
994 PREFERRED_PROVIDER
995 Determines which recipe should be given preference when multiple
996 recipes provide the same item. You should always suffix the variable
997 with the name of the provided item, and you should set it to the
998 ```PN`` <#var-bb-PN>`__ of the recipe to which you want to give
999 precedence. Some examples: PREFERRED_PROVIDER_virtual/kernel ?=
1000 "linux-yocto" PREFERRED_PROVIDER_virtual/xserver = "xserver-xf86"
1001 PREFERRED_PROVIDER_virtual/libgl ?= "mesa"
1002
1003 PREFERRED_PROVIDERS
1004 Determines which recipe should be given preference for cases where
1005 multiple recipes provide the same item. Functionally,
1006 ``PREFERRED_PROVIDERS`` is identical to
1007 ```PREFERRED_PROVIDER`` <#var-bb-PREFERRED_PROVIDER>`__. However, the
1008 ``PREFERRED_PROVIDERS`` variable lets you define preferences for
1009 multiple situations using the following form: PREFERRED_PROVIDERS =
1010 "xxx:yyy aaa:bbb ..." This form is a convenient replacement for the
1011 following: PREFERRED_PROVIDER_xxx = "yyy" PREFERRED_PROVIDER_aaa =
1012 "bbb"
1013
1014 PREFERRED_VERSION
1015 If there are multiple versions of recipes available, this variable
1016 determines which recipe should be given preference. You must always
1017 suffix the variable with the ```PN`` <#var-bb-PN>`__ you want to
1018 select, and you should set ```PV`` <#var-bb-PV>`__ accordingly for
1019 precedence.
1020
1021 The ``PREFERRED_VERSION`` variable supports limited wildcard use
1022 through the "``%``" character. You can use the character to match any
1023 number of characters, which can be useful when specifying versions
1024 that contain long revision numbers that potentially change. Here are
1025 two examples: PREFERRED_VERSION_python = "2.7.3"
1026 PREFERRED_VERSION_linux-yocto = "4.12%"
1027
1028 .. note::
1029
1030 The use of the "
1031 %
1032 " character is limited in that it only works at the end of the
1033 string. You cannot use the wildcard character in any other
1034 location of the string.
1035
1036 PREMIRRORS
1037 Specifies additional paths from which BitBake gets source code. When
1038 the build system searches for source code, it first tries the local
1039 download directory. If that location fails, the build system tries
1040 locations defined by ``PREMIRRORS``, the upstream source, and then
1041 locations specified by ```MIRRORS`` <#var-bb-MIRRORS>`__ in that
1042 order.
1043
1044 Typically, you would add a specific server for the build system to
1045 attempt before any others by adding something like the following to
1046 your configuration: PREMIRRORS_prepend = "\\ git://.*/.\*
1047 http://www.yoctoproject.org/sources/ \\n \\ ftp://.*/.\*
1048 http://www.yoctoproject.org/sources/ \\n \\ http://.*/.\*
1049 http://www.yoctoproject.org/sources/ \\n \\ https://.*/.\*
1050 http://www.yoctoproject.org/sources/ \\n" These changes cause the
1051 build system to intercept Git, FTP, HTTP, and HTTPS requests and
1052 direct them to the ``http://`` sources mirror. You can use
1053 ``file://`` URLs to point to local directories or network shares as
1054 well.
1055
1056 PROVIDES
1057 A list of aliases by which a particular recipe can be known. By
1058 default, a recipe's own ``PN`` is implicitly already in its
1059 ``PROVIDES`` list. If a recipe uses ``PROVIDES``, the additional
1060 aliases are synonyms for the recipe and can be useful satisfying
1061 dependencies of other recipes during the build as specified by
1062 ``DEPENDS``.
1063
1064 Consider the following example ``PROVIDES`` statement from a recipe
1065 file ``libav_0.8.11.bb``: PROVIDES += "libpostproc" The ``PROVIDES``
1066 statement results in the "libav" recipe also being known as
1067 "libpostproc".
1068
1069 In addition to providing recipes under alternate names, the
1070 ``PROVIDES`` mechanism is also used to implement virtual targets. A
1071 virtual target is a name that corresponds to some particular
1072 functionality (e.g. a Linux kernel). Recipes that provide the
1073 functionality in question list the virtual target in ``PROVIDES``.
1074 Recipes that depend on the functionality in question can include the
1075 virtual target in ```DEPENDS`` <#var-bb-DEPENDS>`__ to leave the
1076 choice of provider open.
1077
1078 Conventionally, virtual targets have names on the form
1079 "virtual/function" (e.g. "virtual/kernel"). The slash is simply part
1080 of the name and has no syntactical significance.
1081
1082 PRSERV_HOST
1083 The network based ```PR`` <#var-bb-PR>`__ service host and port.
1084
1085 Following is an example of how the ``PRSERV_HOST`` variable is set:
1086 PRSERV_HOST = "localhost:0" You must set the variable if you want to
1087 automatically start a local PR service. You can set ``PRSERV_HOST``
1088 to other values to use a remote PR service.
1089
1090 PV
1091 The version of the recipe.
1092
1093 RDEPENDS
1094 Lists a package's runtime dependencies (i.e. other packages) that
1095 must be installed in order for the built package to run correctly. If
1096 a package in this list cannot be found during the build, you will get
1097 a build error.
1098
1099 Because the ``RDEPENDS`` variable applies to packages being built,
1100 you should always use the variable in a form with an attached package
1101 name. For example, suppose you are building a development package
1102 that depends on the ``perl`` package. In this case, you would use the
1103 following ``RDEPENDS`` statement: RDEPENDS_${PN}-dev += "perl" In the
1104 example, the development package depends on the ``perl`` package.
1105 Thus, the ``RDEPENDS`` variable has the ``${PN}-dev`` package name as
1106 part of the variable.
1107
1108 BitBake supports specifying versioned dependencies. Although the
1109 syntax varies depending on the packaging format, BitBake hides these
1110 differences from you. Here is the general syntax to specify versions
1111 with the ``RDEPENDS`` variable: RDEPENDS_${PN} = "package (operator
1112 version)" For ``operator``, you can specify the following: = < > <=
1113 >= For example, the following sets up a dependency on version 1.2 or
1114 greater of the package ``foo``: RDEPENDS_${PN} = "foo (>= 1.2)"
1115
1116 For information on build-time dependencies, see the
1117 ```DEPENDS`` <#var-bb-DEPENDS>`__ variable.
1118
1119 REPODIR
1120 The directory in which a local copy of a ``google-repo`` directory is
1121 stored when it is synced.
1122
1123 RPROVIDES
1124 A list of package name aliases that a package also provides. These
1125 aliases are useful for satisfying runtime dependencies of other
1126 packages both during the build and on the target (as specified by
1127 ``RDEPENDS``).
1128
1129 As with all package-controlling variables, you must always use the
1130 variable in conjunction with a package name override. Here is an
1131 example: RPROVIDES_${PN} = "widget-abi-2"
1132
1133 RRECOMMENDS
1134 A list of packages that extends the usability of a package being
1135 built. The package being built does not depend on this list of
1136 packages in order to successfully build, but needs them for the
1137 extended usability. To specify runtime dependencies for packages, see
1138 the ``RDEPENDS`` variable.
1139
1140 BitBake supports specifying versioned recommends. Although the syntax
1141 varies depending on the packaging format, BitBake hides these
1142 differences from you. Here is the general syntax to specify versions
1143 with the ``RRECOMMENDS`` variable: RRECOMMENDS_${PN} = "package
1144 (operator version)" For ``operator``, you can specify the following:
1145 = < > <= >= For example, the following sets up a recommend on version
1146 1.2 or greater of the package ``foo``: RRECOMMENDS_${PN} = "foo (>=
1147 1.2)"
1148
1149 SECTION
1150 The section in which packages should be categorized.
1151
1152 SRC_URI
1153 The list of source files - local or remote. This variable tells
1154 BitBake which bits to pull for the build and how to pull them. For
1155 example, if the recipe or append file needs to fetch a single tarball
1156 from the Internet, the recipe or append file uses a ``SRC_URI`` entry
1157 that specifies that tarball. On the other hand, if the recipe or
1158 append file needs to fetch a tarball and include a custom file, the
1159 recipe or append file needs an ``SRC_URI`` variable that specifies
1160 all those sources.
1161
1162 The following list explains the available URI protocols:
1163
1164 - *``file://`` -* Fetches files, which are usually files shipped
1165 with the metadata, from the local machine. The path is relative to
1166 the ```FILESPATH`` <#var-bb-FILESPATH>`__ variable.
1167
1168 - *``bzr://`` -* Fetches files from a Bazaar revision control
1169 repository.
1170
1171 - *``git://`` -* Fetches files from a Git revision control
1172 repository.
1173
1174 - *``osc://`` -* Fetches files from an OSC (OpenSUSE Build service)
1175 revision control repository.
1176
1177 - *``repo://`` -* Fetches files from a repo (Git) repository.
1178
1179 - *``http://`` -* Fetches files from the Internet using HTTP.
1180
1181 - *``https://`` -* Fetches files from the Internet using HTTPS.
1182
1183 - *``ftp://`` -* Fetches files from the Internet using FTP.
1184
1185 - *``cvs://`` -* Fetches files from a CVS revision control
1186 repository.
1187
1188 - *``hg://`` -* Fetches files from a Mercurial (``hg``) revision
1189 control repository.
1190
1191 - *``p4://`` -* Fetches files from a Perforce (``p4``) revision
1192 control repository.
1193
1194 - *``ssh://`` -* Fetches files from a secure shell.
1195
1196 - *``svn://`` -* Fetches files from a Subversion (``svn``) revision
1197 control repository.
1198
1199 Here are some additional options worth mentioning:
1200
1201 - *``unpack`` -* Controls whether or not to unpack the file if it is
1202 an archive. The default action is to unpack the file.
1203
1204 - *``subdir`` -* Places the file (or extracts its contents) into the
1205 specified subdirectory. This option is useful for unusual tarballs
1206 or other archives that do not have their files already in a
1207 subdirectory within the archive.
1208
1209 - *``name`` -* Specifies a name to be used for association with
1210 ``SRC_URI`` checksums when you have more than one file specified
1211 in ``SRC_URI``.
1212
1213 - *``downloadfilename`` -* Specifies the filename used when storing
1214 the downloaded file.
1215
1216 SRCDATE
1217 The date of the source code used to build the package. This variable
1218 applies only if the source was fetched from a Source Code Manager
1219 (SCM).
1220
1221 SRCREV
1222 The revision of the source code used to build the package. This
1223 variable applies only when using Subversion, Git, Mercurial and
1224 Bazaar. If you want to build a fixed revision and you want to avoid
1225 performing a query on the remote repository every time BitBake parses
1226 your recipe, you should specify a ``SRCREV`` that is a full revision
1227 identifier and not just a tag.
1228
1229 SRCREV_FORMAT
1230 Helps construct valid ```SRCREV`` <#var-bb-SRCREV>`__ values when
1231 multiple source controlled URLs are used in
1232 ```SRC_URI`` <#var-bb-SRC_URI>`__.
1233
1234 The system needs help constructing these values under these
1235 circumstances. Each component in the ``SRC_URI`` is assigned a name
1236 and these are referenced in the ``SRCREV_FORMAT`` variable. Consider
1237 an example with URLs named "machine" and "meta". In this case,
1238 ``SRCREV_FORMAT`` could look like "machine_meta" and those names
1239 would have the SCM versions substituted into each position. Only one
1240 ``AUTOINC`` placeholder is added and if needed. And, this placeholder
1241 is placed at the start of the returned string.
1242
1243 STAMP
1244 Specifies the base path used to create recipe stamp files. The path
1245 to an actual stamp file is constructed by evaluating this string and
1246 then appending additional information.
1247
1248 STAMPCLEAN
1249 Specifies the base path used to create recipe stamp files. Unlike the
1250 ```STAMP`` <#var-bb-STAMP>`__ variable, ``STAMPCLEAN`` can contain
1251 wildcards to match the range of files a clean operation should
1252 remove. BitBake uses a clean operation to remove any other stamps it
1253 should be removing when creating a new stamp.
1254
1255 SUMMARY
1256 A short summary for the recipe, which is 72 characters or less.
1223 1257
1224SVNDIR 1258 SVNDIR
1225 The directory in which files checked out of a Subversion system are 1259 The directory in which files checked out of a Subversion system are
1226 stored. 1260 stored.
1227 1261
1228T 1262 T
1229 Points to a directory were BitBake places temporary files, which 1263 Points to a directory were BitBake places temporary files, which
1230 consist mostly of task logs and scripts, when building a particular 1264 consist mostly of task logs and scripts, when building a particular
1231 recipe. 1265 recipe.
1232 1266
1233TOPDIR 1267 TOPDIR
1234 Points to the build directory. BitBake automatically sets this 1268 Points to the build directory. BitBake automatically sets this
1235 variable. 1269 variable.