summaryrefslogtreecommitdiffstats
path: root/doc/bitbake-user-manual/bitbake-user-manual-intro.xml
blob: 02058a6f627e0b33561525f6a19606d03f6ea460 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
    "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<chapter id="bitbake-user-manual-intro">
    <title>Overview</title>

    <para>
        Welcome to the BitBake User Manual.
        This manual provides information on the BitBake tool.
        The information attempts to be as independent as possible regarding
        systems that use BitBake, such as OpenEmbedded and the
        Yocto Project.
        In some cases, scenarios or examples within the context of
        a build system are used in the manual to help with understanding.
        For these cases, the manual clearly states the context.
    </para>

    <section id="intro">
        <title>Introduction</title>

        <para>
            Fundamentally, BitBake is a generic task execution
            engine that allows shell and Python tasks to be run
            efficiently and in parallel while working within
            complex inter-task dependency constraints.
            One of BitBake's main users, OpenEmbedded, takes this core
            and builds embedded Linux software stacks using
            a task-oriented approach.
        </para>

        <para>
            Conceptually, BitBake is similar to GNU Make in
            some regards but has significant differences:
            <itemizedlist>
                <listitem><para>
                    BitBake executes tasks according to provided
                    metadata that builds up the tasks.
                    Metadata is stored in recipe (<filename>.bb</filename>)
                    and related recipe "append" (<filename>.bbappend</filename>)
                    files, configuration (<filename>.conf</filename>) and
                    underlying include (<filename>.inc</filename>) files, and
                    in class (<filename>.bbclass</filename>) files.
                    The metadata provides
                    BitBake with instructions on what tasks to run and
                    the dependencies between those tasks.
                    </para></listitem>
                <listitem><para>
                    BitBake includes a fetcher library for obtaining source
                    code from various places such as local files, source control
                    systems, or websites.
                    </para></listitem>
                <listitem><para>
                    The instructions for each unit to be built (e.g. a piece
                    of software) are known as "recipe" files and
                    contain all the information about the unit
                    (dependencies, source file locations, checksums, description
                    and so on).
                    </para></listitem>
                <listitem><para>
                    BitBake includes a client/server abstraction and can
                    be used from a command line or used as a service over
                    XML-RPC and has several different user interfaces.
                    </para></listitem>
            </itemizedlist>
        </para>
    </section>

    <section id="history-and-goals">
        <title>History and Goals</title>

        <para>
            BitBake was originally a part of the OpenEmbedded project.
            It was inspired by the Portage package management system
            used by the Gentoo Linux distribution.
            On December 7, 2004, OpenEmbedded project team member
            Chris Larson split the project into two distinct pieces:
            <itemizedlist>
                <listitem><para>BitBake, a generic task executor</para></listitem>
                <listitem><para>OpenEmbedded, a metadata set utilized by
                    BitBake</para></listitem>
            </itemizedlist>
            Today, BitBake is the primary basis of the
            <ulink url="http://www.openembedded.org/">OpenEmbedded</ulink>
            project, which is being used to build and maintain Linux
            distributions such as the
            <ulink url='http://www.angstrom-distribution.org/'>Angstrom Distribution</ulink>,
            and which is also being used as the build tool for Linux projects
            such as the
            <ulink url='http://www.yoctoproject.org'>Yocto Project</ulink>.
        </para>

        <para>
            Prior to BitBake, no other build tool adequately met the needs of
            an aspiring embedded Linux distribution.
            All of the build systems used by traditional desktop Linux
            distributions lacked important functionality, and none of the
            ad hoc Buildroot-based systems, prevalent in the
            embedded space, were scalable or maintainable.
        </para>

        <para>
            Some important original goals for BitBake were:
            <itemizedlist>
                <listitem><para>
                    Handle cross-compilation.
                    </para></listitem>
                <listitem><para>
                    Handle inter-package dependencies (build time on
                    target architecture, build time on native
                    architecture, and runtime).
                    </para></listitem>
                <listitem><para>
                    Support running any number of tasks within a given
                    package, including, but not limited to, fetching
                    upstream sources, unpacking them, patching them,
                    configuring them, and so forth.
                    </para></listitem>
                <listitem><para>
                    Be Linux distribution agnostic for both build and
                    target systems.
                    </para></listitem>
                <listitem><para>
                    Be architecture agnostic.
                    </para></listitem>
                <listitem><para>
                    Support multiple build and target operating systems
                    (e.g. Cygwin, the BSDs, and so forth).
                    </para></listitem>
                <listitem><para>
                    Be self contained, rather than tightly
                    integrated into the build machine's root
                    filesystem.
                    </para></listitem>
                <listitem><para>
                    Handle conditional metadata on the target architecture,
                    operating system, distribution, and machine.
                    </para></listitem>
                <listitem><para>
                    Be easy to use the tools to supply local metadata and packages
                    against which to operate.
                    </para></listitem>
                <listitem><para>
                    Be easy to use BitBake to collaborate between multiple
                    projects for their builds.
                    </para></listitem>
                <listitem><para>
                    Provide an inheritance mechanism to share
                    common metadata between many packages.
                    </para></listitem>
            </itemizedlist>
            Over time it became apparent that some further requirements
            were necessary:
            <itemizedlist>
                <listitem><para>
                    Handle variants of a base recipe (e.g. native, sdk,
                    and multilib).
                    </para></listitem>
                <listitem><para>
                    Split metadata into layers and allow layers
                    to enhance or override other layers.
                    </para></listitem>
                <listitem><para>
                    Allow representation of a given set of input variables
                    to a task as a checksum.
                    Based on that checksum, allow acceleration of builds
                    with prebuilt components.
                    </para></listitem>
            </itemizedlist>
            BitBake satisfies all the original requirements and many more
            with extensions being made to the basic functionality to
            reflect the additional requirements.
            Flexibility and power have always been the priorities.
            BitBake is highly extensible and supports embedded Python code and
            execution of any arbitrary tasks.
        </para>
    </section>

    <section id="Concepts">
        <title>Concepts</title>

        <para>
            BitBake is a program written in the Python language.
            At the highest level, BitBake interprets metadata, decides
            what tasks are required to run, and executes those tasks.
            Similar to GNU Make, BitBake controls how software is
            built.
            GNU Make achieves its control through "makefiles", while
            BitBake uses "recipes".
        </para>

        <para>
            BitBake extends the capabilities of a simple
            tool like GNU Make by allowing for the definition of much more
            complex tasks, such as assembling entire embedded Linux
            distributions.
        </para>

        <para>
            The remainder of this section introduces several concepts
            that should be understood in order to better leverage
            the power of BitBake.
        </para>

        <section id='recipes'>
            <title>Recipes</title>

            <para>
                BitBake Recipes, which are denoted by the file extension
                <filename>.bb</filename>, are the most basic metadata files.
                These recipe files provide BitBake with the following:
                <itemizedlist>
                    <listitem><para>Descriptive information about the
                        package (author, homepage, license, and so on)</para></listitem>
                    <listitem><para>The version of the recipe</para></listitem>
                    <listitem><para>Existing dependencies (both build
                        and runtime dependencies)</para></listitem>
                    <listitem><para>Where the source code resides and
                        how to fetch it</para></listitem>
                    <listitem><para>Whether the source code requires
                        any patches, where to find them, and how to apply
                        them</para></listitem>
                    <listitem><para>How to configure and compile the
                        source code</para></listitem>
                    <listitem><para>Where on the target machine to install the
                        package or packages created</para></listitem>
                </itemizedlist>
            </para>

            <para>
                Within the context of BitBake, or any project utilizing BitBake
                as its build system, files with the <filename>.bb</filename>
                extension are referred to as recipes.
                <note>
                    The term "package" is also commonly used to describe recipes.
                    However, since the same word is used to describe packaged
                    output from a project, it is best to maintain a single
                    descriptive term - "recipes".
                    Put another way, a single "recipe" file is quite capable
                    of generating a number of related but separately installable
                    "packages".
                    In fact, that ability is fairly common.
                </note>
            </para>
        </section>

        <section id='configuration-files'>
            <title>Configuration Files</title>

            <para>
                Configuration files, which are denoted by the
                <filename>.conf</filename> extension, define
                various configuration variables that govern the project's build
                process.
                These files fall into several areas that define
                machine configuration options, distribution configuration
                options, compiler tuning options, general common
                configuration options, and user configuration options.
                The main configuration file is the sample
                <filename>bitbake.conf</filename> file, which is
                located within the BitBake source tree
                <filename>conf</filename> directory.
            </para>
        </section>

        <section id='classes'>
            <title>Classes</title>

            <para>
                Class files, which are denoted by the
                <filename>.bbclass</filename> extension, contain
                information that is useful to share between metadata files.
                The BitBake source tree currently comes with one class metadata file
                called <filename>base.bbclass</filename>.
                You can find this file in the
                <filename>classes</filename> directory.
                The <filename>base.bbclass</filename> class files is special since it
                is always included automatically for all recipes
                and classes.
                This class contains definitions for standard basic tasks such
                as fetching, unpacking, configuring (empty by default),
                compiling (runs any Makefile present), installing (empty by
                default) and packaging (empty by default).
                These tasks are often overridden or extended by other classes
                added during the project development process.
            </para>
        </section>

        <section id='layers'>
            <title>Layers</title>

            <para>
                Layers allow you to isolate different types of
                customizations from each other.
                While you might find it tempting to keep everything in one layer
                when working on a single project, the more modular you organize
                your metadata, the easier it is to cope with future changes.
            </para>

            <para>
                To illustrate how you can use layers to keep things modular,
                consider customizations you might make to support a specific target machine.
                These types of customizations typically reside in a special layer,
                rather than a general layer, called a Board Support Package (BSP)
                Layer.
                Furthermore, the machine customizations should be isolated from
                recipes and metadata that support a new GUI environment, for
                example.
                This situation gives you a couple of layers: one for the machine
                configurations and one for the GUI environment.
                It is important to understand, however, that the BSP layer can still
                make machine-specific additions to recipes within
                the GUI environment layer without polluting the GUI layer itself
                with those machine-specific changes.
                You can accomplish this through a recipe that is a BitBake append
                (<filename>.bbappend</filename>) file.
            </para>
        </section>

        <section id='append-bbappend-files'>
            <title>Append Files</title>

            <para>
                Append files, which are files that have the
                <filename>.bbappend</filename> file extension, extend or
                override information in an existing recipe file.
            </para>

            <para>
                BitBake expects every append file to have a corresponding recipe file.
                Furthermore, the append file and corresponding recipe file
                must use the same root filename.
                The filenames can differ only in the file type suffix used
                (e.g. <filename>formfactor_0.0.bb</filename> and
                <filename>formfactor_0.0.bbappend</filename>).
            </para>

            <para>
                Information in append files extends or
                overrides the information in the underlying,
                similarly-named recipe files.
            </para>

            <para>
                When you name an append file, you can use the
                "<filename>%</filename>" wildcard character to allow for matching
                recipe names.
                For example, suppose you have an append file named
                as follows:
                <literallayout class='monospaced'>
     busybox_1.21.%.bbappend
                </literallayout>
                That append file would match any <filename>busybox_1.21.</filename><replaceable>x</replaceable><filename>.bb</filename>
                version of the recipe.
                So, the append file would match the following recipe names:
                <literallayout class='monospaced'>
     busybox_1.21.1.bb
     busybox_1.21.2.bb
     busybox_1.21.3.bb
                </literallayout>
                <note><title>Important</title>
                    The use of the "<filename>%</filename>" character
                    is limited in that it only works directly in front of the
                    <filename>.bbappend</filename> portion of the append file's
                    name.
                    You cannot use the wildcard character in any other
                    location of the name.
                </note>
                If the <filename>busybox</filename> recipe was updated to
                <filename>busybox_1.3.0.bb</filename>, the append name would not
                match.
                However, if you named the append file
                <filename>busybox_1.%.bbappend</filename>, then you would have a match.
            </para>

            <para>
                In the most general case, you could name the append file something as
                simple as <filename>busybox_%.bbappend</filename> to be entirely
                version independent.
            </para>
        </section>
    </section>

    <section id='obtaining-bitbake'>
        <title>Obtaining BitBake</title>

        <para>
            You can obtain BitBake several different ways:
            <itemizedlist>
                <listitem><para><emphasis>Cloning BitBake:</emphasis>
                    Using Git to clone the BitBake source code repository
                    is the recommended method for obtaining BitBake.
                    Cloning the repository makes it easy to get bug fixes
                    and have access to stable branches and the master
                    branch.
                    Once you have cloned BitBake, you should use
                    the latest stable
                    branch for development since the master branch is for
                    BitBake development and might contain less stable changes.
                    </para>
                    <para>You usually need a version of BitBake
                    that matches the metadata you are using.
                    The metadata is generally backwards compatible but
                    not forward compatible.</para>
                    <para>Here is an example that clones the BitBake repository:
                    <literallayout class='monospaced'>
     $ git clone git://git.openembedded.org/bitbake
                    </literallayout>
                    This command clones the BitBake Git repository into a
                    directory called <filename>bitbake</filename>.
                    Alternatively, you can
                    designate a directory after the
                    <filename>git clone</filename> command
                    if you want to call the new directory something
                    other than <filename>bitbake</filename>.
                    Here is an example that names the directory
                    <filename>bbdev</filename>:
                    <literallayout class='monospaced'>
     $ git clone git://git.openembedded.org/bitbake bbdev
                    </literallayout></para></listitem>
                <listitem><para><emphasis>Installation using your Distribution
                    Package Management System:</emphasis>
                    This method is not
                    recommended because the BitBake version that is
                    provided by your distribution, in most cases,
                    is several
                    releases behind a snapshot of the BitBake repository.
                    </para></listitem>
                <listitem><para><emphasis>Taking a snapshot of BitBake:</emphasis>
                    Downloading a snapshot of BitBake from the
                    source code repository gives you access to a known
                    branch or release of BitBake.
                    <note>
                         Cloning the Git repository, as described earlier,
                         is the preferred method for getting BitBake.
                         Cloning the repository makes it easier to update as
                         patches are added to the stable branches.
                    </note></para>
                    <para>The following example downloads a snapshot of
                    BitBake version 1.17.0:
                    <literallayout class='monospaced'>
     $ wget http://git.openembedded.org/bitbake/snapshot/bitbake-1.17.0.tar.gz
     $ tar zxpvf bitbake-1.17.0.tar.gz
                    </literallayout>
                    After extraction of the tarball using the tar utility,
                    you have a directory entitled
                    <filename>bitbake-1.17.0</filename>.
                    </para></listitem>
                <listitem><para><emphasis>Using the BitBake that Comes With Your
                    Build Checkout:</emphasis>
                    A final possibility for getting a copy of BitBake is that it
                    already comes with your checkout of a larger Bitbake-based build
                    system, such as Poky.
                    Rather than manually checking out individual layers and
                    gluing them together yourself, you can check
                    out an entire build system.
                    The checkout will already include a version of BitBake that
                    has been thoroughly tested for compatibility with the other
                    components.
                    For information on how to check out a particular BitBake-based
                    build system, consult that build system's supporting documentation.
                    </para></listitem>
            </itemizedlist>
        </para>
    </section>

    <section id="bitbake-user-manual-command">
        <title>The BitBake Command</title>

        <para>
            The <filename>bitbake</filename> command is the primary interface
            to the BitBake tool.
            This section presents the BitBake command syntax and provides
            several execution examples.
        </para>

        <section id='usage-and-syntax'>
            <title>Usage and syntax</title>

            <para>
                Following is the usage and syntax for BitBake:
                <literallayout class='monospaced'>
     $ bitbake -h
     Usage: bitbake [options] [recipename/target recipe:do_task ...]

         Executes the specified task (default is 'build') for a given set of target recipes (.bb files).
         It is assumed there is a conf/bblayers.conf available in cwd or in BBPATH which
         will provide the layer, BBFILES and other configuration information.

     Options:
       --version             show program's version number and exit
       -h, --help            show this help message and exit
       -b BUILDFILE, --buildfile=BUILDFILE
                             Execute tasks from a specific .bb recipe directly.
                             WARNING: Does not handle any dependencies from other
                             recipes.
       -k, --continue        Continue as much as possible after an error. While the
                             target that failed and anything depending on it cannot
                             be built, as much as possible will be built before
                             stopping.
       -f, --force           Force the specified targets/task to run (invalidating
                             any existing stamp file).
       -c CMD, --cmd=CMD     Specify the task to execute. The exact options
                             available depend on the metadata. Some examples might
                             be 'compile' or 'populate_sysroot' or 'listtasks' may
                             give a list of the tasks available.
       -C INVALIDATE_STAMP, --clear-stamp=INVALIDATE_STAMP
                             Invalidate the stamp for the specified task such as
                             'compile' and then run the default task for the
                             specified target(s).
       -r PREFILE, --read=PREFILE
                             Read the specified file before bitbake.conf.
       -R POSTFILE, --postread=POSTFILE
                             Read the specified file after bitbake.conf.
       -v, --verbose         Enable tracing of shell tasks (with 'set -x'). Also
                             print bb.note(...) messages to stdout (in addition to
                             writing them to ${T}/log.do_&lt;task&gt;).
       -D, --debug           Increase the debug level. You can specify this more
                             than once. -D sets the debug level to 1, where only
                             bb.debug(1, ...) messages are printed to stdout; -DD
                             sets the debug level to 2, where both bb.debug(1, ...)
                             and bb.debug(2, ...) messages are printed; etc.
                             Without -D, no debug messages are printed. Note that
                             -D only affects output to stdout. All debug messages
                             are written to ${T}/log.do_taskname, regardless of the
                             debug level.
       -q, --quiet           Output less log message data to the terminal. You can
                             specify this more than once.
       -n, --dry-run         Don't execute, just go through the motions.
       -S SIGNATURE_HANDLER, --dump-signatures=SIGNATURE_HANDLER
                             Dump out the signature construction information, with
                             no task execution. The SIGNATURE_HANDLER parameter is
                             passed to the handler. Two common values are none and
                             printdiff but the handler may define more/less. none
                             means only dump the signature, printdiff means compare
                             the dumped signature with the cached one.
       -p, --parse-only      Quit after parsing the BB recipes.
       -s, --show-versions   Show current and preferred versions of all recipes.
       -e, --environment     Show the global or per-recipe environment complete
                             with information about where variables were
                             set/changed.
       -g, --graphviz        Save dependency tree information for the specified
                             targets in the dot syntax.
       -I EXTRA_ASSUME_PROVIDED, --ignore-deps=EXTRA_ASSUME_PROVIDED
                             Assume these dependencies don't exist and are already
                             provided (equivalent to ASSUME_PROVIDED). Useful to
                             make dependency graphs more appealing
       -l DEBUG_DOMAINS, --log-domains=DEBUG_DOMAINS
                             Show debug logging for the specified logging domains
       -P, --profile         Profile the command and save reports.
       -u UI, --ui=UI        The user interface to use (knotty, ncurses or taskexp
                             - default knotty).
       --token=XMLRPCTOKEN   Specify the connection token to be used when
                             connecting to a remote server.
       --revisions-changed   Set the exit code depending on whether upstream
                             floating revisions have changed or not.
       --server-only         Run bitbake without a UI, only starting a server
                             (cooker) process.
       -B BIND, --bind=BIND  The name/address for the bitbake xmlrpc server to bind
                             to.
       -T SERVER_TIMEOUT, --idle-timeout=SERVER_TIMEOUT
                             Set timeout to unload bitbake server due to
                             inactivity, set to -1 means no unload, default:
                             Environment variable BB_SERVER_TIMEOUT.
       --no-setscene         Do not run any setscene tasks. sstate will be ignored
                             and everything needed, built.
       --setscene-only       Only run setscene tasks, don't run any real tasks.
       --remote-server=REMOTE_SERVER
                             Connect to the specified server.
       -m, --kill-server     Terminate any running bitbake server.
       --observe-only        Connect to a server as an observing-only client.
       --status-only         Check the status of the remote bitbake server.
       -w WRITEEVENTLOG, --write-log=WRITEEVENTLOG
                             Writes the event log of the build to a bitbake event
                             json file. Use '' (empty string) to assign the name
                             automatically.
       --runall=RUNALL       Run the specified task for any recipe in the taskgraph
                             of the specified target (even if it wouldn't otherwise
                             have run).
       --runonly=RUNONLY     Run only the specified task within the taskgraph of
                             the specified targets (and any task dependencies those
                             tasks may have).
                </literallayout>
            </para>
        </section>

        <section id='bitbake-examples'>
            <title>Examples</title>

            <para>
                This section presents some examples showing how to use BitBake.
            </para>

            <section id='example-executing-a-task-against-a-single-recipe'>
                <title>Executing a Task Against a Single Recipe</title>

                <para>
                    Executing tasks for a single recipe file is relatively simple.
                    You specify the file in question, and BitBake parses
                    it and executes the specified task.
                    If you do not specify a task, BitBake executes the default
                    task, which is "build”.
                    BitBake obeys inter-task dependencies when doing
                    so.
                </para>

                <para>
                    The following command runs the build task, which is
                    the default task, on the <filename>foo_1.0.bb</filename>
                    recipe file:
                    <literallayout class='monospaced'>
     $ bitbake -b foo_1.0.bb
                    </literallayout>
                    The following command runs the clean task on the
                    <filename>foo.bb</filename> recipe file:
                    <literallayout class='monospaced'>
     $ bitbake -b foo.bb -c clean
                    </literallayout>
                    <note>
                        The "-b" option explicitly does not handle recipe
                        dependencies.
                        Other than for debugging purposes, it is instead
                        recommended that you use the syntax presented in the
                        next section.
                    </note>
                </para>
            </section>

            <section id='executing-tasks-against-a-set-of-recipe-files'>
                <title>Executing Tasks Against a Set of Recipe Files</title>

                <para>
                    There are a number of additional complexities introduced
                    when one wants to manage multiple <filename>.bb</filename>
                    files.
                    Clearly there needs to be a way to tell BitBake what
                    files are available and, of those, which you
                    want to execute.
                    There also needs to be a way for each recipe
                    to express its dependencies, both for build-time and
                    runtime.
                    There must be a way for you to express recipe preferences
                    when multiple recipes provide the same functionality, or when
                    there are multiple versions of a recipe.
                </para>

                <para>
                    The <filename>bitbake</filename> command, when not using
                    "--buildfile" or "-b" only accepts a "PROVIDES".
                    You cannot provide anything else.
                    By default, a recipe file generally "PROVIDES" its
                    "packagename" as shown in the following example:
                    <literallayout class='monospaced'>
     $ bitbake foo
                    </literallayout>
                    This next example "PROVIDES" the package name and also uses
                    the "-c" option to tell BitBake to just execute the
                    <filename>do_clean</filename> task:
                    <literallayout class='monospaced'>
     $ bitbake -c clean foo
                    </literallayout>
                </para>
            </section>

            <section id='executing-a-list-of-task-and-recipe-combinations'>
                <title>Executing a List of Task and Recipe Combinations</title>

                <para>
                    The BitBake command line supports specifying different
                    tasks for individual targets when you specify multiple
                    targets.
                    For example, suppose you had two targets (or recipes)
                    <filename>myfirstrecipe</filename> and
                    <filename>mysecondrecipe</filename> and you needed
                    BitBake to run <filename>taskA</filename> for the first
                    recipe and <filename>taskB</filename> for the second
                    recipe:
                    <literallayout class='monospaced'>
     $ bitbake myfirstrecipe:do_taskA mysecondrecipe:do_taskB
                    </literallayout>
                </para>
            </section>

            <section id='generating-dependency-graphs'>
                <title>Generating Dependency Graphs</title>

                <para>
                    BitBake is able to generate dependency graphs using
                    the <filename>dot</filename> syntax.
                    You can convert these graphs into images using the
                    <filename>dot</filename> tool from
                    <ulink url='http://www.graphviz.org'>Graphviz</ulink>.
                </para>

                <para>
                    When you generate a dependency graph, BitBake writes three files
                    to the current working directory:
                    <itemizedlist>
                        <listitem><para>
                            <emphasis><filename>recipe-depends.dot</filename>:</emphasis>
                            Shows dependencies between recipes (i.e. a collapsed version of
                            <filename>task-depends.dot</filename>).
                            </para></listitem>
                        <listitem><para>
                            <emphasis><filename>task-depends.dot</filename>:</emphasis>
                            Shows dependencies between tasks.
                            These dependencies match BitBake's internal task execution list.
                            </para></listitem>
                        <listitem><para>
                            <emphasis><filename>pn-buildlist</filename>:</emphasis>
                            Shows a simple list of targets that are to be built.
                            </para></listitem>
                    </itemizedlist>
                </para>

                <para>
                    To stop depending on common depends, use the "-I" depend
                    option and BitBake omits them from the graph.
                    Leaving this information out can produce more readable graphs.
                    This way, you can remove from the graph
                    <filename>DEPENDS</filename> from inherited classes
                    such as <filename>base.bbclass</filename>.
                </para>

                <para>
                    Here are two examples that create dependency graphs.
                    The second example omits depends common in OpenEmbedded from
                    the graph:
                    <literallayout class='monospaced'>
     $ bitbake -g foo

     $ bitbake -g -I virtual/kernel -I eglibc foo
                    </literallayout>
                </para>
            </section>

            <section id='executing-a-multiple-configuration-build'>
                <title>Executing a Multiple Configuration Build</title>

                <para>
                    BitBake is able to build multiple images or packages
                    using a single command where the different targets
                    require different configurations (multiple configuration
                    builds).
                    Each target, in this scenario, is referred to as a
                    "multiconfig".
                </para>

                <para>
                    To accomplish a multiple configuration build, you must
                    define each target's configuration separately using
                    a parallel configuration file in the build directory.
                    The location for these multiconfig configuration files
                    is specific.
                    They must reside in the current build directory in
                    a sub-directory of <filename>conf</filename> named
                    <filename>multiconfig</filename>.
                    Following is an example for two separate targets:
                    <imagedata fileref="figures/bb_multiconfig_files.png" align="center" width="4in" depth="3in" />
                </para>

                <para>
                    The reason for this required file hierarchy
                    is because the <filename>BBPATH</filename> variable
                    is not constructed until the layers are parsed.
                    Consequently, using the configuration file as a
                    pre-configuration file is not possible unless it is
                    located in the current working directory.
                </para>

                <para>
                    Minimally, each configuration file must define the
                    machine and the temporary directory BitBake uses
                    for the build.
                    Suggested practice dictates that you do not
                    overlap the temporary directories used during the
                    builds.
                </para>

                <para>
                    Aside from separate configuration files for each
                    target, you must also enable BitBake to perform multiple
                    configuration builds.
                    Enabling is accomplished by setting the
                    <link linkend='var-bb-BBMULTICONFIG'><filename>BBMULTICONFIG</filename></link>
                    variable in the <filename>local.conf</filename>
                    configuration file.
                    As an example, suppose you had configuration files
                    for <filename>target1</filename> and
                    <filename>target2</filename> defined in the build
                    directory.
                    The following statement in the
                    <filename>local.conf</filename> file both enables
                    BitBake to perform multiple configuration builds and
                    specifies the two multiconfigs:
                    <literallayout class='monospaced'>
     BBMULTICONFIG = "target1 target2"
                    </literallayout>
                </para>

                <para>
                    Once the target configuration files are in place and
                    BitBake has been enabled to perform multiple configuration
                    builds, use the following command form to start the
                    builds:
                    <literallayout class='monospaced'>
     $ bitbake [multiconfig:<replaceable>multiconfigname</replaceable>:]<replaceable>target</replaceable> [[[multiconfig:<replaceable>multiconfigname</replaceable>:]<replaceable>target</replaceable>] ... ]
                    </literallayout>
                    Here is an example for two multiconfigs:
                    <filename>target1</filename> and
                    <filename>target2</filename>:
                    <literallayout class='monospaced'>
     $ bitbake multiconfig:target1:<replaceable>target</replaceable> multiconfig:target2:<replaceable>target</replaceable>
                    </literallayout>
                </para>
            </section>

            <section id='bb-enabling-multiple-configuration-build-dependencies'>
                <title>Enabling Multiple Configuration Build Dependencies</title>

                <para>
                    Sometimes dependencies can exist between targets
                    (multiconfigs) in a multiple configuration build.
                    For example, suppose that in order to build an image
                    for a particular architecture, the root filesystem of
                    another build for a different architecture needs to
                    exist.
                    In other words, the image for the first multiconfig depends
                    on the root filesystem of the second multiconfig.
                    This dependency is essentially that the task in the recipe
                    that builds one multiconfig is dependent on the
                    completion of the task in the recipe that builds
                    another multiconfig.
                </para>

                <para>
                    To enable dependencies in a multiple configuration
                    build, you must declare the dependencies in the recipe
                    using the following statement form:
                    <literallayout class='monospaced'>
     <replaceable>task_or_package</replaceable>[mcdepends] = "multiconfig:<replaceable>from_multiconfig</replaceable>:<replaceable>to_multiconfig</replaceable>:<replaceable>recipe_name</replaceable>:<replaceable>task_on_which_to_depend</replaceable>"
                    </literallayout>
                    To better show how to use this statement, consider an
                    example with two multiconfigs: <filename>target1</filename>
                    and <filename>target2</filename>:
                    <literallayout class='monospaced'>
     <replaceable>image_task</replaceable>[mcdepends] = "multiconfig:target1:target2:<replaceable>image2</replaceable>:<replaceable>rootfs_task</replaceable>"
                    </literallayout>
                    In this example, the
                    <replaceable>from_multiconfig</replaceable> is "target1" and
                    the <replaceable>to_multiconfig</replaceable> is "target2".
                    The task on which the image whose recipe contains
                    <replaceable>image_task</replaceable> depends on the
                    completion of the <replaceable>rootfs_task</replaceable>
                    used to build out <replaceable>image2</replaceable>, which
                    is associated with the "target2" multiconfig.
               </para>

               <para>
                   Once you set up this dependency, you can build the
                   "target1" multiconfig using a BitBake command as follows:
                   <literallayout class='monospaced'>
     $ bitbake multiconfig:target1:<replaceable>image1</replaceable>
                   </literallayout>
                   This command executes all the tasks needed to create
                   <replaceable>image1</replaceable> for the "target1"
                   multiconfig.
                   Because of the dependency, BitBake also executes through
                   the <replaceable>rootfs_task</replaceable> for the "target2"
                   multiconfig build.
               </para>

               <para>
                   Having a recipe depend on the root filesystem of another
                   build might not seem that useful.
                   Consider this change to the statement in the
                   <replaceable>image1</replaceable> recipe:
                   <literallayout class='monospaced'>
     <replaceable>image_task</replaceable>[mcdepends] = "multiconfig:target1:target2:<replaceable>image2</replaceable>:<replaceable>image_task</replaceable>"
                   </literallayout>
                   In this case, BitBake must create
                   <replaceable>image2</replaceable> for the "target2"
                   build since the "target1" build depends on it.
               </para>

               <para>
                   Because "target1" and "target2" are enabled for multiple
                   configuration builds and have separate configuration
                   files, BitBake places the artifacts for each build in the
                   respective temporary build directories.
               </para>
            </section>
        </section>
    </section>
</chapter>