diff options
Diffstat (limited to 'bitbake/doc/bitbake-user-manual/bitbake-user-manual-intro.xml')
-rw-r--r-- | bitbake/doc/bitbake-user-manual/bitbake-user-manual-intro.xml | 891 |
1 files changed, 0 insertions, 891 deletions
diff --git a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-intro.xml b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-intro.xml deleted file mode 100644 index 995c2fa7bf..0000000000 --- a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-intro.xml +++ /dev/null | |||
@@ -1,891 +0,0 @@ | |||
1 | <!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>How to assemble the generated artifacts into | ||
225 | one or more installable packages</para></listitem> | ||
226 | <listitem><para>Where on the target machine to install the | ||
227 | package or packages created</para></listitem> | ||
228 | </itemizedlist> | ||
229 | </para> | ||
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> | ||
234 | extension are referred to as <firstterm>recipes</firstterm>. | ||
235 | <note> | ||
236 | The term "package" is also commonly used to describe recipes. | ||
237 | However, since the same word is used to describe packaged | ||
238 | output from a project, it is best to maintain a single | ||
239 | descriptive term - "recipes". | ||
240 | Put another way, a single "recipe" file is quite capable | ||
241 | of generating a number of related but separately installable | ||
242 | "packages". | ||
243 | In fact, that ability is fairly common. | ||
244 | </note> | ||
245 | </para> | ||
246 | </section> | ||
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 | ||
257 | machine configuration, distribution configuration, | ||
258 | possible compiler tuning, general common | ||
259 | configuration, and user configuration. | ||
260 | The main configuration file is the sample | ||
261 | <filename>bitbake.conf</filename> file, which is | ||
262 | located within the BitBake source tree | ||
263 | <filename>conf</filename> directory. | ||
264 | </para> | ||
265 | </section> | ||
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 | ||
297 | when working on a single project, the more modular | ||
298 | 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, | ||
305 | rather than a general layer, called a <firstterm>Board Support Package</firstterm> (BSP) | ||
306 | layer. | ||
307 | Furthermore, the machine customizations should be isolated from | ||
308 | recipes and metadata that support a new GUI environment, for | ||
309 | example. | ||
310 | This situation gives you a couple of layers: one for the machine | ||
311 | configurations and one for the GUI environment. | ||
312 | It is important to understand, however, that the BSP layer can still | ||
313 | make machine-specific additions to recipes within | ||
314 | the GUI environment layer without polluting the GUI layer itself | ||
315 | with those machine-specific changes. | ||
316 | You can accomplish this through a recipe that is a BitBake append | ||
317 | (<filename>.bbappend</filename>) file. | ||
318 | </para> | ||
319 | </section> | ||
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 | ||
347 | "<filename>%</filename>" wildcard character to allow for matching | ||
348 | recipe names. | ||
349 | For example, suppose you have an append file named | ||
350 | as follows: | ||
351 | <literallayout class='monospaced'> | ||
352 | busybox_1.21.%.bbappend | ||
353 | </literallayout> | ||
354 | That append file would match any <filename>busybox_1.21.</filename><replaceable>x</replaceable><filename>.bb</filename> | ||
355 | version of the recipe. | ||
356 | So, the append file would match the following recipe names: | ||
357 | <literallayout class='monospaced'> | ||
358 | busybox_1.21.1.bb | ||
359 | busybox_1.21.2.bb | ||
360 | busybox_1.21.3.bb | ||
361 | </literallayout> | ||
362 | <note><title>Important</title> | ||
363 | The use of the "<filename>%</filename>" character | ||
364 | is limited in that it only works directly in front of the | ||
365 | <filename>.bbappend</filename> portion of the append file's | ||
366 | name. | ||
367 | You cannot use the wildcard character in any other | ||
368 | location of the name. | ||
369 | </note> | ||
370 | If the <filename>busybox</filename> recipe was updated to | ||
371 | <filename>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 | ||
453 | already comes with your checkout of a larger BitBake-based build | ||
454 | system, such as Poky. | ||
455 | Rather than manually checking out individual layers and | ||
456 | gluing them together yourself, you can check | ||
457 | out an entire build system. | ||
458 | The checkout will already include a version of BitBake that | ||
459 | has been thoroughly tested for compatibility with the other | ||
460 | components. | ||
461 | For information on how to check out a particular BitBake-based | ||
462 | build system, consult that build system's supporting documentation. | ||
463 | </para></listitem> | ||
464 | </itemizedlist> | ||
465 | </para> | ||
466 | </section> | ||
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 | ||
485 | Usage: bitbake [options] [recipename/target recipe:do_task ...] | ||
486 | |||
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. | ||
502 | -f, --force Force the specified targets/task to run (invalidating | ||
503 | any existing stamp file). | ||
504 | -c CMD, --cmd=CMD Specify the task to execute. The exact options | ||
505 | available depend on the metadata. Some examples might | ||
506 | be 'compile' or 'populate_sysroot' or 'listtasks' may | ||
507 | give a list of the tasks available. | ||
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. | ||
516 | -v, --verbose Enable tracing of shell tasks (with 'set -x'). Also | ||
517 | print bb.note(...) messages to stdout (in addition to | ||
518 | writing them to ${T}/log.do_<task>). | ||
519 | -D, --debug Increase the debug level. You can specify this more | ||
520 | than once. -D sets the debug level to 1, where only | ||
521 | bb.debug(1, ...) messages are printed to stdout; -DD | ||
522 | sets the debug level to 2, where both bb.debug(1, ...) | ||
523 | and bb.debug(2, ...) messages are printed; etc. | ||
524 | Without -D, no debug messages are printed. Note that | ||
525 | -D only affects output to stdout. All debug messages | ||
526 | are written to ${T}/log.do_taskname, regardless of the | ||
527 | debug level. | ||
528 | -q, --quiet Output less log message data to the terminal. You can | ||
529 | specify this more than once. | ||
530 | -n, --dry-run Don't execute, just go through the motions. | ||
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. | ||
552 | -u UI, --ui=UI The user interface to use (knotty, ncurses or taskexp | ||
553 | - default knotty). | ||
554 | --token=XMLRPCTOKEN Specify the connection token to be used when | ||
555 | connecting to a remote server. | ||
556 | --revisions-changed Set the exit code depending on whether upstream | ||
557 | floating revisions have changed or not. | ||
558 | --server-only Run bitbake without a UI, only starting a server | ||
559 | (cooker) process. | ||
560 | -B BIND, --bind=BIND The name/address for the bitbake xmlrpc server to bind | ||
561 | to. | ||
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. | ||
566 | --no-setscene Do not run any setscene tasks. sstate will be ignored | ||
567 | and everything needed, built. | ||
568 | --setscene-only Only run setscene tasks, don't run any real tasks. | ||
569 | --remote-server=REMOTE_SERVER | ||
570 | Connect to the specified server. | ||
571 | -m, --kill-server Terminate any running bitbake server. | ||
572 | --observe-only Connect to a server as an observing-only client. | ||
573 | --status-only Check the status of the remote bitbake server. | ||
574 | -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. | ||
578 | --runall=RUNALL Run the specified task for any recipe in the taskgraph | ||
579 | of the specified target (even if it wouldn't otherwise | ||
580 | have run). | ||
581 | --runonly=RUNONLY Run only the specified task within the taskgraph of | ||
582 | the specified targets (and any task dependencies those | ||
583 | tasks may have). | ||
584 | </literallayout> | ||
585 | </para> | ||
586 | </section> | ||
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 | |||
666 | <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 | |||
685 | <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> | ||
697 | When you generate a dependency graph, BitBake writes two files | ||
698 | to the current working directory: | ||
699 | <itemizedlist> | ||
700 | <listitem><para> | ||
701 | <emphasis><filename>task-depends.dot</filename>:</emphasis> | ||
702 | Shows dependencies between tasks. | ||
703 | These dependencies match BitBake's internal task execution list. | ||
704 | </para></listitem> | ||
705 | <listitem><para> | ||
706 | <emphasis><filename>pn-buildlist</filename>:</emphasis> | ||
707 | Shows a simple list of targets that are to be built. | ||
708 | </para></listitem> | ||
709 | </itemizedlist> | ||
710 | </para> | ||
711 | |||
712 | <para> | ||
713 | To stop depending on common depends, use the "-I" depend | ||
714 | option and BitBake omits them from the graph. | ||
715 | Leaving this information out can produce more readable graphs. | ||
716 | This way, you can remove from the graph | ||
717 | <filename>DEPENDS</filename> from inherited classes | ||
718 | such as <filename>base.bbclass</filename>. | ||
719 | </para> | ||
720 | |||
721 | <para> | ||
722 | Here are two examples that create dependency graphs. | ||
723 | The second example omits depends common in OpenEmbedded from | ||
724 | the graph: | ||
725 | <literallayout class='monospaced'> | ||
726 | $ bitbake -g foo | ||
727 | |||
728 | $ bitbake -g -I virtual/kernel -I eglibc foo | ||
729 | </literallayout> | ||
730 | </para> | ||
731 | </section> | ||
732 | |||
733 | <section id='executing-a-multiple-configuration-build'> | ||
734 | <title>Executing a Multiple Configuration Build</title> | ||
735 | |||
736 | <para> | ||
737 | BitBake is able to build multiple images or packages | ||
738 | using a single command where the different targets | ||
739 | require different configurations (multiple configuration | ||
740 | builds). | ||
741 | Each target, in this scenario, is referred to as a | ||
742 | "multiconfig". | ||
743 | </para> | ||
744 | |||
745 | <para> | ||
746 | To accomplish a multiple configuration build, you must | ||
747 | define each target's configuration separately using | ||
748 | a parallel configuration file in the build directory. | ||
749 | The location for these multiconfig configuration files | ||
750 | is specific. | ||
751 | They must reside in the current build directory in | ||
752 | a sub-directory of <filename>conf</filename> named | ||
753 | <filename>multiconfig</filename>. | ||
754 | Following is an example for two separate targets: | ||
755 | <imagedata fileref="figures/bb_multiconfig_files.png" align="center" width="4in" depth="3in" /> | ||
756 | </para> | ||
757 | |||
758 | <para> | ||
759 | The reason for this required file hierarchy | ||
760 | is because the <filename>BBPATH</filename> variable | ||
761 | is not constructed until the layers are parsed. | ||
762 | Consequently, using the configuration file as a | ||
763 | pre-configuration file is not possible unless it is | ||
764 | located in the current working directory. | ||
765 | </para> | ||
766 | |||
767 | <para> | ||
768 | Minimally, each configuration file must define the | ||
769 | machine and the temporary directory BitBake uses | ||
770 | for the build. | ||
771 | Suggested practice dictates that you do not | ||
772 | overlap the temporary directories used during the | ||
773 | builds. | ||
774 | </para> | ||
775 | |||
776 | <para> | ||
777 | Aside from separate configuration files for each | ||
778 | target, you must also enable BitBake to perform multiple | ||
779 | configuration builds. | ||
780 | Enabling is accomplished by setting the | ||
781 | <link linkend='var-bb-BBMULTICONFIG'><filename>BBMULTICONFIG</filename></link> | ||
782 | variable in the <filename>local.conf</filename> | ||
783 | configuration file. | ||
784 | As an example, suppose you had configuration files | ||
785 | for <filename>target1</filename> and | ||
786 | <filename>target2</filename> defined in the build | ||
787 | directory. | ||
788 | The following statement in the | ||
789 | <filename>local.conf</filename> file both enables | ||
790 | BitBake to perform multiple configuration builds and | ||
791 | specifies the two extra multiconfigs: | ||
792 | <literallayout class='monospaced'> | ||
793 | BBMULTICONFIG = "target1 target2" | ||
794 | </literallayout> | ||
795 | </para> | ||
796 | |||
797 | <para> | ||
798 | Once the target configuration files are in place and | ||
799 | BitBake has been enabled to perform multiple configuration | ||
800 | builds, use the following command form to start the | ||
801 | builds: | ||
802 | <literallayout class='monospaced'> | ||
803 | $ bitbake [mc:<replaceable>multiconfigname</replaceable>:]<replaceable>target</replaceable> [[[mc:<replaceable>multiconfigname</replaceable>:]<replaceable>target</replaceable>] ... ] | ||
804 | </literallayout> | ||
805 | Here is an example for two extra multiconfigs: | ||
806 | <filename>target1</filename> and | ||
807 | <filename>target2</filename>: | ||
808 | <literallayout class='monospaced'> | ||
809 | $ bitbake mc::<replaceable>target</replaceable> mc:target1:<replaceable>target</replaceable> mc:target2:<replaceable>target</replaceable> | ||
810 | </literallayout> | ||
811 | </para> | ||
812 | </section> | ||
813 | |||
814 | <section id='bb-enabling-multiple-configuration-build-dependencies'> | ||
815 | <title>Enabling Multiple Configuration Build Dependencies</title> | ||
816 | |||
817 | <para> | ||
818 | Sometimes dependencies can exist between targets | ||
819 | (multiconfigs) in a multiple configuration build. | ||
820 | For example, suppose that in order to build an image | ||
821 | for a particular architecture, the root filesystem of | ||
822 | another build for a different architecture needs to | ||
823 | exist. | ||
824 | In other words, the image for the first multiconfig depends | ||
825 | on the root filesystem of the second multiconfig. | ||
826 | This dependency is essentially that the task in the recipe | ||
827 | that builds one multiconfig is dependent on the | ||
828 | completion of the task in the recipe that builds | ||
829 | another multiconfig. | ||
830 | </para> | ||
831 | |||
832 | <para> | ||
833 | To enable dependencies in a multiple configuration | ||
834 | build, you must declare the dependencies in the recipe | ||
835 | using the following statement form: | ||
836 | <literallayout class='monospaced'> | ||
837 | <replaceable>task_or_package</replaceable>[mcdepends] = "mc:<replaceable>from_multiconfig</replaceable>:<replaceable>to_multiconfig</replaceable>:<replaceable>recipe_name</replaceable>:<replaceable>task_on_which_to_depend</replaceable>" | ||
838 | </literallayout> | ||
839 | To better show how to use this statement, consider an | ||
840 | example with two multiconfigs: <filename>target1</filename> | ||
841 | and <filename>target2</filename>: | ||
842 | <literallayout class='monospaced'> | ||
843 | <replaceable>image_task</replaceable>[mcdepends] = "mc:target1:target2:<replaceable>image2</replaceable>:<replaceable>rootfs_task</replaceable>" | ||
844 | </literallayout> | ||
845 | In this example, the | ||
846 | <replaceable>from_multiconfig</replaceable> is "target1" and | ||
847 | the <replaceable>to_multiconfig</replaceable> is "target2". | ||
848 | The task on which the image whose recipe contains | ||
849 | <replaceable>image_task</replaceable> depends on the | ||
850 | completion of the <replaceable>rootfs_task</replaceable> | ||
851 | used to build out <replaceable>image2</replaceable>, which | ||
852 | is associated with the "target2" multiconfig. | ||
853 | </para> | ||
854 | |||
855 | <para> | ||
856 | Once you set up this dependency, you can build the | ||
857 | "target1" multiconfig using a BitBake command as follows: | ||
858 | <literallayout class='monospaced'> | ||
859 | $ bitbake mc:target1:<replaceable>image1</replaceable> | ||
860 | </literallayout> | ||
861 | This command executes all the tasks needed to create | ||
862 | <replaceable>image1</replaceable> for the "target1" | ||
863 | multiconfig. | ||
864 | Because of the dependency, BitBake also executes through | ||
865 | the <replaceable>rootfs_task</replaceable> for the "target2" | ||
866 | multiconfig build. | ||
867 | </para> | ||
868 | |||
869 | <para> | ||
870 | Having a recipe depend on the root filesystem of another | ||
871 | build might not seem that useful. | ||
872 | Consider this change to the statement in the | ||
873 | <replaceable>image1</replaceable> recipe: | ||
874 | <literallayout class='monospaced'> | ||
875 | <replaceable>image_task</replaceable>[mcdepends] = "mc:target1:target2:<replaceable>image2</replaceable>:<replaceable>image_task</replaceable>" | ||
876 | </literallayout> | ||
877 | In this case, BitBake must create | ||
878 | <replaceable>image2</replaceable> for the "target2" | ||
879 | build since the "target1" build depends on it. | ||
880 | </para> | ||
881 | |||
882 | <para> | ||
883 | Because "target1" and "target2" are enabled for multiple | ||
884 | configuration builds and have separate configuration | ||
885 | files, BitBake places the artifacts for each build in the | ||
886 | respective temporary build directories. | ||
887 | </para> | ||
888 | </section> | ||
889 | </section> | ||
890 | </section> | ||
891 | </chapter> | ||