blob: f5526c053eab5210432148a998bae99427b60fba [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>
Andrew Geissler82c905d2020-04-13 13:39:40 -0500130 Be self-contained, rather than tightly
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500131 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>
Andrew Geissler82c905d2020-04-13 13:39:40 -0500224 <listitem><para>How to assemble the generated artifacts into
225 one or more installable packages</para></listitem>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500226 <listitem><para>Where on the target machine to install the
227 package or packages created</para></listitem>
228 </itemizedlist>
229 </para>
230
231 <para>
232 Within the context of BitBake, or any project utilizing BitBake
233 as its build system, files with the <filename>.bb</filename>
Andrew Geissler82c905d2020-04-13 13:39:40 -0500234 extension are referred to as <firstterm>recipes</firstterm>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500235 <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>
247
248 <section id='configuration-files'>
249 <title>Configuration Files</title>
250
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
Andrew Geissler82c905d2020-04-13 13:39:40 -0500257 machine configuration, distribution configuration,
258 possible compiler tuning, general common
259 configuration, and user configuration.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500260 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>
266
267 <section id='classes'>
268 <title>Classes</title>
269
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>
289
290 <section id='layers'>
291 <title>Layers</title>
292
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
Andrew Geissler82c905d2020-04-13 13:39:40 -0500297 when working on a single project, the more modular
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500298 your metadata, the easier it is to cope with future changes.
299 </para>
300
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,
Andrew Geissler82c905d2020-04-13 13:39:40 -0500305 rather than a general layer, called a <firstterm>Board Support Package</firstterm> (BSP)
306 layer.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500307 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>
320
321 <section id='append-bbappend-files'>
322 <title>Append Files</title>
323
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>
329
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>formfactor_0.0.bb</filename> and
336 <filename>formfactor_0.0.bbappend</filename>).
337 </para>
338
339 <para>
340 Information in append files extends or
341 overrides the information in the underlying,
342 similarly-named recipe files.
343 </para>
344
345 <para>
346 When you name an append file, you can use the
Brad Bishop1a4b7ee2018-12-16 17:11:34 -0800347 "<filename>%</filename>" wildcard character to allow for matching
348 recipe names.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500349 For example, suppose you have an append file named
350 as follows:
351 <literallayout class='monospaced'>
352 busybox_1.21.%.bbappend
353 </literallayout>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -0800354 That append file would match any <filename>busybox_1.21.</filename><replaceable>x</replaceable><filename>.bb</filename>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500355 version of the recipe.
356 So, the append file would match the following recipe names:
357 <literallayout class='monospaced'>
358 busybox_1.21.1.bb
359 busybox_1.21.2.bb
360 busybox_1.21.3.bb
361 </literallayout>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -0800362 <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>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500370 If the <filename>busybox</filename> recipe was updated to
371 <filename>busybox_1.3.0.bb</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>
376
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>
384
385 <section id='obtaining-bitbake'>
386 <title>Obtaining BitBake</title>
387
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://git.openembedded.org/bitbake
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://git.openembedded.org/bitbake 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 http://git.openembedded.org/bitbake/snapshot/bitbake-1.17.0.tar.gz
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
Andrew Geissler82c905d2020-04-13 13:39:40 -0500453 already comes with your checkout of a larger BitBake-based build
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500454 system, such as Poky.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500455 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>
467
468 <section id="bitbake-user-manual-command">
469 <title>The BitBake Command</title>
470
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>
477
478 <section id='usage-and-syntax'>
479 <title>Usage and syntax</title>
480
481 <para>
482 Following is the usage and syntax for BitBake:
483 <literallayout class='monospaced'>
484 $ bitbake -h
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500485 Usage: bitbake [options] [recipename/target recipe:do_task ...]
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500486
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.
490
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.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500502 -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.
508 -C INVALIDATE_STAMP, --clear-stamp=INVALIDATE_STAMP
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.
Brad Bishop316dfdd2018-06-25 12:45:53 -0400516 -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.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500530 -n, --dry-run Don't execute, just go through the motions.
531 -S SIGNATURE_HANDLER, --dump-signatures=SIGNATURE_HANDLER
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.
545 -I EXTRA_ASSUME_PROVIDED, --ignore-deps=EXTRA_ASSUME_PROVIDED
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.
Brad Bishop316dfdd2018-06-25 12:45:53 -0400552 -u UI, --ui=UI The user interface to use (knotty, ncurses or taskexp
553 - default knotty).
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500554 --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.
Brad Bishop316dfdd2018-06-25 12:45:53 -0400560 -B BIND, --bind=BIND The name/address for the bitbake xmlrpc server to bind
561 to.
562 -T SERVER_TIMEOUT, --idle-timeout=SERVER_TIMEOUT
563 Set timeout to unload bitbake server due to
564 inactivity, set to -1 means no unload, default:
565 Environment variable BB_SERVER_TIMEOUT.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500566 --no-setscene Do not run any setscene tasks. sstate will be ignored
567 and everything needed, built.
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500568 --setscene-only Only run setscene tasks, don't run any real tasks.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500569 --remote-server=REMOTE_SERVER
570 Connect to the specified server.
Brad Bishop316dfdd2018-06-25 12:45:53 -0400571 -m, --kill-server Terminate any running bitbake server.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500572 --observe-only Connect to a server as an observing-only client.
573 --status-only Check the status of the remote bitbake server.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500574 -w WRITEEVENTLOG, --write-log=WRITEEVENTLOG
575 Writes the event log of the build to a bitbake event
576 json file. Use '' (empty string) to assign the name
577 automatically.
Brad Bishop316dfdd2018-06-25 12:45:53 -0400578 --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).
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500584 </literallayout>
585 </para>
586 </section>
587
588 <section id='bitbake-examples'>
589 <title>Examples</title>
590
591 <para>
592 This section presents some examples showing how to use BitBake.
593 </para>
594
595 <section id='example-executing-a-task-against-a-single-recipe'>
596 <title>Executing a Task Against a Single Recipe</title>
597
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>
607
608 <para>
609 The following command runs the build task, which is
610 the default task, on the <filename>foo_1.0.bb</filename>
611 recipe file:
612 <literallayout class='monospaced'>
613 $ bitbake -b foo_1.0.bb
614 </literallayout>
615 The following command runs the clean task on the
616 <filename>foo.bb</filename> recipe file:
617 <literallayout class='monospaced'>
618 $ bitbake -b foo.bb -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>
629
630 <section id='executing-tasks-against-a-set-of-recipe-files'>
631 <title>Executing Tasks Against a Set of Recipe Files</title>
632
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>
647
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>
665
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600666 <section id='executing-a-list-of-task-and-recipe-combinations'>
667 <title>Executing a List of Task and Recipe Combinations</title>
668
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>
684
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500685 <section id='generating-dependency-graphs'>
686 <title>Generating Dependency Graphs</title>
687
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='http://www.graphviz.org'>Graphviz</ulink>.
694 </para>
695
696 <para>
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500697 When you generate a dependency graph, BitBake writes three files
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500698 to the current working directory:
699 <itemizedlist>
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500700 <listitem><para>
701 <emphasis><filename>recipe-depends.dot</filename>:</emphasis>
702 Shows dependencies between recipes (i.e. a collapsed version of
703 <filename>task-depends.dot</filename>).
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500704 </para></listitem>
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500705 <listitem><para>
706 <emphasis><filename>task-depends.dot</filename>:</emphasis>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500707 Shows dependencies between tasks.
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500708 These dependencies match BitBake's internal task execution list.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500709 </para></listitem>
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500710 <listitem><para>
711 <emphasis><filename>pn-buildlist</filename>:</emphasis>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500712 Shows a simple list of targets that are to be built.
713 </para></listitem>
714 </itemizedlist>
715 </para>
716
717 <para>
718 To stop depending on common depends, use the "-I" depend
719 option and BitBake omits them from the graph.
720 Leaving this information out can produce more readable graphs.
721 This way, you can remove from the graph
722 <filename>DEPENDS</filename> from inherited classes
723 such as <filename>base.bbclass</filename>.
724 </para>
725
726 <para>
727 Here are two examples that create dependency graphs.
728 The second example omits depends common in OpenEmbedded from
729 the graph:
730 <literallayout class='monospaced'>
731 $ bitbake -g foo
732
733 $ bitbake -g -I virtual/kernel -I eglibc foo
734 </literallayout>
735 </para>
736 </section>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -0800737
738 <section id='executing-a-multiple-configuration-build'>
739 <title>Executing a Multiple Configuration Build</title>
740
741 <para>
742 BitBake is able to build multiple images or packages
743 using a single command where the different targets
744 require different configurations (multiple configuration
745 builds).
746 Each target, in this scenario, is referred to as a
747 "multiconfig".
748 </para>
749
750 <para>
751 To accomplish a multiple configuration build, you must
752 define each target's configuration separately using
753 a parallel configuration file in the build directory.
754 The location for these multiconfig configuration files
755 is specific.
756 They must reside in the current build directory in
757 a sub-directory of <filename>conf</filename> named
758 <filename>multiconfig</filename>.
759 Following is an example for two separate targets:
760 <imagedata fileref="figures/bb_multiconfig_files.png" align="center" width="4in" depth="3in" />
761 </para>
762
763 <para>
764 The reason for this required file hierarchy
765 is because the <filename>BBPATH</filename> variable
766 is not constructed until the layers are parsed.
767 Consequently, using the configuration file as a
768 pre-configuration file is not possible unless it is
769 located in the current working directory.
770 </para>
771
772 <para>
773 Minimally, each configuration file must define the
774 machine and the temporary directory BitBake uses
775 for the build.
776 Suggested practice dictates that you do not
777 overlap the temporary directories used during the
778 builds.
779 </para>
780
781 <para>
782 Aside from separate configuration files for each
783 target, you must also enable BitBake to perform multiple
784 configuration builds.
785 Enabling is accomplished by setting the
Brad Bishop19323692019-04-05 15:28:33 -0400786 <link linkend='var-bb-BBMULTICONFIG'><filename>BBMULTICONFIG</filename></link>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -0800787 variable in the <filename>local.conf</filename>
788 configuration file.
789 As an example, suppose you had configuration files
790 for <filename>target1</filename> and
791 <filename>target2</filename> defined in the build
792 directory.
793 The following statement in the
794 <filename>local.conf</filename> file both enables
795 BitBake to perform multiple configuration builds and
Brad Bishopf3f93bb2019-10-16 14:33:32 -0400796 specifies the two extra multiconfigs:
Brad Bishop1a4b7ee2018-12-16 17:11:34 -0800797 <literallayout class='monospaced'>
798 BBMULTICONFIG = "target1 target2"
799 </literallayout>
800 </para>
801
802 <para>
803 Once the target configuration files are in place and
804 BitBake has been enabled to perform multiple configuration
805 builds, use the following command form to start the
806 builds:
807 <literallayout class='monospaced'>
Brad Bishopf3f93bb2019-10-16 14:33:32 -0400808 $ bitbake [mc:<replaceable>multiconfigname</replaceable>:]<replaceable>target</replaceable> [[[mc:<replaceable>multiconfigname</replaceable>:]<replaceable>target</replaceable>] ... ]
Brad Bishop1a4b7ee2018-12-16 17:11:34 -0800809 </literallayout>
Brad Bishopf3f93bb2019-10-16 14:33:32 -0400810 Here is an example for two extra multiconfigs:
Brad Bishop1a4b7ee2018-12-16 17:11:34 -0800811 <filename>target1</filename> and
812 <filename>target2</filename>:
813 <literallayout class='monospaced'>
Brad Bishopf3f93bb2019-10-16 14:33:32 -0400814 $ bitbake mc::<replaceable>target</replaceable> mc:target1:<replaceable>target</replaceable> mc:target2:<replaceable>target</replaceable>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -0800815 </literallayout>
816 </para>
817 </section>
818
819 <section id='bb-enabling-multiple-configuration-build-dependencies'>
820 <title>Enabling Multiple Configuration Build Dependencies</title>
821
822 <para>
823 Sometimes dependencies can exist between targets
824 (multiconfigs) in a multiple configuration build.
825 For example, suppose that in order to build an image
826 for a particular architecture, the root filesystem of
827 another build for a different architecture needs to
828 exist.
829 In other words, the image for the first multiconfig depends
830 on the root filesystem of the second multiconfig.
831 This dependency is essentially that the task in the recipe
832 that builds one multiconfig is dependent on the
833 completion of the task in the recipe that builds
834 another multiconfig.
835 </para>
836
837 <para>
838 To enable dependencies in a multiple configuration
839 build, you must declare the dependencies in the recipe
840 using the following statement form:
841 <literallayout class='monospaced'>
Brad Bishopf3f93bb2019-10-16 14:33:32 -0400842 <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 -0800843 </literallayout>
844 To better show how to use this statement, consider an
845 example with two multiconfigs: <filename>target1</filename>
846 and <filename>target2</filename>:
847 <literallayout class='monospaced'>
Brad Bishopf3f93bb2019-10-16 14:33:32 -0400848 <replaceable>image_task</replaceable>[mcdepends] = "mc:target1:target2:<replaceable>image2</replaceable>:<replaceable>rootfs_task</replaceable>"
Brad Bishop1a4b7ee2018-12-16 17:11:34 -0800849 </literallayout>
850 In this example, the
851 <replaceable>from_multiconfig</replaceable> is "target1" and
852 the <replaceable>to_multiconfig</replaceable> is "target2".
853 The task on which the image whose recipe contains
854 <replaceable>image_task</replaceable> depends on the
855 completion of the <replaceable>rootfs_task</replaceable>
856 used to build out <replaceable>image2</replaceable>, which
857 is associated with the "target2" multiconfig.
858 </para>
859
860 <para>
861 Once you set up this dependency, you can build the
862 "target1" multiconfig using a BitBake command as follows:
863 <literallayout class='monospaced'>
Brad Bishopf3f93bb2019-10-16 14:33:32 -0400864 $ bitbake mc:target1:<replaceable>image1</replaceable>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -0800865 </literallayout>
866 This command executes all the tasks needed to create
867 <replaceable>image1</replaceable> for the "target1"
868 multiconfig.
869 Because of the dependency, BitBake also executes through
870 the <replaceable>rootfs_task</replaceable> for the "target2"
871 multiconfig build.
872 </para>
873
874 <para>
875 Having a recipe depend on the root filesystem of another
876 build might not seem that useful.
877 Consider this change to the statement in the
878 <replaceable>image1</replaceable> recipe:
879 <literallayout class='monospaced'>
Brad Bishopf3f93bb2019-10-16 14:33:32 -0400880 <replaceable>image_task</replaceable>[mcdepends] = "mc:target1:target2:<replaceable>image2</replaceable>:<replaceable>image_task</replaceable>"
Brad Bishop1a4b7ee2018-12-16 17:11:34 -0800881 </literallayout>
882 In this case, BitBake must create
883 <replaceable>image2</replaceable> for the "target2"
884 build since the "target1" build depends on it.
885 </para>
886
887 <para>
888 Because "target1" and "target2" are enabled for multiple
889 configuration builds and have separate configuration
890 files, BitBake places the artifacts for each build in the
891 respective temporary build directories.
892 </para>
893 </section>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500894 </section>
895 </section>
896</chapter>