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

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