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 | 685 |
1 files changed, 685 insertions, 0 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 new file mode 100644 index 0000000000..2188655de3 --- /dev/null +++ b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-intro.xml | |||
@@ -0,0 +1,685 @@ | |||
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>Where on the target machine to install the | ||
225 | package or packages created</para></listitem> | ||
226 | </itemizedlist> | ||
227 | </para> | ||
228 | |||
229 | <para> | ||
230 | Within the context of BitBake, or any project utilizing BitBake | ||
231 | as its build system, files with the <filename>.bb</filename> | ||
232 | extension are referred to as recipes. | ||
233 | <note> | ||
234 | The term "package" is also commonly used to describe recipes. | ||
235 | However, since the same word is used to describe packaged | ||
236 | output from a project, it is best to maintain a single | ||
237 | descriptive term - "recipes". | ||
238 | Put another way, a single "recipe" file is quite capable | ||
239 | of generating a number of related but separately installable | ||
240 | "packages". | ||
241 | In fact, that ability is fairly common. | ||
242 | </note> | ||
243 | </para> | ||
244 | </section> | ||
245 | |||
246 | <section id='configuration-files'> | ||
247 | <title>Configuration Files</title> | ||
248 | |||
249 | <para> | ||
250 | Configuration files, which are denoted by the | ||
251 | <filename>.conf</filename> extension, define | ||
252 | various configuration variables that govern the project's build | ||
253 | process. | ||
254 | These files fall into several areas that define | ||
255 | machine configuration options, distribution configuration | ||
256 | options, compiler tuning options, general common | ||
257 | configuration options, and user configuration options. | ||
258 | The main configuration file is the sample | ||
259 | <filename>bitbake.conf</filename> file, which is | ||
260 | located within the BitBake source tree | ||
261 | <filename>conf</filename> directory. | ||
262 | </para> | ||
263 | </section> | ||
264 | |||
265 | <section id='classes'> | ||
266 | <title>Classes</title> | ||
267 | |||
268 | <para> | ||
269 | Class files, which are denoted by the | ||
270 | <filename>.bbclass</filename> extension, contain | ||
271 | information that is useful to share between metadata files. | ||
272 | The BitBake source tree currently comes with one class metadata file | ||
273 | called <filename>base.bbclass</filename>. | ||
274 | You can find this file in the | ||
275 | <filename>classes</filename> directory. | ||
276 | The <filename>base.bbclass</filename> class files is special since it | ||
277 | is always included automatically for all recipes | ||
278 | and classes. | ||
279 | This class contains definitions for standard basic tasks such | ||
280 | as fetching, unpacking, configuring (empty by default), | ||
281 | compiling (runs any Makefile present), installing (empty by | ||
282 | default) and packaging (empty by default). | ||
283 | These tasks are often overridden or extended by other classes | ||
284 | added during the project development process. | ||
285 | </para> | ||
286 | </section> | ||
287 | |||
288 | <section id='layers'> | ||
289 | <title>Layers</title> | ||
290 | |||
291 | <para> | ||
292 | Layers allow you to isolate different types of | ||
293 | customizations from each other. | ||
294 | While you might find it tempting to keep everything in one layer | ||
295 | when working on a single project, the more modular you organize | ||
296 | your metadata, the easier it is to cope with future changes. | ||
297 | </para> | ||
298 | |||
299 | <para> | ||
300 | To illustrate how you can use layers to keep things modular, | ||
301 | consider customizations you might make to support a specific target machine. | ||
302 | These types of customizations typically reside in a special layer, | ||
303 | rather than a general layer, called a Board Support Package (BSP) | ||
304 | Layer. | ||
305 | Furthermore, the machine customizations should be isolated from | ||
306 | recipes and metadata that support a new GUI environment, for | ||
307 | example. | ||
308 | This situation gives you a couple of layers: one for the machine | ||
309 | configurations and one for the GUI environment. | ||
310 | It is important to understand, however, that the BSP layer can still | ||
311 | make machine-specific additions to recipes within | ||
312 | the GUI environment layer without polluting the GUI layer itself | ||
313 | with those machine-specific changes. | ||
314 | You can accomplish this through a recipe that is a BitBake append | ||
315 | (<filename>.bbappend</filename>) file. | ||
316 | </para> | ||
317 | </section> | ||
318 | |||
319 | <section id='append-bbappend-files'> | ||
320 | <title>Append Files</title> | ||
321 | |||
322 | <para> | ||
323 | Append files, which are files that have the | ||
324 | <filename>.bbappend</filename> file extension, extend or | ||
325 | override information in an existing recipe file. | ||
326 | </para> | ||
327 | |||
328 | <para> | ||
329 | BitBake expects every append file to have a corresponding recipe file. | ||
330 | Furthermore, the append file and corresponding recipe file | ||
331 | must use the same root filename. | ||
332 | The filenames can differ only in the file type suffix used | ||
333 | (e.g. <filename>formfactor_0.0.bb</filename> and | ||
334 | <filename>formfactor_0.0.bbappend</filename>). | ||
335 | </para> | ||
336 | |||
337 | <para> | ||
338 | Information in append files extends or | ||
339 | overrides the information in the underlying, | ||
340 | similarly-named recipe files. | ||
341 | </para> | ||
342 | |||
343 | <para> | ||
344 | When you name an append file, you can use the | ||
345 | wildcard character (%) to allow for matching recipe names. | ||
346 | For example, suppose you have an append file named | ||
347 | as follows: | ||
348 | <literallayout class='monospaced'> | ||
349 | busybox_1.21.%.bbappend | ||
350 | </literallayout> | ||
351 | That append file would match any <filename>busybox_1.21.x.bb</filename> | ||
352 | version of the recipe. | ||
353 | So, the append file would match the following recipe names: | ||
354 | <literallayout class='monospaced'> | ||
355 | busybox_1.21.1.bb | ||
356 | busybox_1.21.2.bb | ||
357 | busybox_1.21.3.bb | ||
358 | </literallayout> | ||
359 | If the <filename>busybox</filename> recipe was updated to | ||
360 | <filename>busybox_1.3.0.bb</filename>, the append name would not | ||
361 | match. | ||
362 | However, if you named the append file | ||
363 | <filename>busybox_1.%.bbappend</filename>, then you would have a match. | ||
364 | </para> | ||
365 | |||
366 | <para> | ||
367 | In the most general case, you could name the append file something as | ||
368 | simple as <filename>busybox_%.bbappend</filename> to be entirely | ||
369 | version independent. | ||
370 | </para> | ||
371 | </section> | ||
372 | </section> | ||
373 | |||
374 | <section id='obtaining-bitbake'> | ||
375 | <title>Obtaining BitBake</title> | ||
376 | |||
377 | <para> | ||
378 | You can obtain BitBake several different ways: | ||
379 | <itemizedlist> | ||
380 | <listitem><para><emphasis>Cloning BitBake:</emphasis> | ||
381 | Using Git to clone the BitBake source code repository | ||
382 | is the recommended method for obtaining BitBake. | ||
383 | Cloning the repository makes it easy to get bug fixes | ||
384 | and have access to stable branches and the master | ||
385 | branch. | ||
386 | Once you have cloned BitBake, you should use | ||
387 | the latest stable | ||
388 | branch for development since the master branch is for | ||
389 | BitBake development and might contain less stable changes. | ||
390 | </para> | ||
391 | <para>You usually need a version of BitBake | ||
392 | that matches the metadata you are using. | ||
393 | The metadata is generally backwards compatible but | ||
394 | not forward compatible.</para> | ||
395 | <para>Here is an example that clones the BitBake repository: | ||
396 | <literallayout class='monospaced'> | ||
397 | $ git clone git://git.openembedded.org/bitbake | ||
398 | </literallayout> | ||
399 | This command clones the BitBake Git repository into a | ||
400 | directory called <filename>bitbake</filename>. | ||
401 | Alternatively, you can | ||
402 | designate a directory after the | ||
403 | <filename>git clone</filename> command | ||
404 | if you want to call the new directory something | ||
405 | other than <filename>bitbake</filename>. | ||
406 | Here is an example that names the directory | ||
407 | <filename>bbdev</filename>: | ||
408 | <literallayout class='monospaced'> | ||
409 | $ git clone git://git.openembedded.org/bitbake bbdev | ||
410 | </literallayout></para></listitem> | ||
411 | <listitem><para><emphasis>Installation using your Distribution | ||
412 | Package Management System:</emphasis> | ||
413 | This method is not | ||
414 | recommended because the BitBake version that is | ||
415 | provided by your distribution, in most cases, | ||
416 | is several | ||
417 | releases behind a snapshot of the BitBake repository. | ||
418 | </para></listitem> | ||
419 | <listitem><para><emphasis>Taking a snapshot of BitBake:</emphasis> | ||
420 | Downloading a snapshot of BitBake from the | ||
421 | source code repository gives you access to a known | ||
422 | branch or release of BitBake. | ||
423 | <note> | ||
424 | Cloning the Git repository, as described earlier, | ||
425 | is the preferred method for getting BitBake. | ||
426 | Cloning the repository makes it easier to update as | ||
427 | patches are added to the stable branches. | ||
428 | </note></para> | ||
429 | <para>The following example downloads a snapshot of | ||
430 | BitBake version 1.17.0: | ||
431 | <literallayout class='monospaced'> | ||
432 | $ wget http://git.openembedded.org/bitbake/snapshot/bitbake-1.17.0.tar.gz | ||
433 | $ tar zxpvf bitbake-1.17.0.tar.gz | ||
434 | </literallayout> | ||
435 | After extraction of the tarball using the tar utility, | ||
436 | you have a directory entitled | ||
437 | <filename>bitbake-1.17.0</filename>. | ||
438 | </para></listitem> | ||
439 | <listitem><para><emphasis>Using the BitBake that Comes With Your | ||
440 | Build Checkout:</emphasis> | ||
441 | A final possibility for getting a copy of BitBake is that it | ||
442 | already comes with your checkout of a larger Bitbake-based build | ||
443 | system, such as Poky or Yocto Project. | ||
444 | Rather than manually checking out individual layers and | ||
445 | gluing them together yourself, you can check | ||
446 | out an entire build system. | ||
447 | The checkout will already include a version of BitBake that | ||
448 | has been thoroughly tested for compatibility with the other | ||
449 | components. | ||
450 | For information on how to check out a particular BitBake-based | ||
451 | build system, consult that build system's supporting documentation. | ||
452 | </para></listitem> | ||
453 | </itemizedlist> | ||
454 | </para> | ||
455 | </section> | ||
456 | |||
457 | <section id="bitbake-user-manual-command"> | ||
458 | <title>The BitBake Command</title> | ||
459 | |||
460 | <para> | ||
461 | The <filename>bitbake</filename> command is the primary interface | ||
462 | to the BitBake tool. | ||
463 | This section presents the BitBake command syntax and provides | ||
464 | several execution examples. | ||
465 | </para> | ||
466 | |||
467 | <section id='usage-and-syntax'> | ||
468 | <title>Usage and syntax</title> | ||
469 | |||
470 | <para> | ||
471 | Following is the usage and syntax for BitBake: | ||
472 | <literallayout class='monospaced'> | ||
473 | $ bitbake -h | ||
474 | Usage: bitbake [options] [recipename/target ...] | ||
475 | |||
476 | Executes the specified task (default is 'build') for a given set of target recipes (.bb files). | ||
477 | It is assumed there is a conf/bblayers.conf available in cwd or in BBPATH which | ||
478 | will provide the layer, BBFILES and other configuration information. | ||
479 | |||
480 | Options: | ||
481 | --version show program's version number and exit | ||
482 | -h, --help show this help message and exit | ||
483 | -b BUILDFILE, --buildfile=BUILDFILE | ||
484 | Execute tasks from a specific .bb recipe directly. | ||
485 | WARNING: Does not handle any dependencies from other | ||
486 | recipes. | ||
487 | -k, --continue Continue as much as possible after an error. While the | ||
488 | target that failed and anything depending on it cannot | ||
489 | be built, as much as possible will be built before | ||
490 | stopping. | ||
491 | -a, --tryaltconfigs Continue with builds by trying to use alternative | ||
492 | providers where possible. | ||
493 | -f, --force Force the specified targets/task to run (invalidating | ||
494 | any existing stamp file). | ||
495 | -c CMD, --cmd=CMD Specify the task to execute. The exact options | ||
496 | available depend on the metadata. Some examples might | ||
497 | be 'compile' or 'populate_sysroot' or 'listtasks' may | ||
498 | give a list of the tasks available. | ||
499 | -C INVALIDATE_STAMP, --clear-stamp=INVALIDATE_STAMP | ||
500 | Invalidate the stamp for the specified task such as | ||
501 | 'compile' and then run the default task for the | ||
502 | specified target(s). | ||
503 | -r PREFILE, --read=PREFILE | ||
504 | Read the specified file before bitbake.conf. | ||
505 | -R POSTFILE, --postread=POSTFILE | ||
506 | Read the specified file after bitbake.conf. | ||
507 | -v, --verbose Output more log message data to the terminal. | ||
508 | -D, --debug Increase the debug level. You can specify this more | ||
509 | than once. | ||
510 | -n, --dry-run Don't execute, just go through the motions. | ||
511 | -S SIGNATURE_HANDLER, --dump-signatures=SIGNATURE_HANDLER | ||
512 | Dump out the signature construction information, with | ||
513 | no task execution. The SIGNATURE_HANDLER parameter is | ||
514 | passed to the handler. Two common values are none and | ||
515 | printdiff but the handler may define more/less. none | ||
516 | means only dump the signature, printdiff means compare | ||
517 | the dumped signature with the cached one. | ||
518 | -p, --parse-only Quit after parsing the BB recipes. | ||
519 | -s, --show-versions Show current and preferred versions of all recipes. | ||
520 | -e, --environment Show the global or per-recipe environment complete | ||
521 | with information about where variables were | ||
522 | set/changed. | ||
523 | -g, --graphviz Save dependency tree information for the specified | ||
524 | targets in the dot syntax. | ||
525 | -I EXTRA_ASSUME_PROVIDED, --ignore-deps=EXTRA_ASSUME_PROVIDED | ||
526 | Assume these dependencies don't exist and are already | ||
527 | provided (equivalent to ASSUME_PROVIDED). Useful to | ||
528 | make dependency graphs more appealing | ||
529 | -l DEBUG_DOMAINS, --log-domains=DEBUG_DOMAINS | ||
530 | Show debug logging for the specified logging domains | ||
531 | -P, --profile Profile the command and save reports. | ||
532 | -u UI, --ui=UI The user interface to use (e.g. knotty, hob, depexp). | ||
533 | -t SERVERTYPE, --servertype=SERVERTYPE | ||
534 | Choose which server to use, process or xmlrpc. | ||
535 | --token=XMLRPCTOKEN Specify the connection token to be used when | ||
536 | connecting to a remote server. | ||
537 | --revisions-changed Set the exit code depending on whether upstream | ||
538 | floating revisions have changed or not. | ||
539 | --server-only Run bitbake without a UI, only starting a server | ||
540 | (cooker) process. | ||
541 | -B BIND, --bind=BIND The name/address for the bitbake server to bind to. | ||
542 | --no-setscene Do not run any setscene tasks. sstate will be ignored | ||
543 | and everything needed, built. | ||
544 | --remote-server=REMOTE_SERVER | ||
545 | Connect to the specified server. | ||
546 | -m, --kill-server Terminate the remote server. | ||
547 | --observe-only Connect to a server as an observing-only client. | ||
548 | --status-only Check the status of the remote bitbake server. | ||
549 | </literallayout> | ||
550 | </para> | ||
551 | </section> | ||
552 | |||
553 | <section id='bitbake-examples'> | ||
554 | <title>Examples</title> | ||
555 | |||
556 | <para> | ||
557 | This section presents some examples showing how to use BitBake. | ||
558 | </para> | ||
559 | |||
560 | <section id='example-executing-a-task-against-a-single-recipe'> | ||
561 | <title>Executing a Task Against a Single Recipe</title> | ||
562 | |||
563 | <para> | ||
564 | Executing tasks for a single recipe file is relatively simple. | ||
565 | You specify the file in question, and BitBake parses | ||
566 | it and executes the specified task. | ||
567 | If you do not specify a task, BitBake executes the default | ||
568 | task, which is "build”. | ||
569 | BitBake obeys inter-task dependencies when doing | ||
570 | so. | ||
571 | </para> | ||
572 | |||
573 | <para> | ||
574 | The following command runs the build task, which is | ||
575 | the default task, on the <filename>foo_1.0.bb</filename> | ||
576 | recipe file: | ||
577 | <literallayout class='monospaced'> | ||
578 | $ bitbake -b foo_1.0.bb | ||
579 | </literallayout> | ||
580 | The following command runs the clean task on the | ||
581 | <filename>foo.bb</filename> recipe file: | ||
582 | <literallayout class='monospaced'> | ||
583 | $ bitbake -b foo.bb -c clean | ||
584 | </literallayout> | ||
585 | <note> | ||
586 | The "-b" option explicitly does not handle recipe | ||
587 | dependencies. | ||
588 | Other than for debugging purposes, it is instead | ||
589 | recommended that you use the syntax presented in the | ||
590 | next section. | ||
591 | </note> | ||
592 | </para> | ||
593 | </section> | ||
594 | |||
595 | <section id='executing-tasks-against-a-set-of-recipe-files'> | ||
596 | <title>Executing Tasks Against a Set of Recipe Files</title> | ||
597 | |||
598 | <para> | ||
599 | There are a number of additional complexities introduced | ||
600 | when one wants to manage multiple <filename>.bb</filename> | ||
601 | files. | ||
602 | Clearly there needs to be a way to tell BitBake what | ||
603 | files are available and, of those, which you | ||
604 | want to execute. | ||
605 | There also needs to be a way for each recipe | ||
606 | to express its dependencies, both for build-time and | ||
607 | runtime. | ||
608 | There must be a way for you to express recipe preferences | ||
609 | when multiple recipes provide the same functionality, or when | ||
610 | there are multiple versions of a recipe. | ||
611 | </para> | ||
612 | |||
613 | <para> | ||
614 | The <filename>bitbake</filename> command, when not using | ||
615 | "--buildfile" or "-b" only accepts a "PROVIDES". | ||
616 | You cannot provide anything else. | ||
617 | By default, a recipe file generally "PROVIDES" its | ||
618 | "packagename" as shown in the following example: | ||
619 | <literallayout class='monospaced'> | ||
620 | $ bitbake foo | ||
621 | </literallayout> | ||
622 | This next example "PROVIDES" the package name and also uses | ||
623 | the "-c" option to tell BitBake to just execute the | ||
624 | <filename>do_clean</filename> task: | ||
625 | <literallayout class='monospaced'> | ||
626 | $ bitbake -c clean foo | ||
627 | </literallayout> | ||
628 | </para> | ||
629 | </section> | ||
630 | |||
631 | <section id='generating-dependency-graphs'> | ||
632 | <title>Generating Dependency Graphs</title> | ||
633 | |||
634 | <para> | ||
635 | BitBake is able to generate dependency graphs using | ||
636 | the <filename>dot</filename> syntax. | ||
637 | You can convert these graphs into images using the | ||
638 | <filename>dot</filename> tool from | ||
639 | <ulink url='http://www.graphviz.org'>Graphviz</ulink>. | ||
640 | </para> | ||
641 | |||
642 | <para> | ||
643 | When you generate a dependency graph, BitBake writes four files | ||
644 | to the current working directory: | ||
645 | <itemizedlist> | ||
646 | <listitem><para><emphasis><filename>package-depends.dot</filename>:</emphasis> | ||
647 | Shows BitBake's knowledge of dependencies between | ||
648 | runtime targets. | ||
649 | </para></listitem> | ||
650 | <listitem><para><emphasis><filename>pn-depends.dot</filename>:</emphasis> | ||
651 | Shows dependencies between build-time targets | ||
652 | (i.e. recipes). | ||
653 | </para></listitem> | ||
654 | <listitem><para><emphasis><filename>task-depends.dot</filename>:</emphasis> | ||
655 | Shows dependencies between tasks. | ||
656 | </para></listitem> | ||
657 | <listitem><para><emphasis><filename>pn-buildlist</filename>:</emphasis> | ||
658 | Shows a simple list of targets that are to be built. | ||
659 | </para></listitem> | ||
660 | </itemizedlist> | ||
661 | </para> | ||
662 | |||
663 | <para> | ||
664 | To stop depending on common depends, use the "-I" depend | ||
665 | option and BitBake omits them from the graph. | ||
666 | Leaving this information out can produce more readable graphs. | ||
667 | This way, you can remove from the graph | ||
668 | <filename>DEPENDS</filename> from inherited classes | ||
669 | such as <filename>base.bbclass</filename>. | ||
670 | </para> | ||
671 | |||
672 | <para> | ||
673 | Here are two examples that create dependency graphs. | ||
674 | The second example omits depends common in OpenEmbedded from | ||
675 | the graph: | ||
676 | <literallayout class='monospaced'> | ||
677 | $ bitbake -g foo | ||
678 | |||
679 | $ bitbake -g -I virtual/kernel -I eglibc foo | ||
680 | </literallayout> | ||
681 | </para> | ||
682 | </section> | ||
683 | </section> | ||
684 | </section> | ||
685 | </chapter> | ||