bitbake-user-manual-intro.rst 28 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651
  1. .. SPDX-License-Identifier: CC-BY-2.5
  2. ========
  3. Overview
  4. ========
  5. |
  6. Welcome to the BitBake User Manual. This manual provides information on
  7. the BitBake tool. The information attempts to be as independent as
  8. possible regarding systems that use BitBake, such as OpenEmbedded and
  9. the Yocto Project. In some cases, scenarios or examples within the
  10. context of a build system are used in the manual to help with
  11. understanding. For these cases, the manual clearly states the context.
  12. .. _intro:
  13. Introduction
  14. ============
  15. Fundamentally, BitBake is a generic task execution engine that allows
  16. shell and Python tasks to be run efficiently and in parallel while
  17. working within complex inter-task dependency constraints. One of
  18. BitBake's main users, OpenEmbedded, takes this core and builds embedded
  19. Linux software stacks using a task-oriented approach.
  20. Conceptually, BitBake is similar to GNU Make in some regards but has
  21. significant differences:
  22. - BitBake executes tasks according to provided metadata that builds up
  23. the tasks. Metadata is stored in recipe (``.bb``) and related recipe
  24. "append" (``.bbappend``) files, configuration (``.conf``) and
  25. underlying include (``.inc``) files, and in class (``.bbclass``)
  26. files. The metadata provides BitBake with instructions on what tasks
  27. to run and the dependencies between those tasks.
  28. - BitBake includes a fetcher library for obtaining source code from
  29. various places such as local files, source control systems, or
  30. websites.
  31. - The instructions for each unit to be built (e.g. a piece of software)
  32. are known as "recipe" files and contain all the information about the
  33. unit (dependencies, source file locations, checksums, description and
  34. so on).
  35. - BitBake includes a client/server abstraction and can be used from a
  36. command line or used as a service over XML-RPC and has several
  37. different user interfaces.
  38. History and Goals
  39. =================
  40. BitBake was originally a part of the OpenEmbedded project. It was
  41. inspired by the Portage package management system used by the Gentoo
  42. Linux distribution. On December 7, 2004, OpenEmbedded project team
  43. member Chris Larson split the project into two distinct pieces:
  44. - BitBake, a generic task executor
  45. - OpenEmbedded, a metadata set utilized by BitBake
  46. Today, BitBake is the primary basis of the
  47. `OpenEmbedded <http://www.openembedded.org/>`__ project, which is being
  48. used to build and maintain Linux distributions such as the `Angstrom
  49. Distribution <http://www.angstrom-distribution.org/>`__, and which is
  50. also being used as the build tool for Linux projects such as the `Yocto
  51. Project <http://www.yoctoproject.org>`__.
  52. Prior to BitBake, no other build tool adequately met the needs of an
  53. aspiring embedded Linux distribution. All of the build systems used by
  54. traditional desktop Linux distributions lacked important functionality,
  55. and none of the ad hoc Buildroot-based systems, prevalent in the
  56. embedded space, were scalable or maintainable.
  57. Some important original goals for BitBake were:
  58. - Handle cross-compilation.
  59. - Handle inter-package dependencies (build time on target architecture,
  60. build time on native architecture, and runtime).
  61. - Support running any number of tasks within a given package,
  62. including, but not limited to, fetching upstream sources, unpacking
  63. them, patching them, configuring them, and so forth.
  64. - Be Linux distribution agnostic for both build and target systems.
  65. - Be architecture agnostic.
  66. - Support multiple build and target operating systems (e.g. Cygwin, the
  67. BSDs, and so forth).
  68. - Be self-contained, rather than tightly integrated into the build
  69. machine's root filesystem.
  70. - Handle conditional metadata on the target architecture, operating
  71. system, distribution, and machine.
  72. - Be easy to use the tools to supply local metadata and packages
  73. against which to operate.
  74. - Be easy to use BitBake to collaborate between multiple projects for
  75. their builds.
  76. - Provide an inheritance mechanism to share common metadata between
  77. many packages.
  78. Over time it became apparent that some further requirements were
  79. necessary:
  80. - Handle variants of a base recipe (e.g. native, sdk, and multilib).
  81. - Split metadata into layers and allow layers to enhance or override
  82. other layers.
  83. - Allow representation of a given set of input variables to a task as a
  84. checksum. Based on that checksum, allow acceleration of builds with
  85. prebuilt components.
  86. BitBake satisfies all the original requirements and many more with
  87. extensions being made to the basic functionality to reflect the
  88. additional requirements. Flexibility and power have always been the
  89. priorities. BitBake is highly extensible and supports embedded Python
  90. code and execution of any arbitrary tasks.
  91. .. _Concepts:
  92. Concepts
  93. ========
  94. BitBake is a program written in the Python language. At the highest
  95. level, BitBake interprets metadata, decides what tasks are required to
  96. run, and executes those tasks. Similar to GNU Make, BitBake controls how
  97. software is built. GNU Make achieves its control through "makefiles",
  98. while BitBake uses "recipes".
  99. BitBake extends the capabilities of a simple tool like GNU Make by
  100. allowing for the definition of much more complex tasks, such as
  101. assembling entire embedded Linux distributions.
  102. The remainder of this section introduces several concepts that should be
  103. understood in order to better leverage the power of BitBake.
  104. Recipes
  105. -------
  106. BitBake Recipes, which are denoted by the file extension ``.bb``, are
  107. the most basic metadata files. These recipe files provide BitBake with
  108. the following:
  109. - Descriptive information about the package (author, homepage, license,
  110. and so on)
  111. - The version of the recipe
  112. - Existing dependencies (both build and runtime dependencies)
  113. - Where the source code resides and how to fetch it
  114. - Whether the source code requires any patches, where to find them, and
  115. how to apply them
  116. - How to configure and compile the source code
  117. - How to assemble the generated artifacts into one or more installable
  118. packages
  119. - Where on the target machine to install the package or packages
  120. created
  121. Within the context of BitBake, or any project utilizing BitBake as its
  122. build system, files with the ``.bb`` extension are referred to as
  123. recipes.
  124. .. note::
  125. The term "package" is also commonly used to describe recipes.
  126. However, since the same word is used to describe packaged output from
  127. a project, it is best to maintain a single descriptive term -
  128. "recipes". Put another way, a single "recipe" file is quite capable
  129. of generating a number of related but separately installable
  130. "packages". In fact, that ability is fairly common.
  131. Configuration Files
  132. -------------------
  133. Configuration files, which are denoted by the ``.conf`` extension,
  134. define various configuration variables that govern the project's build
  135. process. These files fall into several areas that define machine
  136. configuration, distribution configuration, possible compiler tuning,
  137. general common configuration, and user configuration. The main
  138. configuration file is the sample ``bitbake.conf`` file, which is located
  139. within the BitBake source tree ``conf`` directory.
  140. Classes
  141. -------
  142. Class files, which are denoted by the ``.bbclass`` extension, contain
  143. information that is useful to share between metadata files. The BitBake
  144. source tree currently comes with one class metadata file called
  145. ``base.bbclass``. You can find this file in the ``classes`` directory.
  146. The ``base.bbclass`` class files is special since it is always included
  147. automatically for all recipes and classes. This class contains
  148. definitions for standard basic tasks such as fetching, unpacking,
  149. configuring (empty by default), compiling (runs any Makefile present),
  150. installing (empty by default) and packaging (empty by default). These
  151. tasks are often overridden or extended by other classes added during the
  152. project development process.
  153. Layers
  154. ------
  155. Layers allow you to isolate different types of customizations from each
  156. other. While you might find it tempting to keep everything in one layer
  157. when working on a single project, the more modular your metadata, the
  158. easier it is to cope with future changes.
  159. To illustrate how you can use layers to keep things modular, consider
  160. customizations you might make to support a specific target machine.
  161. These types of customizations typically reside in a special layer,
  162. rather than a general layer, called a Board Support Package (BSP) layer.
  163. Furthermore, the machine customizations should be isolated from recipes
  164. and metadata that support a new GUI environment, for example. This
  165. situation gives you a couple of layers: one for the machine
  166. configurations and one for the GUI environment. It is important to
  167. understand, however, that the BSP layer can still make machine-specific
  168. additions to recipes within the GUI environment layer without polluting
  169. the GUI layer itself with those machine-specific changes. You can
  170. accomplish this through a recipe that is a BitBake append
  171. (``.bbappend``) file.
  172. .. _append-bbappend-files:
  173. Append Files
  174. ------------
  175. Append files, which are files that have the ``.bbappend`` file
  176. extension, extend or override information in an existing recipe file.
  177. BitBake expects every append file to have a corresponding recipe file.
  178. Furthermore, the append file and corresponding recipe file must use the
  179. same root filename. The filenames can differ only in the file type
  180. suffix used (e.g. ``formfactor_0.0.bb`` and
  181. ``formfactor_0.0.bbappend``).
  182. Information in append files extends or overrides the information in the
  183. underlying, similarly-named recipe files.
  184. When you name an append file, you can use the "``%``" wildcard character
  185. to allow for matching recipe names. For example, suppose you have an
  186. append file named as follows: ::
  187. busybox_1.21.%.bbappend
  188. That append file
  189. would match any ``busybox_1.21.``\ x\ ``.bb`` version of the recipe. So,
  190. the append file would match the following recipe names: ::
  191. busybox_1.21.1.bb
  192. busybox_1.21.2.bb
  193. busybox_1.21.3.bb
  194. .. note::
  195. The use of the " % " character is limited in that it only works directly in
  196. front of the .bbappend portion of the append file's name. You cannot use the
  197. wildcard character in any other location of the name.
  198. If the ``busybox`` recipe was updated to ``busybox_1.3.0.bb``, the
  199. append name would not match. However, if you named the append file
  200. ``busybox_1.%.bbappend``, then you would have a match.
  201. In the most general case, you could name the append file something as
  202. simple as ``busybox_%.bbappend`` to be entirely version independent.
  203. Obtaining BitBake
  204. =================
  205. You can obtain BitBake several different ways:
  206. - **Cloning BitBake:** Using Git to clone the BitBake source code
  207. repository is the recommended method for obtaining BitBake. Cloning
  208. the repository makes it easy to get bug fixes and have access to
  209. stable branches and the master branch. Once you have cloned BitBake,
  210. you should use the latest stable branch for development since the
  211. master branch is for BitBake development and might contain less
  212. stable changes.
  213. You usually need a version of BitBake that matches the metadata you
  214. are using. The metadata is generally backwards compatible but not
  215. forward compatible.
  216. Here is an example that clones the BitBake repository: ::
  217. $ git clone git://git.openembedded.org/bitbake
  218. This command clones the BitBake
  219. Git repository into a directory called ``bitbake``. Alternatively,
  220. you can designate a directory after the ``git clone`` command if you
  221. want to call the new directory something other than ``bitbake``. Here
  222. is an example that names the directory ``bbdev``: ::
  223. $ git clone git://git.openembedded.org/bitbake bbdev
  224. - **Installation using your Distribution Package Management System:**
  225. This method is not recommended because the BitBake version that is
  226. provided by your distribution, in most cases, is several releases
  227. behind a snapshot of the BitBake repository.
  228. - **Taking a snapshot of BitBake:** Downloading a snapshot of BitBake
  229. from the source code repository gives you access to a known branch or
  230. release of BitBake.
  231. .. note::
  232. Cloning the Git repository, as described earlier, is the preferred
  233. method for getting BitBake. Cloning the repository makes it easier
  234. to update as patches are added to the stable branches.
  235. The following example downloads a snapshot of BitBake version 1.17.0: ::
  236. $ wget http://git.openembedded.org/bitbake/snapshot/bitbake-1.17.0.tar.gz
  237. $ tar zxpvf bitbake-1.17.0.tar.gz
  238. After extraction of the tarball using
  239. the tar utility, you have a directory entitled ``bitbake-1.17.0``.
  240. - **Using the BitBake that Comes With Your Build Checkout:** A final
  241. possibility for getting a copy of BitBake is that it already comes
  242. with your checkout of a larger BitBake-based build system, such as
  243. Poky. Rather than manually checking out individual layers and gluing
  244. them together yourself, you can check out an entire build system. The
  245. checkout will already include a version of BitBake that has been
  246. thoroughly tested for compatibility with the other components. For
  247. information on how to check out a particular BitBake-based build
  248. system, consult that build system's supporting documentation.
  249. .. _bitbake-user-manual-command:
  250. The BitBake Command
  251. ===================
  252. The ``bitbake`` command is the primary interface to the BitBake tool.
  253. This section presents the BitBake command syntax and provides several
  254. execution examples.
  255. Usage and syntax
  256. ----------------
  257. Following is the usage and syntax for BitBake: ::
  258. $ bitbake -h
  259. Usage: bitbake [options] [recipename/target recipe:do_task ...]
  260. Executes the specified task (default is 'build') for a given set of target recipes (.bb files).
  261. It is assumed there is a conf/bblayers.conf available in cwd or in BBPATH which
  262. will provide the layer, BBFILES and other configuration information.
  263. Options:
  264. --version show program's version number and exit
  265. -h, --help show this help message and exit
  266. -b BUILDFILE, --buildfile=BUILDFILE
  267. Execute tasks from a specific .bb recipe directly.
  268. WARNING: Does not handle any dependencies from other
  269. recipes.
  270. -k, --continue Continue as much as possible after an error. While the
  271. target that failed and anything depending on it cannot
  272. be built, as much as possible will be built before
  273. stopping.
  274. -f, --force Force the specified targets/task to run (invalidating
  275. any existing stamp file).
  276. -c CMD, --cmd=CMD Specify the task to execute. The exact options
  277. available depend on the metadata. Some examples might
  278. be 'compile' or 'populate_sysroot' or 'listtasks' may
  279. give a list of the tasks available.
  280. -C INVALIDATE_STAMP, --clear-stamp=INVALIDATE_STAMP
  281. Invalidate the stamp for the specified task such as
  282. 'compile' and then run the default task for the
  283. specified target(s).
  284. -r PREFILE, --read=PREFILE
  285. Read the specified file before bitbake.conf.
  286. -R POSTFILE, --postread=POSTFILE
  287. Read the specified file after bitbake.conf.
  288. -v, --verbose Enable tracing of shell tasks (with 'set -x'). Also
  289. print bb.note(...) messages to stdout (in addition to
  290. writing them to ${T}/log.do_&lt;task&gt;).
  291. -D, --debug Increase the debug level. You can specify this more
  292. than once. -D sets the debug level to 1, where only
  293. bb.debug(1, ...) messages are printed to stdout; -DD
  294. sets the debug level to 2, where both bb.debug(1, ...)
  295. and bb.debug(2, ...) messages are printed; etc.
  296. Without -D, no debug messages are printed. Note that
  297. -D only affects output to stdout. All debug messages
  298. are written to ${T}/log.do_taskname, regardless of the
  299. debug level.
  300. -q, --quiet Output less log message data to the terminal. You can
  301. specify this more than once.
  302. -n, --dry-run Don't execute, just go through the motions.
  303. -S SIGNATURE_HANDLER, --dump-signatures=SIGNATURE_HANDLER
  304. Dump out the signature construction information, with
  305. no task execution. The SIGNATURE_HANDLER parameter is
  306. passed to the handler. Two common values are none and
  307. printdiff but the handler may define more/less. none
  308. means only dump the signature, printdiff means compare
  309. the dumped signature with the cached one.
  310. -p, --parse-only Quit after parsing the BB recipes.
  311. -s, --show-versions Show current and preferred versions of all recipes.
  312. -e, --environment Show the global or per-recipe environment complete
  313. with information about where variables were
  314. set/changed.
  315. -g, --graphviz Save dependency tree information for the specified
  316. targets in the dot syntax.
  317. -I EXTRA_ASSUME_PROVIDED, --ignore-deps=EXTRA_ASSUME_PROVIDED
  318. Assume these dependencies don't exist and are already
  319. provided (equivalent to ASSUME_PROVIDED). Useful to
  320. make dependency graphs more appealing
  321. -l DEBUG_DOMAINS, --log-domains=DEBUG_DOMAINS
  322. Show debug logging for the specified logging domains
  323. -P, --profile Profile the command and save reports.
  324. -u UI, --ui=UI The user interface to use (knotty, ncurses or taskexp
  325. - default knotty).
  326. --token=XMLRPCTOKEN Specify the connection token to be used when
  327. connecting to a remote server.
  328. --revisions-changed Set the exit code depending on whether upstream
  329. floating revisions have changed or not.
  330. --server-only Run bitbake without a UI, only starting a server
  331. (cooker) process.
  332. -B BIND, --bind=BIND The name/address for the bitbake xmlrpc server to bind
  333. to.
  334. -T SERVER_TIMEOUT, --idle-timeout=SERVER_TIMEOUT
  335. Set timeout to unload bitbake server due to
  336. inactivity, set to -1 means no unload, default:
  337. Environment variable BB_SERVER_TIMEOUT.
  338. --no-setscene Do not run any setscene tasks. sstate will be ignored
  339. and everything needed, built.
  340. --setscene-only Only run setscene tasks, don't run any real tasks.
  341. --remote-server=REMOTE_SERVER
  342. Connect to the specified server.
  343. -m, --kill-server Terminate any running bitbake server.
  344. --observe-only Connect to a server as an observing-only client.
  345. --status-only Check the status of the remote bitbake server.
  346. -w WRITEEVENTLOG, --write-log=WRITEEVENTLOG
  347. Writes the event log of the build to a bitbake event
  348. json file. Use '' (empty string) to assign the name
  349. automatically.
  350. --runall=RUNALL Run the specified task for any recipe in the taskgraph
  351. of the specified target (even if it wouldn't otherwise
  352. have run).
  353. --runonly=RUNONLY Run only the specified task within the taskgraph of
  354. the specified targets (and any task dependencies those
  355. tasks may have).
  356. .. _bitbake-examples:
  357. Examples
  358. --------
  359. This section presents some examples showing how to use BitBake.
  360. .. _example-executing-a-task-against-a-single-recipe:
  361. Executing a Task Against a Single Recipe
  362. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  363. Executing tasks for a single recipe file is relatively simple. You
  364. specify the file in question, and BitBake parses it and executes the
  365. specified task. If you do not specify a task, BitBake executes the
  366. default task, which is "build". BitBake obeys inter-task dependencies
  367. when doing so.
  368. The following command runs the build task, which is the default task, on
  369. the ``foo_1.0.bb`` recipe file: ::
  370. $ bitbake -b foo_1.0.bb
  371. The following command runs the clean task on the ``foo.bb`` recipe file: ::
  372. $ bitbake -b foo.bb -c clean
  373. .. note::
  374. The "-b" option explicitly does not handle recipe dependencies. Other
  375. than for debugging purposes, it is instead recommended that you use
  376. the syntax presented in the next section.
  377. Executing Tasks Against a Set of Recipe Files
  378. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  379. There are a number of additional complexities introduced when one wants
  380. to manage multiple ``.bb`` files. Clearly there needs to be a way to
  381. tell BitBake what files are available and, of those, which you want to
  382. execute. There also needs to be a way for each recipe to express its
  383. dependencies, both for build-time and runtime. There must be a way for
  384. you to express recipe preferences when multiple recipes provide the same
  385. functionality, or when there are multiple versions of a recipe.
  386. The ``bitbake`` command, when not using "--buildfile" or "-b" only
  387. accepts a "PROVIDES". You cannot provide anything else. By default, a
  388. recipe file generally "PROVIDES" its "packagename" as shown in the
  389. following example: ::
  390. $ bitbake foo
  391. This next example "PROVIDES" the
  392. package name and also uses the "-c" option to tell BitBake to just
  393. execute the ``do_clean`` task: ::
  394. $ bitbake -c clean foo
  395. Executing a List of Task and Recipe Combinations
  396. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  397. The BitBake command line supports specifying different tasks for
  398. individual targets when you specify multiple targets. For example,
  399. suppose you had two targets (or recipes) ``myfirstrecipe`` and
  400. ``mysecondrecipe`` and you needed BitBake to run ``taskA`` for the first
  401. recipe and ``taskB`` for the second recipe: ::
  402. $ bitbake myfirstrecipe:do_taskA mysecondrecipe:do_taskB
  403. Generating Dependency Graphs
  404. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  405. BitBake is able to generate dependency graphs using the ``dot`` syntax.
  406. You can convert these graphs into images using the ``dot`` tool from
  407. `Graphviz <http://www.graphviz.org>`__.
  408. When you generate a dependency graph, BitBake writes two files to the
  409. current working directory:
  410. - ``task-depends.dot``: Shows dependencies between tasks. These
  411. dependencies match BitBake's internal task execution list.
  412. - ``pn-buildlist``: Shows a simple list of targets that are to be
  413. built.
  414. To stop depending on common depends, use the "-I" depend option and
  415. BitBake omits them from the graph. Leaving this information out can
  416. produce more readable graphs. This way, you can remove from the graph
  417. ``DEPENDS`` from inherited classes such as ``base.bbclass``.
  418. Here are two examples that create dependency graphs. The second example
  419. omits depends common in OpenEmbedded from the graph: ::
  420. $ bitbake -g foo
  421. $ bitbake -g -I virtual/kernel -I eglibc foo
  422. Executing a Multiple Configuration Build
  423. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  424. BitBake is able to build multiple images or packages using a single
  425. command where the different targets require different configurations
  426. (multiple configuration builds). Each target, in this scenario, is
  427. referred to as a "multiconfig".
  428. To accomplish a multiple configuration build, you must define each
  429. target's configuration separately using a parallel configuration file in
  430. the build directory. The location for these multiconfig configuration
  431. files is specific. They must reside in the current build directory in a
  432. sub-directory of ``conf`` named ``multiconfig``. Following is an example
  433. for two separate targets:
  434. .. image:: figures/bb_multiconfig_files.png
  435. :align: center
  436. The reason for this required file hierarchy is because the ``BBPATH``
  437. variable is not constructed until the layers are parsed. Consequently,
  438. using the configuration file as a pre-configuration file is not possible
  439. unless it is located in the current working directory.
  440. Minimally, each configuration file must define the machine and the
  441. temporary directory BitBake uses for the build. Suggested practice
  442. dictates that you do not overlap the temporary directories used during
  443. the builds.
  444. Aside from separate configuration files for each target, you must also
  445. enable BitBake to perform multiple configuration builds. Enabling is
  446. accomplished by setting the
  447. :term:`BBMULTICONFIG` variable in the
  448. ``local.conf`` configuration file. As an example, suppose you had
  449. configuration files for ``target1`` and ``target2`` defined in the build
  450. directory. The following statement in the ``local.conf`` file both
  451. enables BitBake to perform multiple configuration builds and specifies
  452. the two extra multiconfigs: ::
  453. BBMULTICONFIG = "target1 target2"
  454. Once the target configuration files are in place and BitBake has been
  455. enabled to perform multiple configuration builds, use the following
  456. command form to start the builds: ::
  457. $ bitbake [mc:multiconfigname:]target [[[mc:multiconfigname:]target] ... ]
  458. Here is an example for two extra multiconfigs: ``target1`` and ``target2``: ::
  459. $ bitbake mc::target mc:target1:target mc:target2:target
  460. .. _bb-enabling-multiple-configuration-build-dependencies:
  461. Enabling Multiple Configuration Build Dependencies
  462. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  463. Sometimes dependencies can exist between targets (multiconfigs) in a
  464. multiple configuration build. For example, suppose that in order to
  465. build an image for a particular architecture, the root filesystem of
  466. another build for a different architecture needs to exist. In other
  467. words, the image for the first multiconfig depends on the root
  468. filesystem of the second multiconfig. This dependency is essentially
  469. that the task in the recipe that builds one multiconfig is dependent on
  470. the completion of the task in the recipe that builds another
  471. multiconfig.
  472. To enable dependencies in a multiple configuration build, you must
  473. declare the dependencies in the recipe using the following statement
  474. form: ::
  475. task_or_package[mcdepends] = "mc:from_multiconfig:to_multiconfig:recipe_name:task_on_which_to_depend"
  476. To better show how to use this statement, consider an example with two
  477. multiconfigs: ``target1`` and ``target2``: ::
  478. image_task[mcdepends] = "mc:target1:target2:image2:rootfs_task"
  479. In this example, the
  480. ``from_multiconfig`` is "target1" and the ``to_multiconfig`` is "target2". The
  481. task on which the image whose recipe contains image_task depends on the
  482. completion of the rootfs_task used to build out image2, which is
  483. associated with the "target2" multiconfig.
  484. Once you set up this dependency, you can build the "target1" multiconfig
  485. using a BitBake command as follows: ::
  486. $ bitbake mc:target1:image1
  487. This command executes all the tasks needed to create ``image1`` for the "target1"
  488. multiconfig. Because of the dependency, BitBake also executes through
  489. the ``rootfs_task`` for the "target2" multiconfig build.
  490. Having a recipe depend on the root filesystem of another build might not
  491. seem that useful. Consider this change to the statement in the image1
  492. recipe: ::
  493. image_task[mcdepends] = "mc:target1:target2:image2:image_task"
  494. In this case, BitBake must create ``image2`` for the "target2" build since
  495. the "target1" build depends on it.
  496. Because "target1" and "target2" are enabled for multiple configuration
  497. builds and have separate configuration files, BitBake places the
  498. artifacts for each build in the respective temporary build directories.