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
|
<?xml version="1.0" encoding="UTF-8"?>
<chapter id="chapter_using_bitbake_and_oe">
<title>Using bitbake and OE</title>
<section id="usage_introduction" xreflabel="introduction">
<title>Introduction</title>
<para>If your reading this manual you probably already have some idea of
what OpenEmbedded is all about, which is taking a lot of software and
creating something that you can run on another device. Its all about
downloading some source code, compiling it, creating packages (like .deb
or .rpm) and/or creating boot images that can written to flash on the
device. The complexities of cross-compiling and the variety of devices to
be supported lead to a lot more complexity in on OpenEmbedded based
distribution than you'd find in a typical desktop distribution (which
doesn't get cross-compiled).</para>
<para>A major part of OpenEmbedded deals with compiling source code for
various projects. For each project OpenEmbedded has to:</para>
<orderedlist>
<listitem>
<para>Download the source code, and any supporting files (such as
initscripts);</para>
</listitem>
<listitem>
<para>Extract the source code and apply any patches that might be
wanted;</para>
</listitem>
<listitem>
<para>Configure the software if needed (such as is done by running the
configure script);</para>
</listitem>
<listitem>
<para>Compile everything;</para>
</listitem>
<listitem>
<para>Package up all the files into some package format, like .deb or
.rpm or .ipk, ready for installation.</para>
</listitem>
</orderedlist>
<para>As mentioned this is made for more complex than normal due
to:</para>
<orderedlist>
<listitem>
<para>Cross-compiling: cross-compiling is difficult, and lots of
software has no support for cross-compiling. All packages included in
OE are cross-compiled;</para>
</listitem>
<listitem>
<para>Due to cross-compiling the executable's that are created cannot
normally be run, so any software that tries to run things as part of
it's build process need to have changes made to handle this some other
way</para>
</listitem>
</orderedlist>
<para>Of course there's a lot more to OE then just compiling packages
though. Just some of the things that OE can handle:</para>
<itemizedlist>
<listitem>
<para>Support for glibc and uclibc;</para>
</listitem>
<listitem>
<para>Support for building for multiple targets;</para>
</listitem>
<listitem>
<para>Dependencies - automatically building anything that is required
for the package your really want;</para>
</listitem>
<listitem>
<para>Creation of flash and disk images for booting directly on the
target device;</para>
</listitem>
<listitem>
<para>Support for various packaging formats;</para>
</listitem>
<listitem>
<para>Automatically creating all of the cross-compiling tools you'll
need;</para>
</listitem>
<listitem>
<para>Support for "native" packages that are built for the host
computer and not for the target;</para>
</listitem>
</itemizedlist>
<para>This chapter assumes you have master the Getting Start guides to
OpenEmbedded (see the OpenEmbedded web site for details), and therefore
have an appropriately configured setup and have managed to build the
cross-compilers for your target. This section talks you through some of
the background on what is happening with the aim of helping you understand
how to debug and develop within OpenEmbedded.</para>
</section>
<section id="usage_workspace" xreflabel="workspace">
<title>Work space</title>
<para>Let's start out by taking a look at a typically working area OE.
Note that this isn't exactly what you'll see - there are a lot of options that
can effect exactly how things are done, but it gives us a pretty good idea
of whats going on. What we are looking at here is the tmp directory (as
specified by TMPDIR in your local.conf):<screen>%> find tmp -maxdepth 2 -type d
tmp
tmp/stamps
tmp/cross
tmp/cross/bin
tmp/cross/libexec
tmp/cross/lib
tmp/cross/share
tmp/cross/sh4-linux
tmp/cache
tmp/cache/titan
tmp/work
tmp/work/busybox-1.2.1-r13
tmp/work/libice-1_1.0.3-r0
tmp/work/arpwatch-2.1a15-r2
...
tmp/rootfs
tmp/rootfs/bin
tmp/rootfs/usr
tmp/rootfs/media
tmp/rootfs/dev
tmp/rootfs/var
tmp/rootfs/lib
tmp/rootfs/sbin
tmp/rootfs/mnt
tmp/rootfs/boot
tmp/rootfs/sys
tmp/rootfs/proc
tmp/rootfs/etc
tmp/rootfs/home
tmp/rootfs/tmp
tmp/staging
tmp/staging/man
tmp/staging/x86_64-linux
tmp/staging/pkgdata
tmp/staging/pkgmaps
tmp/staging/var
tmp/staging/sh4-linux
tmp/staging/local
tmp/staging/etc
tmp/deploy
tmp/deploy/addons
tmp/deploy/ipk
tmp/deploy/sources
tmp/deploy/images</screen></para>
<para>The various top level directories under tmp include:</para>
<variablelist>
<varlistentry>
<term>stamps</term>
<listitem>
<para>Nothing of interest to users in here. These time stamps are
used by bitbake to keep track of what tasks it has completed and
what tasks it still has outstanding. This is how it knows that
certain actions have been completed and it doesn't need to do them
again.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>cross</term>
<listitem>
<para>Contains the cross-compiler toolchain. That is the gcc and
binutils that run on the host system but produce output for the
target system.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>cache</term>
<listitem>
<para>Nothing of interest to users in here. This contains the
bitbake parse cache and is used to avoid the need to parse all of
the recipes each time bitbake is run. This makes bitbake a lot
faster on the 2nd and subsequent runs.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>work</term>
<listitem>
<para>The work directory. This is the directory in which all
packages are built - this is where the source code is extract,
patches applied, software configure, compiled, installed and
package. This is where you'll spend most of you time looking when
working in OE.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>rootfs</term>
<listitem>
<para>The generated root filesystem image for your target device.
This is the contents of the root filesystem (NOTE: fakeroot means it
doesn't have the correct device special nodes and permissions to use
directly).</para>
</listitem>
</varlistentry>
<varlistentry>
<term>staging</term>
<listitem>
<para>Contains the staging area, which is used to stored natively
compiled tools and and libraries and headers for the target that are
required for building other software.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>deploy</term>
<listitem>
<para>Contains the final output from OE. This includes the
installation packages (typically .ipkg packages) and flash and/or
disk images. This is where you go to get the final product.</para>
</listitem>
</varlistentry>
</variablelist>
<para></para>
<section id="usage_workdir" xreflabel="work directory">
<title>work directory</title>
<para>The working directory is where all files are extracted and
everything is configured, compiled and packaged. In other words this is
where all the action happens. Each bitbake recipe will produce a
corresponding directory in the working area, with the name containing
the recipe name, version and the release number (as defined by the PR
variable in the recipe).</para>
<para>In the following example we show some of the directories that are
created and in this case they are created directly in the work
directory:<screen>~%> find tmp/work -maxdepth 1 -type d | head -4
tmp/work
tmp/work/busybox-1.2.1-r13
tmp/work/libice-1_1.0.3-r0
tmp/work/arpwatch-2.1a15-r2</screen>Depending on your distribution settings
you may have an additional subdirectory present:<screen>~%> find tmp/work -maxdepth 2 -type d | head -4
tmp/work
tmp/work/sh4-linux
tmp/work/sh4-linux/busybox-1.2.1-r13
tmp/work/sh4-linux/libice-1_1.0.3-r0
tmp/work/sh4-linux/arpwatch-2.1a15-r2</screen></para>
<para>where are additional directory corresponding to the target
architecture and OS has been inserted. This is added by the use of the
<emphasis>multimachine</emphasis> feature which is used to allow builds
for multiple targets within the one work directory (which in turn
enables the sharing of native functionality and a reduction in the time
taken to build for multiple machines). We'll assume multimachine is not
being used for the rest of this chapter, just remember to add the extra
directory if your distribution is using it.</para>
<para>Using lzo 1.08 as an example we'll examine the working directory
and see what it contain for a typical recipe:<screen>%> find tmp/work/lzo-1.08-r14 -maxdepth 1
tmp/work/lzo-1.08-r14
tmp/work/lzo-1.08-r14/temp
tmp/work/lzo-1.08-r14/lzo-1.08
tmp/work/lzo-1.08-r14/install
tmp/work/lzo-1.08-r14/image</screen></para>
<para>The directory, <emphasis
role="bold">tmp/work/lzo-1.08-r14</emphasis>, is know as the working
directory for the recipe is held in the <emphasis
role="bold">WORKDIR</emphasis> variable in bitbake. You'll sometimes see
recipes refer directly to <emphasis role="bold">WORKDIR</emphasis> and
if so this is the directory they are referring to. The <emphasis
role="bold">1.08</emphasis> is the version of lzo and the <emphasis
role="bold">r14</emphasis> is the release number, as defined by the
<emphasis role="bold">PR</emphasis> variable in the recipe.</para>
<para>Under <emphasis role="bold">WORKDIR</emphasis> there are four
directories:</para>
<variablelist>
<varlistentry>
<term>temp</term>
<listitem>
<para>The temp directories contains logs and in some cases scripts
that actually implement specific tasks.</para>
<para>You can look at the logs in this directory to get more
information into what happened (or didn't happen). This is usually
the first thing to look at when things are going wrong and these
usually need to be included when reporting bugs.</para>
<para>The scripts can be used to see what a particular task, such
as configure or compile, is trying to do.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>lzo-1.08</term>
<listitem>
<para>This is the unpacked source code directory, which was
created when the lzo source code was extracted in this directory.
The name and format of this directory is therefore dependent on
the actual source code packaging. Within recipes this directory is
referred to as <emphasis role="bold">S</emphasis> and is usually
expected to be named like this, that is
<emphasis><name>-<version></emphasis>. If the source
code extracts to somewhere else you would need to manually specify
the value of <emphasis role="bold">S</emphasis> in your
recipe.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>install</term>
<listitem>
<para>The installation directory (or destination directory) is
where the software needs to be installed into in order to be
packaged. This directory is referred to as <emphasis
role="bold">D</emphasis> in recipes. So instead of installing into
<emphasis role="bold">/usr/bin</emphasis> and <emphasis
role="bold">/usr/lib</emphasis> for example you would need to
install into <emphasis role="bold">${D}/usr/bin</emphasis> and
<emphasis role="bold">${D}/usr/lib</emphasis> in order for the
packaging system to work.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>image</term>
<listitem>
<para>The image directory is used to split the installed files
into separate packages. One subdirectory is created per package to
be generated and the files and moved from the install directory
(<emphasis role="bold">D</emphasis>) over to this directory as
each packaging instruction is processed. Typically there will be
separate documentation (<emphasis>-doc</emphasis>), debugging
(<emphasis>-dbg</emphasis>) and development
(<emphasis>-dev</emphasis>) packages automatically created.</para>
</listitem>
</varlistentry>
</variablelist>
<para>The various variables that can be used in a recipe are described
in detail in the recipes chapter of this manual.</para>
<para>What can you do with this information? How about checking out what
happened during the configuration of lzo:<screen>~%> less tmp/work/lzo-1.08-r14/temp/log.do_configure.*
...
checking whether ccache sh4-linux-gcc -ml -m4 suffers the -fschedule-insns bug... unknown
checking whether ccache sh4-linux-gcc -ml -m4 suffers the -fstrength-reduce bug... unknown
checking whether ccache sh4-linux-gcc -ml -m4 accepts -fstrict-aliasing... yes
checking the alignment of the assembler... 0
checking whether to build assembler versions... no
configure: creating ./config.status
config.status: creating Makefile
config.status: creating examples/Makefile
config.status: creating include/Makefile
config.status: creating ltest/Makefile
config.status: creating minilzo/Makefile
config.status: creating src/Makefile
config.status: creating tests/Makefile
config.status: creating config.h
config.status: executing depfiles commands</screen></para>
<para>Or perhaps you want to see which files were included in each of
the generated packages:<screen>~%> find tmp/work/lzo-1.08-r14/install
tmp/work/lzo-1.08-r14/install
tmp/work/lzo-1.08-r14/install/lzo-doc
tmp/work/lzo-1.08-r14/install/lzo-dbg
tmp/work/lzo-1.08-r14/install/lzo-dbg/usr
tmp/work/lzo-1.08-r14/install/lzo-dbg/usr/lib
tmp/work/lzo-1.08-r14/install/lzo-dbg/usr/lib/.debug
tmp/work/lzo-1.08-r14/install/lzo-dbg/usr/lib/.debug/liblzo.so.1.0.0
tmp/work/lzo-1.08-r14/install/lzo-dev
tmp/work/lzo-1.08-r14/install/lzo-dev/usr
tmp/work/lzo-1.08-r14/install/lzo-dev/usr/include
tmp/work/lzo-1.08-r14/install/lzo-dev/usr/include/lzo2a.h
tmp/work/lzo-1.08-r14/install/lzo-dev/usr/include/lzo1y.h
tmp/work/lzo-1.08-r14/install/lzo-dev/usr/include/lzo1.h
tmp/work/lzo-1.08-r14/install/lzo-dev/usr/include/lzo1b.h
tmp/work/lzo-1.08-r14/install/lzo-dev/usr/include/lzo1f.h
tmp/work/lzo-1.08-r14/install/lzo-dev/usr/include/lzoconf.h
tmp/work/lzo-1.08-r14/install/lzo-dev/usr/include/lzo1x.h
tmp/work/lzo-1.08-r14/install/lzo-dev/usr/include/lzo16bit.h
tmp/work/lzo-1.08-r14/install/lzo-dev/usr/include/lzo1a.h
tmp/work/lzo-1.08-r14/install/lzo-dev/usr/include/lzo1z.h
tmp/work/lzo-1.08-r14/install/lzo-dev/usr/include/lzoutil.h
tmp/work/lzo-1.08-r14/install/lzo-dev/usr/include/lzo1c.h
tmp/work/lzo-1.08-r14/install/lzo-dev/usr/lib
tmp/work/lzo-1.08-r14/install/lzo-dev/usr/lib/liblzo.a
tmp/work/lzo-1.08-r14/install/lzo-dev/usr/lib/liblzo.so
tmp/work/lzo-1.08-r14/install/lzo-dev/usr/lib/liblzo.la
tmp/work/lzo-1.08-r14/install/lzo.shlibdeps
tmp/work/lzo-1.08-r14/install/lzo-locale
tmp/work/lzo-1.08-r14/install/lzo
tmp/work/lzo-1.08-r14/install/lzo/usr
tmp/work/lzo-1.08-r14/install/lzo/usr/lib
tmp/work/lzo-1.08-r14/install/lzo/usr/lib/liblzo.so.1
tmp/work/lzo-1.08-r14/install/lzo/usr/lib/liblzo.so.1.0.0</screen></para>
</section>
</section>
<section id="usage_tasks" xreflabel="tasks">
<title>Tasks</title>
<para>When you build a software package you generally perform a number of
steps or tasks. These would include things like "download the source
code", "unpack the source code", "run the configure script", "build the
software", "install the software" etc. OpenEmbedded builds software in a
similar way - by performing a set of tasks. Understanding these tasks is
critical to understanding how things get done in OpenEmbedded.</para>
<para></para>
<para>The following is a list of the most commonly seen tasks:</para>
<variablelist>
<varlistentry>
<term>fetch</term>
<listitem>
<para>The fetch task is responsible for fetching any source code
that is required. This means things such as downloading files and
checking out from svn or git repositories for example.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>unpack</term>
<listitem>
<para>The unpack task is responsible for extracting files from
archives, such as .tar.gz, into the working area and copying any
additional files into the working area.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>patch</term>
<listitem>
<para>The patch task is responsible for applying any patches to the
unpacked source code</para>
</listitem>
</varlistentry>
<varlistentry>
<term>configure</term>
<listitem>
<para>The configure task takes care of the configuration of the
package. Running a configure script ("./configure <options>")
is probably the form of configuration that is most recognised but
it's not the only configuration system that exists.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>compile</term>
<listitem>
<para>The compile task actually compiles the software. This could be
as simple as running "make".</para>
</listitem>
</varlistentry>
<varlistentry>
<term>populate_staging (stage)</term>
<listitem>
<para>The populate_staging task (stage is an alternate, easier to
type name, that can be used to refer to this task) is responsible
for making available libraries and headers (if any) that may be
required by other packages to build. For example if you compile zlib
then it's headers and the library need to be made available for
other applications to include and link against.</para>
<para>NOTE that this is different to the install (and packaging)
related tasks in that this is making available things for use during
build on the development host while the installed files are being
made available for use on the target device.</para>
</listitem>
</varlistentry>
<varlistentry>
<term></term>
<listitem>
<para></para>
</listitem>
</varlistentry>
<varlistentry>
<term>install</term>
<listitem>
<para>The install task is responsible for actually installing the
software. Now this needs to install the software into the
destination directory (${D}) but once package the destination
directory will be removed from all the files. In other words if you
install something into ${D}/bin then it will end up in the /bin
directory in the package and therefore on the target.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>package</term>
<listitem>
<para>The package task takes the installed files and splits them
into separate directories under the ${WORKDIR}/install directory,
one per package. It moves the files for the destination directory,
${D}, that they were installed in into the appropriate packages
subdirectory. Usually there will be a main package a separate
documentation (-doc), development (-dev) and debugging packages
(-dbg) for example.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>package_write</term>
<listitem>
<para>The package_write task is responsible for taking each packages
subdirectory and creating any actual installation package, such as
.ipk, .deb or .rpm.</para>
</listitem>
</varlistentry>
<varlistentry>
<term></term>
<listitem>
<para></para>
</listitem>
</varlistentry>
</variablelist>
<para></para>
<para>Note that these are not the only possible set of tasks. There are
various methods available to insert additional tasks in between existing
tasks if needed. As an example the insane.bbclass, which performs various
QA checks, does these checks by inserting a new task, qa_configure,
between the configure and compile tasks to check on the result of
configuration and another new tasks, qa_staging, between populate_staging
and build to validate the files that have been staged.</para>
<para></para>
<para>You can see a list of all the tasks available for a specific recipe
by explicitly calling bitbake on the recipe and asking it for a list of
tasks:</para>
<para><screen>~%> bitbake -b packages/perl/perl_5.8.8.bb -c listtasks
NOTE: package perl-5.8.8: started
NOTE: package perl-5.8.8-r11: task do_listtasks: started
do_fetchall
do_listtasks
do_rebuild
do_compile
do_build
do_populate_staging
do_mrproper
do_fetch
do_configure
do_clean
do_package
do_unpack
do_install
do_package_write
do_distribute_sources
do_showdata
do_qa_configure
do_qa_staging
do_patch
NOTE: package perl-5.8.8-r11: task do_listtasks: completed
NOTE: package perl-5.8.8: completed
~%> </screen></para>
<para>Note that <emphasis>do_</emphasis> prefixed to the tasks - the
<emphasis>do_<task></emphasis> is the name of the method that
implements the required functionality for
<emphasis><task></emphasis>, so the above is actually listing the
methods that implement the available tasks. It's sometimes a but confusing
but just remember that the do_ is the method name (with a definition
usually found in the of the .bbclass files in the classes
directory.)</para>
</section>
<section id="usage_workwithsinglepackage"
xreflabel="working with a single package">
<title>Working with a single package</title>
<para>When working on fixing and/or creating a single recipe you can ask
bitbake to deal directly with a single .bb file only. The <emphasis>-b
<bb-file></emphasis> option asks bitbake to only process the named
file. Note that this ignores any dependencies that are in the recipe, so
these must have already been handled.</para>
<para>A typically example of this is to clean and then rebuild a package
with some debugging information:</para>
<para><screen>%> bitbake -b <bb-file> -c clean
%> bitbake -b <bb-file> -D</screen></para>
<para>The various options to bitbake that are useful here are:</para>
<variablelist>
<varlistentry>
<term>-b <bb-file></term>
<listitem>
<para>Specify which recipe to process;</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-c <action></term>
<listitem>
<para>Specify which action to perform, typically the name of one of
the tasks supported by the recipe;</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-D</term>
<listitem>
<para>Display debugging information, use two <emphasis
role="bold">-D</emphasis>'s for additional debugging.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-f</term>
<listitem>
<para>Force an operation. This is useful in getting bitbake to
perform some operation it normally wouldn't do. For example, if you
try and compile twice in a row then bitbake will not do anything on
the second attempt since it has already performed the compile task.
By adding <emphasis role="bold">-f</emphasis> it will force it to
perform the action regardless of if it thinks it's been done
previously.</para>
</listitem>
</varlistentry>
</variablelist>
<para>The most common actions (used with -c) are:</para>
<variablelist>
<varlistentry>
<term>fetch</term>
<listitem>
<para>Try to download all of the required source files, but don't do
anything else with them.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>unpack</term>
<listitem>
<para>Unpack the source file but don't apply the patches yet.
Sometimes you may want to look at the extracted, but not patched
source code and that's what just unpacking will give you (some
time's handy to get diffs generated against the original
source).</para>
</listitem>
</varlistentry>
<varlistentry>
<term>patch</term>
<listitem>
<para>Apply any patches.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>configure</term>
<listitem>
<para>Performs and configuration that is required for the
software.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>compile</term>
<listitem>
<para>Perform the actual compilation steps of the software.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>stage</term>
<listitem>
<para>If any files, such as header and libraries, will be required
by other packages then they need to be installed into the staging
area and that's what this task takes care of.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>install</term>
<listitem>
<para>Install the software in preparation for packaging.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>package</term>
<listitem>
<para>Package the software. Remember that this moves the files from
the installation directory, D, into the packing install area. So to
re-package you also need to re-install first.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>clean</term>
<listitem>
<para>Delete the entire directory for this version of the software.
Usually done to allow a test build with no chance of old files or
changes being left behind.</para>
</listitem>
</varlistentry>
</variablelist>
<para>Note that each of the actions that corresponds to task's will run
any preceding tasks that have not yet been performed. So starting with
compile will also perform the fetch, unpack, patch and configure
actions.</para>
<para>A typically development session might involve editing files in the
working directory and recompiling until it all works:<screen>[... test ...]
%> bitbake -b packages/testapp/testapp_4.3.bb -c compile -D
[... save a copy of main.c and make some changes ...]
%> vi tmp/work/testapp-4.3-r0/main.c
%> bitbake -b packages/testapp/testapp_4.3.bb -c compile -D -f
[... create a patch and add it to the recipe ...]
%> vi packages/testapp/testapp_4.3.bb
[... test from clean ...]
%> bitbake -b packages/testapp/testapp_4.3.bb -c clean
%> bitbake -b packages/testapp/testapp_4.3.bb
[... NOTE: How to create the patch is not covered at this point ...]</screen></para>
<para>Here's another example showing how you might go about fixing up the
packaging in your recipe:<screen>%> bitbake -b packages/testapp/testapp_4.3.bb -c install -f
%> bitbake -b packages/testapp/testapp_4.3.bb -c stage -f
%> find tmp/work/testapp_4.3/install
...
%> vi packages/testapp/testapp_4.3.bb</screen>At this stage you play with
the <emphasis role="bold">PACKAGE_</emphasis> and <emphasis
role="bold">FILES_</emphasis> variables and then repeat the above
sequence.</para>
<para>Note how we install and then stage. This is one of those things
where understanding the tasks helps a lot! Remember that stage moves the
files from where they were installed (${D}) into the various
subdirectories (under <emphasis role="bold">${WORKDIR}/instal</emphasis>l)
for each package. So if you try and run a stage task without a prior
install there won't be any files there to stage! Note also that the stage
tasks clears all the subdirectories in <emphasis
role="bold">${WORKDIR}/install</emphasis> so you won't get any left over
files. But beware, the install task doesn't clear <emphasis
role="bold">${D}</emphasis> directory, so any left over files from a
previous packing attempt will be left behind (which is ok if all you care
about it staging).</para>
</section>
<section id="usage_interactive_bitbake" xreflabel="interactive bitbake">
<title>Interactive bitbake</title>
<para>To interactively test things use:<screen>%> bitbake -i</screen>this
will open the bitbake shell. From here there are a lot of commands
available (try help).</para>
<para>First thing you will want to do is parse all of the recipes (recent
bitbake version do this automatically when needed, so you don't need to
manually do this anymore):<screen>BB>> parse</screen>You can now
build a specific recipe:<screen>BB>> build net-snmp</screen>If it
fails you may want to clean the build before trying again:<screen>BB>> clean net-snmp</screen>If
you update the recipe by editing the .bb file (to fix some issues) then
you will want to clean the package, reparse the modified recipe, and the
build again:<screen>BB>> clean net-snmp
BB>> reparse net-snmp
BB>> build net-snmp</screen>Note that you can use wildcards in the
bitbake shell as well:<screen>BB>> build t*</screen></para>
<para></para>
</section>
<section id="usage_devshell" xreflabel="devshell">
<title>Devshell</title>
<para>[To be done]</para>
</section>
<section id="usage_patches" xreflabel="patching">
<title>Patching and patch management</title>
<para>[To be done]</para>
</section>
</chapter>
|