blob: 8f2a960cacdabb7f0577dc6dc512b59c144c6ee0 [file] [log] [blame]
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
3
4<chapter id="bitbake-user-manual-intro">
5 <title>Overview</title>
6
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>
17
18 <section id="intro">
19 <title>Introduction</title>
20
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>
30
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>
67
68 <section id="history-and-goals">
69 <title>History and Goals</title>
70
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="http://www.openembedded.org/">OpenEmbedded</ulink>
84 project, which is being used to build and maintain Linux
85 distributions such as the
86 <ulink url='http://www.angstrom-distribution.org/'>Angstrom Distribution</ulink>,
87 and which is also being used as the build tool for Linux projects
88 such as the
89 <ulink url='http://www.yoctoproject.org'>Yocto Project</ulink>.
90 </para>
91
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>
100
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>
177
178 <section id="Concepts">
179 <title>Concepts</title>
180
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>
190
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>
197
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>
203
204 <section id='recipes'>
205 <title>Recipes</title>
206
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>Where on the target machine to install the
225 package or packages created</para></listitem>
226 </itemizedlist>
227 </para>
228
229 <para>
230 Within the context of BitBake, or any project utilizing BitBake
231 as its build system, files with the <filename>.bb</filename>
232 extension are referred to as recipes.
233 <note>
234 The term "package" is also commonly used to describe recipes.
235 However, since the same word is used to describe packaged
236 output from a project, it is best to maintain a single
237 descriptive term - "recipes".
238 Put another way, a single "recipe" file is quite capable
239 of generating a number of related but separately installable
240 "packages".
241 In fact, that ability is fairly common.
242 </note>
243 </para>
244 </section>
245
246 <section id='configuration-files'>
247 <title>Configuration Files</title>
248
249 <para>
250 Configuration files, which are denoted by the
251 <filename>.conf</filename> extension, define
252 various configuration variables that govern the project's build
253 process.
254 These files fall into several areas that define
255 machine configuration options, distribution configuration
256 options, compiler tuning options, general common
257 configuration options, and user configuration options.
258 The main configuration file is the sample
259 <filename>bitbake.conf</filename> file, which is
260 located within the BitBake source tree
261 <filename>conf</filename> directory.
262 </para>
263 </section>
264
265 <section id='classes'>
266 <title>Classes</title>
267
268 <para>
269 Class files, which are denoted by the
270 <filename>.bbclass</filename> extension, contain
271 information that is useful to share between metadata files.
272 The BitBake source tree currently comes with one class metadata file
273 called <filename>base.bbclass</filename>.
274 You can find this file in the
275 <filename>classes</filename> directory.
276 The <filename>base.bbclass</filename> class files is special since it
277 is always included automatically for all recipes
278 and classes.
279 This class contains definitions for standard basic tasks such
280 as fetching, unpacking, configuring (empty by default),
281 compiling (runs any Makefile present), installing (empty by
282 default) and packaging (empty by default).
283 These tasks are often overridden or extended by other classes
284 added during the project development process.
285 </para>
286 </section>
287
288 <section id='layers'>
289 <title>Layers</title>
290
291 <para>
292 Layers allow you to isolate different types of
293 customizations from each other.
294 While you might find it tempting to keep everything in one layer
295 when working on a single project, the more modular you organize
296 your metadata, the easier it is to cope with future changes.
297 </para>
298
299 <para>
300 To illustrate how you can use layers to keep things modular,
301 consider customizations you might make to support a specific target machine.
302 These types of customizations typically reside in a special layer,
303 rather than a general layer, called a Board Support Package (BSP)
304 Layer.
305 Furthermore, the machine customizations should be isolated from
306 recipes and metadata that support a new GUI environment, for
307 example.
308 This situation gives you a couple of layers: one for the machine
309 configurations and one for the GUI environment.
310 It is important to understand, however, that the BSP layer can still
311 make machine-specific additions to recipes within
312 the GUI environment layer without polluting the GUI layer itself
313 with those machine-specific changes.
314 You can accomplish this through a recipe that is a BitBake append
315 (<filename>.bbappend</filename>) file.
316 </para>
317 </section>
318
319 <section id='append-bbappend-files'>
320 <title>Append Files</title>
321
322 <para>
323 Append files, which are files that have the
324 <filename>.bbappend</filename> file extension, extend or
325 override information in an existing recipe file.
326 </para>
327
328 <para>
329 BitBake expects every append file to have a corresponding recipe file.
330 Furthermore, the append file and corresponding recipe file
331 must use the same root filename.
332 The filenames can differ only in the file type suffix used
333 (e.g. <filename>formfactor_0.0.bb</filename> and
334 <filename>formfactor_0.0.bbappend</filename>).
335 </para>
336
337 <para>
338 Information in append files extends or
339 overrides the information in the underlying,
340 similarly-named recipe files.
341 </para>
342
343 <para>
344 When you name an append file, you can use the
Brad Bishop1a4b7ee2018-12-16 17:11:34 -0800345 "<filename>%</filename>" wildcard character to allow for matching
346 recipe names.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500347 For example, suppose you have an append file named
348 as follows:
349 <literallayout class='monospaced'>
350 busybox_1.21.%.bbappend
351 </literallayout>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -0800352 That append file would match any <filename>busybox_1.21.</filename><replaceable>x</replaceable><filename>.bb</filename>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500353 version of the recipe.
354 So, the append file would match the following recipe names:
355 <literallayout class='monospaced'>
356 busybox_1.21.1.bb
357 busybox_1.21.2.bb
358 busybox_1.21.3.bb
359 </literallayout>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -0800360 <note><title>Important</title>
361 The use of the "<filename>%</filename>" character
362 is limited in that it only works directly in front of the
363 <filename>.bbappend</filename> portion of the append file's
364 name.
365 You cannot use the wildcard character in any other
366 location of the name.
367 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500368 If the <filename>busybox</filename> recipe was updated to
369 <filename>busybox_1.3.0.bb</filename>, the append name would not
370 match.
371 However, if you named the append file
372 <filename>busybox_1.%.bbappend</filename>, then you would have a match.
373 </para>
374
375 <para>
376 In the most general case, you could name the append file something as
377 simple as <filename>busybox_%.bbappend</filename> to be entirely
378 version independent.
379 </para>
380 </section>
381 </section>
382
383 <section id='obtaining-bitbake'>
384 <title>Obtaining BitBake</title>
385
386 <para>
387 You can obtain BitBake several different ways:
388 <itemizedlist>
389 <listitem><para><emphasis>Cloning BitBake:</emphasis>
390 Using Git to clone the BitBake source code repository
391 is the recommended method for obtaining BitBake.
392 Cloning the repository makes it easy to get bug fixes
393 and have access to stable branches and the master
394 branch.
395 Once you have cloned BitBake, you should use
396 the latest stable
397 branch for development since the master branch is for
398 BitBake development and might contain less stable changes.
399 </para>
400 <para>You usually need a version of BitBake
401 that matches the metadata you are using.
402 The metadata is generally backwards compatible but
403 not forward compatible.</para>
404 <para>Here is an example that clones the BitBake repository:
405 <literallayout class='monospaced'>
406 $ git clone git://git.openembedded.org/bitbake
407 </literallayout>
408 This command clones the BitBake Git repository into a
409 directory called <filename>bitbake</filename>.
410 Alternatively, you can
411 designate a directory after the
412 <filename>git clone</filename> command
413 if you want to call the new directory something
414 other than <filename>bitbake</filename>.
415 Here is an example that names the directory
416 <filename>bbdev</filename>:
417 <literallayout class='monospaced'>
418 $ git clone git://git.openembedded.org/bitbake bbdev
419 </literallayout></para></listitem>
420 <listitem><para><emphasis>Installation using your Distribution
421 Package Management System:</emphasis>
422 This method is not
423 recommended because the BitBake version that is
424 provided by your distribution, in most cases,
425 is several
426 releases behind a snapshot of the BitBake repository.
427 </para></listitem>
428 <listitem><para><emphasis>Taking a snapshot of BitBake:</emphasis>
429 Downloading a snapshot of BitBake from the
430 source code repository gives you access to a known
431 branch or release of BitBake.
432 <note>
433 Cloning the Git repository, as described earlier,
434 is the preferred method for getting BitBake.
435 Cloning the repository makes it easier to update as
436 patches are added to the stable branches.
437 </note></para>
438 <para>The following example downloads a snapshot of
439 BitBake version 1.17.0:
440 <literallayout class='monospaced'>
441 $ wget http://git.openembedded.org/bitbake/snapshot/bitbake-1.17.0.tar.gz
442 $ tar zxpvf bitbake-1.17.0.tar.gz
443 </literallayout>
444 After extraction of the tarball using the tar utility,
445 you have a directory entitled
446 <filename>bitbake-1.17.0</filename>.
447 </para></listitem>
448 <listitem><para><emphasis>Using the BitBake that Comes With Your
449 Build Checkout:</emphasis>
450 A final possibility for getting a copy of BitBake is that it
451 already comes with your checkout of a larger Bitbake-based build
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500452 system, such as Poky.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500453 Rather than manually checking out individual layers and
454 gluing them together yourself, you can check
455 out an entire build system.
456 The checkout will already include a version of BitBake that
457 has been thoroughly tested for compatibility with the other
458 components.
459 For information on how to check out a particular BitBake-based
460 build system, consult that build system's supporting documentation.
461 </para></listitem>
462 </itemizedlist>
463 </para>
464 </section>
465
466 <section id="bitbake-user-manual-command">
467 <title>The BitBake Command</title>
468
469 <para>
470 The <filename>bitbake</filename> command is the primary interface
471 to the BitBake tool.
472 This section presents the BitBake command syntax and provides
473 several execution examples.
474 </para>
475
476 <section id='usage-and-syntax'>
477 <title>Usage and syntax</title>
478
479 <para>
480 Following is the usage and syntax for BitBake:
481 <literallayout class='monospaced'>
482 $ bitbake -h
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500483 Usage: bitbake [options] [recipename/target recipe:do_task ...]
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500484
485 Executes the specified task (default is 'build') for a given set of target recipes (.bb files).
486 It is assumed there is a conf/bblayers.conf available in cwd or in BBPATH which
487 will provide the layer, BBFILES and other configuration information.
488
489 Options:
490 --version show program's version number and exit
491 -h, --help show this help message and exit
492 -b BUILDFILE, --buildfile=BUILDFILE
493 Execute tasks from a specific .bb recipe directly.
494 WARNING: Does not handle any dependencies from other
495 recipes.
496 -k, --continue Continue as much as possible after an error. While the
497 target that failed and anything depending on it cannot
498 be built, as much as possible will be built before
499 stopping.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500500 -f, --force Force the specified targets/task to run (invalidating
501 any existing stamp file).
502 -c CMD, --cmd=CMD Specify the task to execute. The exact options
503 available depend on the metadata. Some examples might
504 be 'compile' or 'populate_sysroot' or 'listtasks' may
505 give a list of the tasks available.
506 -C INVALIDATE_STAMP, --clear-stamp=INVALIDATE_STAMP
507 Invalidate the stamp for the specified task such as
508 'compile' and then run the default task for the
509 specified target(s).
510 -r PREFILE, --read=PREFILE
511 Read the specified file before bitbake.conf.
512 -R POSTFILE, --postread=POSTFILE
513 Read the specified file after bitbake.conf.
Brad Bishop316dfdd2018-06-25 12:45:53 -0400514 -v, --verbose Enable tracing of shell tasks (with 'set -x'). Also
515 print bb.note(...) messages to stdout (in addition to
516 writing them to ${T}/log.do_&lt;task&gt;).
517 -D, --debug Increase the debug level. You can specify this more
518 than once. -D sets the debug level to 1, where only
519 bb.debug(1, ...) messages are printed to stdout; -DD
520 sets the debug level to 2, where both bb.debug(1, ...)
521 and bb.debug(2, ...) messages are printed; etc.
522 Without -D, no debug messages are printed. Note that
523 -D only affects output to stdout. All debug messages
524 are written to ${T}/log.do_taskname, regardless of the
525 debug level.
526 -q, --quiet Output less log message data to the terminal. You can
527 specify this more than once.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500528 -n, --dry-run Don't execute, just go through the motions.
529 -S SIGNATURE_HANDLER, --dump-signatures=SIGNATURE_HANDLER
530 Dump out the signature construction information, with
531 no task execution. The SIGNATURE_HANDLER parameter is
532 passed to the handler. Two common values are none and
533 printdiff but the handler may define more/less. none
534 means only dump the signature, printdiff means compare
535 the dumped signature with the cached one.
536 -p, --parse-only Quit after parsing the BB recipes.
537 -s, --show-versions Show current and preferred versions of all recipes.
538 -e, --environment Show the global or per-recipe environment complete
539 with information about where variables were
540 set/changed.
541 -g, --graphviz Save dependency tree information for the specified
542 targets in the dot syntax.
543 -I EXTRA_ASSUME_PROVIDED, --ignore-deps=EXTRA_ASSUME_PROVIDED
544 Assume these dependencies don't exist and are already
545 provided (equivalent to ASSUME_PROVIDED). Useful to
546 make dependency graphs more appealing
547 -l DEBUG_DOMAINS, --log-domains=DEBUG_DOMAINS
548 Show debug logging for the specified logging domains
549 -P, --profile Profile the command and save reports.
Brad Bishop316dfdd2018-06-25 12:45:53 -0400550 -u UI, --ui=UI The user interface to use (knotty, ncurses or taskexp
551 - default knotty).
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500552 --token=XMLRPCTOKEN Specify the connection token to be used when
553 connecting to a remote server.
554 --revisions-changed Set the exit code depending on whether upstream
555 floating revisions have changed or not.
556 --server-only Run bitbake without a UI, only starting a server
557 (cooker) process.
Brad Bishop316dfdd2018-06-25 12:45:53 -0400558 -B BIND, --bind=BIND The name/address for the bitbake xmlrpc server to bind
559 to.
560 -T SERVER_TIMEOUT, --idle-timeout=SERVER_TIMEOUT
561 Set timeout to unload bitbake server due to
562 inactivity, set to -1 means no unload, default:
563 Environment variable BB_SERVER_TIMEOUT.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500564 --no-setscene Do not run any setscene tasks. sstate will be ignored
565 and everything needed, built.
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500566 --setscene-only Only run setscene tasks, don't run any real tasks.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500567 --remote-server=REMOTE_SERVER
568 Connect to the specified server.
Brad Bishop316dfdd2018-06-25 12:45:53 -0400569 -m, --kill-server Terminate any running bitbake server.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500570 --observe-only Connect to a server as an observing-only client.
571 --status-only Check the status of the remote bitbake server.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500572 -w WRITEEVENTLOG, --write-log=WRITEEVENTLOG
573 Writes the event log of the build to a bitbake event
574 json file. Use '' (empty string) to assign the name
575 automatically.
Brad Bishop316dfdd2018-06-25 12:45:53 -0400576 --runall=RUNALL Run the specified task for any recipe in the taskgraph
577 of the specified target (even if it wouldn't otherwise
578 have run).
579 --runonly=RUNONLY Run only the specified task within the taskgraph of
580 the specified targets (and any task dependencies those
581 tasks may have).
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500582 </literallayout>
583 </para>
584 </section>
585
586 <section id='bitbake-examples'>
587 <title>Examples</title>
588
589 <para>
590 This section presents some examples showing how to use BitBake.
591 </para>
592
593 <section id='example-executing-a-task-against-a-single-recipe'>
594 <title>Executing a Task Against a Single Recipe</title>
595
596 <para>
597 Executing tasks for a single recipe file is relatively simple.
598 You specify the file in question, and BitBake parses
599 it and executes the specified task.
600 If you do not specify a task, BitBake executes the default
601 task, which is "build”.
602 BitBake obeys inter-task dependencies when doing
603 so.
604 </para>
605
606 <para>
607 The following command runs the build task, which is
608 the default task, on the <filename>foo_1.0.bb</filename>
609 recipe file:
610 <literallayout class='monospaced'>
611 $ bitbake -b foo_1.0.bb
612 </literallayout>
613 The following command runs the clean task on the
614 <filename>foo.bb</filename> recipe file:
615 <literallayout class='monospaced'>
616 $ bitbake -b foo.bb -c clean
617 </literallayout>
618 <note>
619 The "-b" option explicitly does not handle recipe
620 dependencies.
621 Other than for debugging purposes, it is instead
622 recommended that you use the syntax presented in the
623 next section.
624 </note>
625 </para>
626 </section>
627
628 <section id='executing-tasks-against-a-set-of-recipe-files'>
629 <title>Executing Tasks Against a Set of Recipe Files</title>
630
631 <para>
632 There are a number of additional complexities introduced
633 when one wants to manage multiple <filename>.bb</filename>
634 files.
635 Clearly there needs to be a way to tell BitBake what
636 files are available and, of those, which you
637 want to execute.
638 There also needs to be a way for each recipe
639 to express its dependencies, both for build-time and
640 runtime.
641 There must be a way for you to express recipe preferences
642 when multiple recipes provide the same functionality, or when
643 there are multiple versions of a recipe.
644 </para>
645
646 <para>
647 The <filename>bitbake</filename> command, when not using
648 "--buildfile" or "-b" only accepts a "PROVIDES".
649 You cannot provide anything else.
650 By default, a recipe file generally "PROVIDES" its
651 "packagename" as shown in the following example:
652 <literallayout class='monospaced'>
653 $ bitbake foo
654 </literallayout>
655 This next example "PROVIDES" the package name and also uses
656 the "-c" option to tell BitBake to just execute the
657 <filename>do_clean</filename> task:
658 <literallayout class='monospaced'>
659 $ bitbake -c clean foo
660 </literallayout>
661 </para>
662 </section>
663
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600664 <section id='executing-a-list-of-task-and-recipe-combinations'>
665 <title>Executing a List of Task and Recipe Combinations</title>
666
667 <para>
668 The BitBake command line supports specifying different
669 tasks for individual targets when you specify multiple
670 targets.
671 For example, suppose you had two targets (or recipes)
672 <filename>myfirstrecipe</filename> and
673 <filename>mysecondrecipe</filename> and you needed
674 BitBake to run <filename>taskA</filename> for the first
675 recipe and <filename>taskB</filename> for the second
676 recipe:
677 <literallayout class='monospaced'>
678 $ bitbake myfirstrecipe:do_taskA mysecondrecipe:do_taskB
679 </literallayout>
680 </para>
681 </section>
682
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500683 <section id='generating-dependency-graphs'>
684 <title>Generating Dependency Graphs</title>
685
686 <para>
687 BitBake is able to generate dependency graphs using
688 the <filename>dot</filename> syntax.
689 You can convert these graphs into images using the
690 <filename>dot</filename> tool from
691 <ulink url='http://www.graphviz.org'>Graphviz</ulink>.
692 </para>
693
694 <para>
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500695 When you generate a dependency graph, BitBake writes three files
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500696 to the current working directory:
697 <itemizedlist>
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500698 <listitem><para>
699 <emphasis><filename>recipe-depends.dot</filename>:</emphasis>
700 Shows dependencies between recipes (i.e. a collapsed version of
701 <filename>task-depends.dot</filename>).
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500702 </para></listitem>
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500703 <listitem><para>
704 <emphasis><filename>task-depends.dot</filename>:</emphasis>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500705 Shows dependencies between tasks.
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500706 These dependencies match BitBake's internal task execution list.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500707 </para></listitem>
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500708 <listitem><para>
709 <emphasis><filename>pn-buildlist</filename>:</emphasis>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500710 Shows a simple list of targets that are to be built.
711 </para></listitem>
712 </itemizedlist>
713 </para>
714
715 <para>
716 To stop depending on common depends, use the "-I" depend
717 option and BitBake omits them from the graph.
718 Leaving this information out can produce more readable graphs.
719 This way, you can remove from the graph
720 <filename>DEPENDS</filename> from inherited classes
721 such as <filename>base.bbclass</filename>.
722 </para>
723
724 <para>
725 Here are two examples that create dependency graphs.
726 The second example omits depends common in OpenEmbedded from
727 the graph:
728 <literallayout class='monospaced'>
729 $ bitbake -g foo
730
731 $ bitbake -g -I virtual/kernel -I eglibc foo
732 </literallayout>
733 </para>
734 </section>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -0800735
736 <section id='executing-a-multiple-configuration-build'>
737 <title>Executing a Multiple Configuration Build</title>
738
739 <para>
740 BitBake is able to build multiple images or packages
741 using a single command where the different targets
742 require different configurations (multiple configuration
743 builds).
744 Each target, in this scenario, is referred to as a
745 "multiconfig".
746 </para>
747
748 <para>
749 To accomplish a multiple configuration build, you must
750 define each target's configuration separately using
751 a parallel configuration file in the build directory.
752 The location for these multiconfig configuration files
753 is specific.
754 They must reside in the current build directory in
755 a sub-directory of <filename>conf</filename> named
756 <filename>multiconfig</filename>.
757 Following is an example for two separate targets:
758 <imagedata fileref="figures/bb_multiconfig_files.png" align="center" width="4in" depth="3in" />
759 </para>
760
761 <para>
762 The reason for this required file hierarchy
763 is because the <filename>BBPATH</filename> variable
764 is not constructed until the layers are parsed.
765 Consequently, using the configuration file as a
766 pre-configuration file is not possible unless it is
767 located in the current working directory.
768 </para>
769
770 <para>
771 Minimally, each configuration file must define the
772 machine and the temporary directory BitBake uses
773 for the build.
774 Suggested practice dictates that you do not
775 overlap the temporary directories used during the
776 builds.
777 </para>
778
779 <para>
780 Aside from separate configuration files for each
781 target, you must also enable BitBake to perform multiple
782 configuration builds.
783 Enabling is accomplished by setting the
Brad Bishop19323692019-04-05 15:28:33 -0400784 <link linkend='var-bb-BBMULTICONFIG'><filename>BBMULTICONFIG</filename></link>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -0800785 variable in the <filename>local.conf</filename>
786 configuration file.
787 As an example, suppose you had configuration files
788 for <filename>target1</filename> and
789 <filename>target2</filename> defined in the build
790 directory.
791 The following statement in the
792 <filename>local.conf</filename> file both enables
793 BitBake to perform multiple configuration builds and
Brad Bishopf3f93bb2019-10-16 14:33:32 -0400794 specifies the two extra multiconfigs:
Brad Bishop1a4b7ee2018-12-16 17:11:34 -0800795 <literallayout class='monospaced'>
796 BBMULTICONFIG = "target1 target2"
797 </literallayout>
798 </para>
799
800 <para>
801 Once the target configuration files are in place and
802 BitBake has been enabled to perform multiple configuration
803 builds, use the following command form to start the
804 builds:
805 <literallayout class='monospaced'>
Brad Bishopf3f93bb2019-10-16 14:33:32 -0400806 $ bitbake [mc:<replaceable>multiconfigname</replaceable>:]<replaceable>target</replaceable> [[[mc:<replaceable>multiconfigname</replaceable>:]<replaceable>target</replaceable>] ... ]
Brad Bishop1a4b7ee2018-12-16 17:11:34 -0800807 </literallayout>
Brad Bishopf3f93bb2019-10-16 14:33:32 -0400808 Here is an example for two extra multiconfigs:
Brad Bishop1a4b7ee2018-12-16 17:11:34 -0800809 <filename>target1</filename> and
810 <filename>target2</filename>:
811 <literallayout class='monospaced'>
Brad Bishopf3f93bb2019-10-16 14:33:32 -0400812 $ bitbake mc::<replaceable>target</replaceable> mc:target1:<replaceable>target</replaceable> mc:target2:<replaceable>target</replaceable>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -0800813 </literallayout>
814 </para>
815 </section>
816
817 <section id='bb-enabling-multiple-configuration-build-dependencies'>
818 <title>Enabling Multiple Configuration Build Dependencies</title>
819
820 <para>
821 Sometimes dependencies can exist between targets
822 (multiconfigs) in a multiple configuration build.
823 For example, suppose that in order to build an image
824 for a particular architecture, the root filesystem of
825 another build for a different architecture needs to
826 exist.
827 In other words, the image for the first multiconfig depends
828 on the root filesystem of the second multiconfig.
829 This dependency is essentially that the task in the recipe
830 that builds one multiconfig is dependent on the
831 completion of the task in the recipe that builds
832 another multiconfig.
833 </para>
834
835 <para>
836 To enable dependencies in a multiple configuration
837 build, you must declare the dependencies in the recipe
838 using the following statement form:
839 <literallayout class='monospaced'>
Brad Bishopf3f93bb2019-10-16 14:33:32 -0400840 <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>"
Brad Bishop1a4b7ee2018-12-16 17:11:34 -0800841 </literallayout>
842 To better show how to use this statement, consider an
843 example with two multiconfigs: <filename>target1</filename>
844 and <filename>target2</filename>:
845 <literallayout class='monospaced'>
Brad Bishopf3f93bb2019-10-16 14:33:32 -0400846 <replaceable>image_task</replaceable>[mcdepends] = "mc:target1:target2:<replaceable>image2</replaceable>:<replaceable>rootfs_task</replaceable>"
Brad Bishop1a4b7ee2018-12-16 17:11:34 -0800847 </literallayout>
848 In this example, the
849 <replaceable>from_multiconfig</replaceable> is "target1" and
850 the <replaceable>to_multiconfig</replaceable> is "target2".
851 The task on which the image whose recipe contains
852 <replaceable>image_task</replaceable> depends on the
853 completion of the <replaceable>rootfs_task</replaceable>
854 used to build out <replaceable>image2</replaceable>, which
855 is associated with the "target2" multiconfig.
856 </para>
857
858 <para>
859 Once you set up this dependency, you can build the
860 "target1" multiconfig using a BitBake command as follows:
861 <literallayout class='monospaced'>
Brad Bishopf3f93bb2019-10-16 14:33:32 -0400862 $ bitbake mc:target1:<replaceable>image1</replaceable>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -0800863 </literallayout>
864 This command executes all the tasks needed to create
865 <replaceable>image1</replaceable> for the "target1"
866 multiconfig.
867 Because of the dependency, BitBake also executes through
868 the <replaceable>rootfs_task</replaceable> for the "target2"
869 multiconfig build.
870 </para>
871
872 <para>
873 Having a recipe depend on the root filesystem of another
874 build might not seem that useful.
875 Consider this change to the statement in the
876 <replaceable>image1</replaceable> recipe:
877 <literallayout class='monospaced'>
Brad Bishopf3f93bb2019-10-16 14:33:32 -0400878 <replaceable>image_task</replaceable>[mcdepends] = "mc:target1:target2:<replaceable>image2</replaceable>:<replaceable>image_task</replaceable>"
Brad Bishop1a4b7ee2018-12-16 17:11:34 -0800879 </literallayout>
880 In this case, BitBake must create
881 <replaceable>image2</replaceable> for the "target2"
882 build since the "target1" build depends on it.
883 </para>
884
885 <para>
886 Because "target1" and "target2" are enabled for multiple
887 configuration builds and have separate configuration
888 files, BitBake places the artifacts for each build in the
889 respective temporary build directories.
890 </para>
891 </section>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500892 </section>
893 </section>
894</chapter>