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