blob: 995c2fa7bf48d1047b3088436848088e920ee59a [file] [log] [blame]
Andrew Geissler4873add2020-11-02 18:44:49 -06001<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2 "">
4<chapter id="bitbake-user-manual-intro">
5 <title>Overview</title>
7 <para>
8 Welcome to the BitBake User Manual.
9 This manual provides information on the BitBake tool.
10 The information attempts to be as independent as possible regarding
11 systems that use BitBake, such as OpenEmbedded and the
12 Yocto Project.
13 In some cases, scenarios or examples within the context of
14 a build system are used in the manual to help with understanding.
15 For these cases, the manual clearly states the context.
16 </para>
18 <section id="intro">
19 <title>Introduction</title>
21 <para>
22 Fundamentally, BitBake is a generic task execution
23 engine that allows shell and Python tasks to be run
24 efficiently and in parallel while working within
25 complex inter-task dependency constraints.
26 One of BitBake's main users, OpenEmbedded, takes this core
27 and builds embedded Linux software stacks using
28 a task-oriented approach.
29 </para>
31 <para>
32 Conceptually, BitBake is similar to GNU Make in
33 some regards but has significant differences:
34 <itemizedlist>
35 <listitem><para>
36 BitBake executes tasks according to provided
37 metadata that builds up the tasks.
38 Metadata is stored in recipe (<filename>.bb</filename>)
39 and related recipe "append" (<filename>.bbappend</filename>)
40 files, configuration (<filename>.conf</filename>) and
41 underlying include (<filename>.inc</filename>) files, and
42 in class (<filename>.bbclass</filename>) files.
43 The metadata provides
44 BitBake with instructions on what tasks to run and
45 the dependencies between those tasks.
46 </para></listitem>
47 <listitem><para>
48 BitBake includes a fetcher library for obtaining source
49 code from various places such as local files, source control
50 systems, or websites.
51 </para></listitem>
52 <listitem><para>
53 The instructions for each unit to be built (e.g. a piece
54 of software) are known as "recipe" files and
55 contain all the information about the unit
56 (dependencies, source file locations, checksums, description
57 and so on).
58 </para></listitem>
59 <listitem><para>
60 BitBake includes a client/server abstraction and can
61 be used from a command line or used as a service over
62 XML-RPC and has several different user interfaces.
63 </para></listitem>
64 </itemizedlist>
65 </para>
66 </section>
68 <section id="history-and-goals">
69 <title>History and Goals</title>
71 <para>
72 BitBake was originally a part of the OpenEmbedded project.
73 It was inspired by the Portage package management system
74 used by the Gentoo Linux distribution.
75 On December 7, 2004, OpenEmbedded project team member
76 Chris Larson split the project into two distinct pieces:
77 <itemizedlist>
78 <listitem><para>BitBake, a generic task executor</para></listitem>
79 <listitem><para>OpenEmbedded, a metadata set utilized by
80 BitBake</para></listitem>
81 </itemizedlist>
82 Today, BitBake is the primary basis of the
83 <ulink url="">OpenEmbedded</ulink>
84 project, which is being used to build and maintain Linux
85 distributions such as the
86 <ulink url=''>Angstrom Distribution</ulink>,
87 and which is also being used as the build tool for Linux projects
88 such as the
89 <ulink url=''>Yocto Project</ulink>.
90 </para>
92 <para>
93 Prior to BitBake, no other build tool adequately met the needs of
94 an aspiring embedded Linux distribution.
95 All of the build systems used by traditional desktop Linux
96 distributions lacked important functionality, and none of the
97 ad hoc Buildroot-based systems, prevalent in the
98 embedded space, were scalable or maintainable.
99 </para>
101 <para>
102 Some important original goals for BitBake were:
103 <itemizedlist>
104 <listitem><para>
105 Handle cross-compilation.
106 </para></listitem>
107 <listitem><para>
108 Handle inter-package dependencies (build time on
109 target architecture, build time on native
110 architecture, and runtime).
111 </para></listitem>
112 <listitem><para>
113 Support running any number of tasks within a given
114 package, including, but not limited to, fetching
115 upstream sources, unpacking them, patching them,
116 configuring them, and so forth.
117 </para></listitem>
118 <listitem><para>
119 Be Linux distribution agnostic for both build and
120 target systems.
121 </para></listitem>
122 <listitem><para>
123 Be architecture agnostic.
124 </para></listitem>
125 <listitem><para>
126 Support multiple build and target operating systems
127 (e.g. Cygwin, the BSDs, and so forth).
128 </para></listitem>
129 <listitem><para>
130 Be self-contained, rather than tightly
131 integrated into the build machine's root
132 filesystem.
133 </para></listitem>
134 <listitem><para>
135 Handle conditional metadata on the target architecture,
136 operating system, distribution, and machine.
137 </para></listitem>
138 <listitem><para>
139 Be easy to use the tools to supply local metadata and packages
140 against which to operate.
141 </para></listitem>
142 <listitem><para>
143 Be easy to use BitBake to collaborate between multiple
144 projects for their builds.
145 </para></listitem>
146 <listitem><para>
147 Provide an inheritance mechanism to share
148 common metadata between many packages.
149 </para></listitem>
150 </itemizedlist>
151 Over time it became apparent that some further requirements
152 were necessary:
153 <itemizedlist>
154 <listitem><para>
155 Handle variants of a base recipe (e.g. native, sdk,
156 and multilib).
157 </para></listitem>
158 <listitem><para>
159 Split metadata into layers and allow layers
160 to enhance or override other layers.
161 </para></listitem>
162 <listitem><para>
163 Allow representation of a given set of input variables
164 to a task as a checksum.
165 Based on that checksum, allow acceleration of builds
166 with prebuilt components.
167 </para></listitem>
168 </itemizedlist>
169 BitBake satisfies all the original requirements and many more
170 with extensions being made to the basic functionality to
171 reflect the additional requirements.
172 Flexibility and power have always been the priorities.
173 BitBake is highly extensible and supports embedded Python code and
174 execution of any arbitrary tasks.
175 </para>
176 </section>
178 <section id="Concepts">
179 <title>Concepts</title>
181 <para>
182 BitBake is a program written in the Python language.
183 At the highest level, BitBake interprets metadata, decides
184 what tasks are required to run, and executes those tasks.
185 Similar to GNU Make, BitBake controls how software is
186 built.
187 GNU Make achieves its control through "makefiles", while
188 BitBake uses "recipes".
189 </para>
191 <para>
192 BitBake extends the capabilities of a simple
193 tool like GNU Make by allowing for the definition of much more
194 complex tasks, such as assembling entire embedded Linux
195 distributions.
196 </para>
198 <para>
199 The remainder of this section introduces several concepts
200 that should be understood in order to better leverage
201 the power of BitBake.
202 </para>
204 <section id='recipes'>
205 <title>Recipes</title>
207 <para>
208 BitBake Recipes, which are denoted by the file extension
209 <filename>.bb</filename>, are the most basic metadata files.
210 These recipe files provide BitBake with the following:
211 <itemizedlist>
212 <listitem><para>Descriptive information about the
213 package (author, homepage, license, and so on)</para></listitem>
214 <listitem><para>The version of the recipe</para></listitem>
215 <listitem><para>Existing dependencies (both build
216 and runtime dependencies)</para></listitem>
217 <listitem><para>Where the source code resides and
218 how to fetch it</para></listitem>
219 <listitem><para>Whether the source code requires
220 any patches, where to find them, and how to apply
221 them</para></listitem>
222 <listitem><para>How to configure and compile the
223 source code</para></listitem>
224 <listitem><para>How to assemble the generated artifacts into
225 one or more installable packages</para></listitem>
226 <listitem><para>Where on the target machine to install the
227 package or packages created</para></listitem>
228 </itemizedlist>
229 </para>
231 <para>
232 Within the context of BitBake, or any project utilizing BitBake
233 as its build system, files with the <filename>.bb</filename>
234 extension are referred to as <firstterm>recipes</firstterm>.
235 <note>
236 The term "package" is also commonly used to describe recipes.
237 However, since the same word is used to describe packaged
238 output from a project, it is best to maintain a single
239 descriptive term - "recipes".
240 Put another way, a single "recipe" file is quite capable
241 of generating a number of related but separately installable
242 "packages".
243 In fact, that ability is fairly common.
244 </note>
245 </para>
246 </section>
248 <section id='configuration-files'>
249 <title>Configuration Files</title>
251 <para>
252 Configuration files, which are denoted by the
253 <filename>.conf</filename> extension, define
254 various configuration variables that govern the project's build
255 process.
256 These files fall into several areas that define
257 machine configuration, distribution configuration,
258 possible compiler tuning, general common
259 configuration, and user configuration.
260 The main configuration file is the sample
261 <filename>bitbake.conf</filename> file, which is
262 located within the BitBake source tree
263 <filename>conf</filename> directory.
264 </para>
265 </section>
267 <section id='classes'>
268 <title>Classes</title>
270 <para>
271 Class files, which are denoted by the
272 <filename>.bbclass</filename> extension, contain
273 information that is useful to share between metadata files.
274 The BitBake source tree currently comes with one class metadata file
275 called <filename>base.bbclass</filename>.
276 You can find this file in the
277 <filename>classes</filename> directory.
278 The <filename>base.bbclass</filename> class files is special since it
279 is always included automatically for all recipes
280 and classes.
281 This class contains definitions for standard basic tasks such
282 as fetching, unpacking, configuring (empty by default),
283 compiling (runs any Makefile present), installing (empty by
284 default) and packaging (empty by default).
285 These tasks are often overridden or extended by other classes
286 added during the project development process.
287 </para>
288 </section>
290 <section id='layers'>
291 <title>Layers</title>
293 <para>
294 Layers allow you to isolate different types of
295 customizations from each other.
296 While you might find it tempting to keep everything in one layer
297 when working on a single project, the more modular
298 your metadata, the easier it is to cope with future changes.
299 </para>
301 <para>
302 To illustrate how you can use layers to keep things modular,
303 consider customizations you might make to support a specific target machine.
304 These types of customizations typically reside in a special layer,
305 rather than a general layer, called a <firstterm>Board Support Package</firstterm> (BSP)
306 layer.
307 Furthermore, the machine customizations should be isolated from
308 recipes and metadata that support a new GUI environment, for
309 example.
310 This situation gives you a couple of layers: one for the machine
311 configurations and one for the GUI environment.
312 It is important to understand, however, that the BSP layer can still
313 make machine-specific additions to recipes within
314 the GUI environment layer without polluting the GUI layer itself
315 with those machine-specific changes.
316 You can accomplish this through a recipe that is a BitBake append
317 (<filename>.bbappend</filename>) file.
318 </para>
319 </section>
321 <section id='append-bbappend-files'>
322 <title>Append Files</title>
324 <para>
325 Append files, which are files that have the
326 <filename>.bbappend</filename> file extension, extend or
327 override information in an existing recipe file.
328 </para>
330 <para>
331 BitBake expects every append file to have a corresponding recipe file.
332 Furthermore, the append file and corresponding recipe file
333 must use the same root filename.
334 The filenames can differ only in the file type suffix used
335 (e.g. <filename></filename> and
336 <filename>formfactor_0.0.bbappend</filename>).
337 </para>
339 <para>
340 Information in append files extends or
341 overrides the information in the underlying,
342 similarly-named recipe files.
343 </para>
345 <para>
346 When you name an append file, you can use the
347 "<filename>%</filename>" wildcard character to allow for matching
348 recipe names.
349 For example, suppose you have an append file named
350 as follows:
351 <literallayout class='monospaced'>
352 busybox_1.21.%.bbappend
353 </literallayout>
354 That append file would match any <filename>busybox_1.21.</filename><replaceable>x</replaceable><filename>.bb</filename>
355 version of the recipe.
356 So, the append file would match the following recipe names:
357 <literallayout class='monospaced'>
361 </literallayout>
362 <note><title>Important</title>
363 The use of the "<filename>%</filename>" character
364 is limited in that it only works directly in front of the
365 <filename>.bbappend</filename> portion of the append file's
366 name.
367 You cannot use the wildcard character in any other
368 location of the name.
369 </note>
370 If the <filename>busybox</filename> recipe was updated to
371 <filename></filename>, the append name would not
372 match.
373 However, if you named the append file
374 <filename>busybox_1.%.bbappend</filename>, then you would have a match.
375 </para>
377 <para>
378 In the most general case, you could name the append file something as
379 simple as <filename>busybox_%.bbappend</filename> to be entirely
380 version independent.
381 </para>
382 </section>
383 </section>
385 <section id='obtaining-bitbake'>
386 <title>Obtaining BitBake</title>
388 <para>
389 You can obtain BitBake several different ways:
390 <itemizedlist>
391 <listitem><para><emphasis>Cloning BitBake:</emphasis>
392 Using Git to clone the BitBake source code repository
393 is the recommended method for obtaining BitBake.
394 Cloning the repository makes it easy to get bug fixes
395 and have access to stable branches and the master
396 branch.
397 Once you have cloned BitBake, you should use
398 the latest stable
399 branch for development since the master branch is for
400 BitBake development and might contain less stable changes.
401 </para>
402 <para>You usually need a version of BitBake
403 that matches the metadata you are using.
404 The metadata is generally backwards compatible but
405 not forward compatible.</para>
406 <para>Here is an example that clones the BitBake repository:
407 <literallayout class='monospaced'>
408 $ git clone git://
409 </literallayout>
410 This command clones the BitBake Git repository into a
411 directory called <filename>bitbake</filename>.
412 Alternatively, you can
413 designate a directory after the
414 <filename>git clone</filename> command
415 if you want to call the new directory something
416 other than <filename>bitbake</filename>.
417 Here is an example that names the directory
418 <filename>bbdev</filename>:
419 <literallayout class='monospaced'>
420 $ git clone git:// bbdev
421 </literallayout></para></listitem>
422 <listitem><para><emphasis>Installation using your Distribution
423 Package Management System:</emphasis>
424 This method is not
425 recommended because the BitBake version that is
426 provided by your distribution, in most cases,
427 is several
428 releases behind a snapshot of the BitBake repository.
429 </para></listitem>
430 <listitem><para><emphasis>Taking a snapshot of BitBake:</emphasis>
431 Downloading a snapshot of BitBake from the
432 source code repository gives you access to a known
433 branch or release of BitBake.
434 <note>
435 Cloning the Git repository, as described earlier,
436 is the preferred method for getting BitBake.
437 Cloning the repository makes it easier to update as
438 patches are added to the stable branches.
439 </note></para>
440 <para>The following example downloads a snapshot of
441 BitBake version 1.17.0:
442 <literallayout class='monospaced'>
443 $ wget
444 $ tar zxpvf bitbake-1.17.0.tar.gz
445 </literallayout>
446 After extraction of the tarball using the tar utility,
447 you have a directory entitled
448 <filename>bitbake-1.17.0</filename>.
449 </para></listitem>
450 <listitem><para><emphasis>Using the BitBake that Comes With Your
451 Build Checkout:</emphasis>
452 A final possibility for getting a copy of BitBake is that it
453 already comes with your checkout of a larger BitBake-based build
454 system, such as Poky.
455 Rather than manually checking out individual layers and
456 gluing them together yourself, you can check
457 out an entire build system.
458 The checkout will already include a version of BitBake that
459 has been thoroughly tested for compatibility with the other
460 components.
461 For information on how to check out a particular BitBake-based
462 build system, consult that build system's supporting documentation.
463 </para></listitem>
464 </itemizedlist>
465 </para>
466 </section>
468 <section id="bitbake-user-manual-command">
469 <title>The BitBake Command</title>
471 <para>
472 The <filename>bitbake</filename> command is the primary interface
473 to the BitBake tool.
474 This section presents the BitBake command syntax and provides
475 several execution examples.
476 </para>
478 <section id='usage-and-syntax'>
479 <title>Usage and syntax</title>
481 <para>
482 Following is the usage and syntax for BitBake:
483 <literallayout class='monospaced'>
484 $ bitbake -h
485 Usage: bitbake [options] [recipename/target recipe:do_task ...]
487 Executes the specified task (default is 'build') for a given set of target recipes (.bb files).
488 It is assumed there is a conf/bblayers.conf available in cwd or in BBPATH which
489 will provide the layer, BBFILES and other configuration information.
491 Options:
492 --version show program's version number and exit
493 -h, --help show this help message and exit
494 -b BUILDFILE, --buildfile=BUILDFILE
495 Execute tasks from a specific .bb recipe directly.
496 WARNING: Does not handle any dependencies from other
497 recipes.
498 -k, --continue Continue as much as possible after an error. While the
499 target that failed and anything depending on it cannot
500 be built, as much as possible will be built before
501 stopping.
502 -f, --force Force the specified targets/task to run (invalidating
503 any existing stamp file).
504 -c CMD, --cmd=CMD Specify the task to execute. The exact options
505 available depend on the metadata. Some examples might
506 be 'compile' or 'populate_sysroot' or 'listtasks' may
507 give a list of the tasks available.
509 Invalidate the stamp for the specified task such as
510 'compile' and then run the default task for the
511 specified target(s).
512 -r PREFILE, --read=PREFILE
513 Read the specified file before bitbake.conf.
514 -R POSTFILE, --postread=POSTFILE
515 Read the specified file after bitbake.conf.
516 -v, --verbose Enable tracing of shell tasks (with 'set -x'). Also
517 print bb.note(...) messages to stdout (in addition to
518 writing them to ${T}/log.do_&lt;task&gt;).
519 -D, --debug Increase the debug level. You can specify this more
520 than once. -D sets the debug level to 1, where only
521 bb.debug(1, ...) messages are printed to stdout; -DD
522 sets the debug level to 2, where both bb.debug(1, ...)
523 and bb.debug(2, ...) messages are printed; etc.
524 Without -D, no debug messages are printed. Note that
525 -D only affects output to stdout. All debug messages
526 are written to ${T}/log.do_taskname, regardless of the
527 debug level.
528 -q, --quiet Output less log message data to the terminal. You can
529 specify this more than once.
530 -n, --dry-run Don't execute, just go through the motions.
532 Dump out the signature construction information, with
533 no task execution. The SIGNATURE_HANDLER parameter is
534 passed to the handler. Two common values are none and
535 printdiff but the handler may define more/less. none
536 means only dump the signature, printdiff means compare
537 the dumped signature with the cached one.
538 -p, --parse-only Quit after parsing the BB recipes.
539 -s, --show-versions Show current and preferred versions of all recipes.
540 -e, --environment Show the global or per-recipe environment complete
541 with information about where variables were
542 set/changed.
543 -g, --graphviz Save dependency tree information for the specified
544 targets in the dot syntax.
546 Assume these dependencies don't exist and are already
547 provided (equivalent to ASSUME_PROVIDED). Useful to
548 make dependency graphs more appealing
549 -l DEBUG_DOMAINS, --log-domains=DEBUG_DOMAINS
550 Show debug logging for the specified logging domains
551 -P, --profile Profile the command and save reports.
552 -u UI, --ui=UI The user interface to use (knotty, ncurses or taskexp
553 - default knotty).
554 --token=XMLRPCTOKEN Specify the connection token to be used when
555 connecting to a remote server.
556 --revisions-changed Set the exit code depending on whether upstream
557 floating revisions have changed or not.
558 --server-only Run bitbake without a UI, only starting a server
559 (cooker) process.
560 -B BIND, --bind=BIND The name/address for the bitbake xmlrpc server to bind
561 to.
563 Set timeout to unload bitbake server due to
564 inactivity, set to -1 means no unload, default:
565 Environment variable BB_SERVER_TIMEOUT.
566 --no-setscene Do not run any setscene tasks. sstate will be ignored
567 and everything needed, built.
568 --setscene-only Only run setscene tasks, don't run any real tasks.
569 --remote-server=REMOTE_SERVER
570 Connect to the specified server.
571 -m, --kill-server Terminate any running bitbake server.
572 --observe-only Connect to a server as an observing-only client.
573 --status-only Check the status of the remote bitbake server.
575 Writes the event log of the build to a bitbake event
576 json file. Use '' (empty string) to assign the name
577 automatically.
578 --runall=RUNALL Run the specified task for any recipe in the taskgraph
579 of the specified target (even if it wouldn't otherwise
580 have run).
581 --runonly=RUNONLY Run only the specified task within the taskgraph of
582 the specified targets (and any task dependencies those
583 tasks may have).
584 </literallayout>
585 </para>
586 </section>
588 <section id='bitbake-examples'>
589 <title>Examples</title>
591 <para>
592 This section presents some examples showing how to use BitBake.
593 </para>
595 <section id='example-executing-a-task-against-a-single-recipe'>
596 <title>Executing a Task Against a Single Recipe</title>
598 <para>
599 Executing tasks for a single recipe file is relatively simple.
600 You specify the file in question, and BitBake parses
601 it and executes the specified task.
602 If you do not specify a task, BitBake executes the default
603 task, which is "build”.
604 BitBake obeys inter-task dependencies when doing
605 so.
606 </para>
608 <para>
609 The following command runs the build task, which is
610 the default task, on the <filename></filename>
611 recipe file:
612 <literallayout class='monospaced'>
613 $ bitbake -b
614 </literallayout>
615 The following command runs the clean task on the
616 <filename></filename> recipe file:
617 <literallayout class='monospaced'>
618 $ bitbake -b -c clean
619 </literallayout>
620 <note>
621 The "-b" option explicitly does not handle recipe
622 dependencies.
623 Other than for debugging purposes, it is instead
624 recommended that you use the syntax presented in the
625 next section.
626 </note>
627 </para>
628 </section>
630 <section id='executing-tasks-against-a-set-of-recipe-files'>
631 <title>Executing Tasks Against a Set of Recipe Files</title>
633 <para>
634 There are a number of additional complexities introduced
635 when one wants to manage multiple <filename>.bb</filename>
636 files.
637 Clearly there needs to be a way to tell BitBake what
638 files are available and, of those, which you
639 want to execute.
640 There also needs to be a way for each recipe
641 to express its dependencies, both for build-time and
642 runtime.
643 There must be a way for you to express recipe preferences
644 when multiple recipes provide the same functionality, or when
645 there are multiple versions of a recipe.
646 </para>
648 <para>
649 The <filename>bitbake</filename> command, when not using
650 "--buildfile" or "-b" only accepts a "PROVIDES".
651 You cannot provide anything else.
652 By default, a recipe file generally "PROVIDES" its
653 "packagename" as shown in the following example:
654 <literallayout class='monospaced'>
655 $ bitbake foo
656 </literallayout>
657 This next example "PROVIDES" the package name and also uses
658 the "-c" option to tell BitBake to just execute the
659 <filename>do_clean</filename> task:
660 <literallayout class='monospaced'>
661 $ bitbake -c clean foo
662 </literallayout>
663 </para>
664 </section>
666 <section id='executing-a-list-of-task-and-recipe-combinations'>
667 <title>Executing a List of Task and Recipe Combinations</title>
669 <para>
670 The BitBake command line supports specifying different
671 tasks for individual targets when you specify multiple
672 targets.
673 For example, suppose you had two targets (or recipes)
674 <filename>myfirstrecipe</filename> and
675 <filename>mysecondrecipe</filename> and you needed
676 BitBake to run <filename>taskA</filename> for the first
677 recipe and <filename>taskB</filename> for the second
678 recipe:
679 <literallayout class='monospaced'>
680 $ bitbake myfirstrecipe:do_taskA mysecondrecipe:do_taskB
681 </literallayout>
682 </para>
683 </section>
685 <section id='generating-dependency-graphs'>
686 <title>Generating Dependency Graphs</title>
688 <para>
689 BitBake is able to generate dependency graphs using
690 the <filename>dot</filename> syntax.
691 You can convert these graphs into images using the
692 <filename>dot</filename> tool from
693 <ulink url=''>Graphviz</ulink>.
694 </para>
696 <para>
697 When you generate a dependency graph, BitBake writes two files
698 to the current working directory:
699 <itemizedlist>
700 <listitem><para>
701 <emphasis><filename></filename>:</emphasis>
702 Shows dependencies between tasks.
703 These dependencies match BitBake's internal task execution list.
704 </para></listitem>
705 <listitem><para>
706 <emphasis><filename>pn-buildlist</filename>:</emphasis>
707 Shows a simple list of targets that are to be built.
708 </para></listitem>
709 </itemizedlist>
710 </para>
712 <para>
713 To stop depending on common depends, use the "-I" depend
714 option and BitBake omits them from the graph.
715 Leaving this information out can produce more readable graphs.
716 This way, you can remove from the graph
717 <filename>DEPENDS</filename> from inherited classes
718 such as <filename>base.bbclass</filename>.
719 </para>
721 <para>
722 Here are two examples that create dependency graphs.
723 The second example omits depends common in OpenEmbedded from
724 the graph:
725 <literallayout class='monospaced'>
726 $ bitbake -g foo
728 $ bitbake -g -I virtual/kernel -I eglibc foo
729 </literallayout>
730 </para>
731 </section>
733 <section id='executing-a-multiple-configuration-build'>
734 <title>Executing a Multiple Configuration Build</title>
736 <para>
737 BitBake is able to build multiple images or packages
738 using a single command where the different targets
739 require different configurations (multiple configuration
740 builds).
741 Each target, in this scenario, is referred to as a
742 "multiconfig".
743 </para>
745 <para>
746 To accomplish a multiple configuration build, you must
747 define each target's configuration separately using
748 a parallel configuration file in the build directory.
749 The location for these multiconfig configuration files
750 is specific.
751 They must reside in the current build directory in
752 a sub-directory of <filename>conf</filename> named
753 <filename>multiconfig</filename>.
754 Following is an example for two separate targets:
755 <imagedata fileref="figures/bb_multiconfig_files.png" align="center" width="4in" depth="3in" />
756 </para>
758 <para>
759 The reason for this required file hierarchy
760 is because the <filename>BBPATH</filename> variable
761 is not constructed until the layers are parsed.
762 Consequently, using the configuration file as a
763 pre-configuration file is not possible unless it is
764 located in the current working directory.
765 </para>
767 <para>
768 Minimally, each configuration file must define the
769 machine and the temporary directory BitBake uses
770 for the build.
771 Suggested practice dictates that you do not
772 overlap the temporary directories used during the
773 builds.
774 </para>
776 <para>
777 Aside from separate configuration files for each
778 target, you must also enable BitBake to perform multiple
779 configuration builds.
780 Enabling is accomplished by setting the
781 <link linkend='var-bb-BBMULTICONFIG'><filename>BBMULTICONFIG</filename></link>
782 variable in the <filename>local.conf</filename>
783 configuration file.
784 As an example, suppose you had configuration files
785 for <filename>target1</filename> and
786 <filename>target2</filename> defined in the build
787 directory.
788 The following statement in the
789 <filename>local.conf</filename> file both enables
790 BitBake to perform multiple configuration builds and
791 specifies the two extra multiconfigs:
792 <literallayout class='monospaced'>
793 BBMULTICONFIG = "target1 target2"
794 </literallayout>
795 </para>
797 <para>
798 Once the target configuration files are in place and
799 BitBake has been enabled to perform multiple configuration
800 builds, use the following command form to start the
801 builds:
802 <literallayout class='monospaced'>
803 $ bitbake [mc:<replaceable>multiconfigname</replaceable>:]<replaceable>target</replaceable> [[[mc:<replaceable>multiconfigname</replaceable>:]<replaceable>target</replaceable>] ... ]
804 </literallayout>
805 Here is an example for two extra multiconfigs:
806 <filename>target1</filename> and
807 <filename>target2</filename>:
808 <literallayout class='monospaced'>
809 $ bitbake mc::<replaceable>target</replaceable> mc:target1:<replaceable>target</replaceable> mc:target2:<replaceable>target</replaceable>
810 </literallayout>
811 </para>
812 </section>
814 <section id='bb-enabling-multiple-configuration-build-dependencies'>
815 <title>Enabling Multiple Configuration Build Dependencies</title>
817 <para>
818 Sometimes dependencies can exist between targets
819 (multiconfigs) in a multiple configuration build.
820 For example, suppose that in order to build an image
821 for a particular architecture, the root filesystem of
822 another build for a different architecture needs to
823 exist.
824 In other words, the image for the first multiconfig depends
825 on the root filesystem of the second multiconfig.
826 This dependency is essentially that the task in the recipe
827 that builds one multiconfig is dependent on the
828 completion of the task in the recipe that builds
829 another multiconfig.
830 </para>
832 <para>
833 To enable dependencies in a multiple configuration
834 build, you must declare the dependencies in the recipe
835 using the following statement form:
836 <literallayout class='monospaced'>
837 <replaceable>task_or_package</replaceable>[mcdepends] = "mc:<replaceable>from_multiconfig</replaceable>:<replaceable>to_multiconfig</replaceable>:<replaceable>recipe_name</replaceable>:<replaceable>task_on_which_to_depend</replaceable>"
838 </literallayout>
839 To better show how to use this statement, consider an
840 example with two multiconfigs: <filename>target1</filename>
841 and <filename>target2</filename>:
842 <literallayout class='monospaced'>
843 <replaceable>image_task</replaceable>[mcdepends] = "mc:target1:target2:<replaceable>image2</replaceable>:<replaceable>rootfs_task</replaceable>"
844 </literallayout>
845 In this example, the
846 <replaceable>from_multiconfig</replaceable> is "target1" and
847 the <replaceable>to_multiconfig</replaceable> is "target2".
848 The task on which the image whose recipe contains
849 <replaceable>image_task</replaceable> depends on the
850 completion of the <replaceable>rootfs_task</replaceable>
851 used to build out <replaceable>image2</replaceable>, which
852 is associated with the "target2" multiconfig.
853 </para>
855 <para>
856 Once you set up this dependency, you can build the
857 "target1" multiconfig using a BitBake command as follows:
858 <literallayout class='monospaced'>
859 $ bitbake mc:target1:<replaceable>image1</replaceable>
860 </literallayout>
861 This command executes all the tasks needed to create
862 <replaceable>image1</replaceable> for the "target1"
863 multiconfig.
864 Because of the dependency, BitBake also executes through
865 the <replaceable>rootfs_task</replaceable> for the "target2"
866 multiconfig build.
867 </para>
869 <para>
870 Having a recipe depend on the root filesystem of another
871 build might not seem that useful.
872 Consider this change to the statement in the
873 <replaceable>image1</replaceable> recipe:
874 <literallayout class='monospaced'>
875 <replaceable>image_task</replaceable>[mcdepends] = "mc:target1:target2:<replaceable>image2</replaceable>:<replaceable>image_task</replaceable>"
876 </literallayout>
877 In this case, BitBake must create
878 <replaceable>image2</replaceable> for the "target2"
879 build since the "target1" build depends on it.
880 </para>
882 <para>
883 Because "target1" and "target2" are enabled for multiple
884 configuration builds and have separate configuration
885 files, BitBake places the artifacts for each build in the
886 respective temporary build directories.
887 </para>
888 </section>
889 </section>
890 </section>