bitbake-user-manual-ref-variables.rst 56 KB

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