summaryrefslogtreecommitdiffstats
path: root/documentation/ref-manual/faq.xml
blob: 49ff86261da4cae89a6933b5ddffc7b65bbeb974 (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
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >

<chapter id='faq'>
<title>FAQ</title>
<qandaset>
    <qandaentry>
        <question>
            <para>
                How does Poky differ from <ulink url='&OE_HOME_URL;'>OpenEmbedded</ulink>?
            </para>
        </question>
        <answer>
            <para>
                The term "<link link='poky'>Poky</link>"
                refers to the specific reference build system that
                the Yocto Project provides.
                Poky is based on <link linkend='oe-core'>OE-Core</link>
                and <link linkend='bitbake-term'>BitBake</link>.
                Thus, the generic term used here for the build system is
                the "OpenEmbedded build system."
                Development in the Yocto Project using Poky is closely tied to OpenEmbedded, with
                changes always being merged to OE-Core or BitBake first before being pulled back
                into Poky.
                This practice benefits both projects immediately.
            </para>
        </answer>
    </qandaentry>

    <qandaentry>
        <question>
            <para id='faq-not-meeting-requirements'>
                My development system does not meet the
                required Git, tar, and Python versions.
                In particular, I do not have Python 3.4.0 or greater.
                Can I still use the Yocto Project?
            </para>
        </question>
        <answer>
            <para>
                You can get the required tools on your host development
                system a couple different ways (i.e. building a tarball or
                downloading a tarball).
                See the
                "<link linkend='required-git-tar-and-python-versions'>Required Git, tar, and Python Versions</link>"
                section for steps on how to update your build tools.
            </para>
        </answer>
    </qandaentry>

    <qandaentry>
        <question>
            <para>
                How can you claim Poky / OpenEmbedded-Core is stable?
            </para>
        </question>
        <answer>
            <para>
                There are three areas that help with stability;
                <itemizedlist>
                    <listitem><para>The Yocto Project team keeps
                        <link linkend='oe-core'>OE-Core</link> small
                        and focused, containing around 830 recipes as opposed to the thousands
                        available in other OpenEmbedded community layers.
                        Keeping it small makes it easy to test and maintain.</para></listitem>
                    <listitem><para>The Yocto Project team runs manual and automated tests
                        using a small, fixed set of reference hardware as well as emulated
                        targets.</para></listitem>
                    <listitem><para>The Yocto Project uses an autobuilder,
                        which provides continuous build and integration tests.</para></listitem>
                </itemizedlist>
            </para>
        </answer>
    </qandaentry>

    <qandaentry>
        <question>
            <para>
                How do I get support for my board added to the Yocto Project?
            </para>
        </question>
        <answer>
            <para>
                Support for an additional board is added by creating a
                Board Support Package (BSP) layer for it.
                For more information on how to create a BSP layer, see the
                "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>"
                section in the Yocto Project Development Tasks Manual and the
                <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>.
            </para>
            <para>
                Usually, if the board is not completely exotic, adding support in
                the Yocto Project is fairly straightforward.
            </para>
        </answer>
    </qandaentry>

    <qandaentry>
        <question>
            <para>
                Are there any products built using the OpenEmbedded build system?
            </para>
        </question>
        <answer>
            <para>
                The software running on the <ulink url='http://vernier.com/labquest/'>Vernier LabQuest</ulink>
                is built using the OpenEmbedded build system.
                See the <ulink url='http://www.vernier.com/products/interfaces/labq/'>Vernier LabQuest</ulink>
                website for more information.
                There are a number of pre-production devices using the OpenEmbedded build system
                and the Yocto Project team
                announces them as soon as they are released.
            </para>
        </answer>
    </qandaentry>

    <qandaentry>
        <question>
            <para>
                What does the OpenEmbedded build system produce as output?
            </para>
        </question>
        <answer>
            <para>
                Because you can use the same set of recipes to create output of
                various formats, the output of an OpenEmbedded build depends on
                how you start it.
                Usually, the output is a flashable image ready for the target
                device.
            </para>
        </answer>
    </qandaentry>

    <qandaentry>
        <question>
            <para>
                How do I add my package to the Yocto Project?
            </para>
        </question>
        <answer>
            <para>
                To add a package, you need to create a BitBake recipe.
                For information on how to create a BitBake recipe, see the
                "<ulink url='&YOCTO_DOCS_DEV_URL;#new-recipe-writing-a-new-recipe'>Writing a New Recipe</ulink>"
                section in the Yocto Project Development Tasks Manual.
            </para>
        </answer>
    </qandaentry>

    <qandaentry>
        <question>
            <para>
                Do I have to reflash my entire board with a new Yocto Project image when recompiling
                a package?
            </para>
        </question>
        <answer>
            <para>
                The OpenEmbedded build system can build packages in various
                formats such as IPK for OPKG, Debian package
                (<filename>.deb</filename>), or RPM.
                You can then upgrade the packages using the package tools on
                the device, much like on a desktop distribution such as
                Ubuntu or Fedora.
                However, package management on the target is entirely optional.
            </para>
        </answer>
    </qandaentry>

    <qandaentry>
        <question>
            <para>
                I see the error '<filename>chmod: XXXXX new permissions are r-xrwxrwx, not r-xr-xr-x</filename>'.
                What is wrong?
            </para>
        </question>
        <answer>
            <para>
                You are probably running the build on an NTFS filesystem.
                Use <filename>ext2</filename>, <filename>ext3</filename>, or <filename>ext4</filename> instead.
            </para>
        </answer>
    </qandaentry>

<!--    <qandaentry>
        <question>
            <para>
                How do I make the Yocto Project work in RHEL/CentOS?
            </para>
        </question>
        <answer>
            <para>
                To get the Yocto Project working under RHEL/CentOS 5.1 you need to first
                install some required packages.
                The standard CentOS packages needed are:
                <itemizedlist>
                    <listitem><para>"Development tools" (selected during installation)</para></listitem>
                    <listitem><para><filename>texi2html</filename></para></listitem>
                    <listitem><para><filename>compat-gcc-34</filename></para></listitem>
                </itemizedlist>
                On top of these, you need the following external packages:
                <itemizedlist>
                    <listitem><para><filename>python-sqlite2</filename> from
                        <ulink url='http://dag.wieers.com/rpm/packages/python-sqlite2/'>DAG repository</ulink>
                        </para></listitem>
                    <listitem><para><filename>help2man</filename> from
                        <ulink url='http://centos.karan.org/el4/extras/stable/x86_64/RPMS/repodata/repoview/help2man-0-1.33.1-2.html'>Karan repository</ulink></para></listitem>
                </itemizedlist>
            </para>

            <para>
                Once these packages are installed, the OpenEmbedded build system will be able
                to build standard images.
                However, there might be a problem with the QEMU emulator segfaulting.
                You can either disable the generation of binary locales by setting
                <filename><link linkend='var-ENABLE_BINARY_LOCALE_GENERATION'>ENABLE_BINARY_LOCALE_GENERATION</link>
                </filename> to "0" or by removing the <filename>linux-2.6-execshield.patch</filename>
                from the kernel and rebuilding it since that is the patch that causes the problems with QEMU.
            </para>

            <note>
                <para>For information on distributions that the Yocto Project
                uses during validation, see the
                <ulink url='&YOCTO_WIKI_URL;/wiki/Distribution_Support'>Distribution Support</ulink>
                Wiki page.</para>
                <para>For notes about using the Yocto Project on a RHEL 4-based
                host, see the
                <ulink url='&YOCTO_WIKI_URL;/wiki/BuildingOnRHEL4'>Building on RHEL4</ulink>
                Wiki page.</para>
            </note>
        </answer>
    </qandaentry> -->

    <qandaentry>
        <question>
            <para>
                I see lots of 404 responses for files when the OpenEmbedded
                build system is trying to download sources.
                Is something wrong?
            </para>
        </question>
        <answer>
            <para>
                Nothing is wrong.
                The OpenEmbedded build system checks any configured source mirrors before downloading
                from the upstream sources.
                The build system does this searching for both source archives and
                pre-checked out versions of SCM-managed software.
                These checks help in large installations because it can reduce load on the SCM servers
                themselves.
                The address above is one of the default mirrors configured into the
                build system.
                Consequently, if an upstream source disappears, the team
                can place sources there so builds continue to work.
            </para>
        </answer>
    </qandaentry>

    <qandaentry>
        <question>
            <para>
                I have machine-specific data in a package for one machine only but the package is
                being marked as machine-specific in all cases, how do I prevent this?
            </para>
        </question>
        <answer>
            <para>
                Set <filename><link linkend='var-SRC_URI_OVERRIDES_PACKAGE_ARCH'>SRC_URI_OVERRIDES_PACKAGE_ARCH</link>
                </filename> = "0" in the <filename>.bb</filename> file but make sure the package is
                manually marked as
                machine-specific for the case that needs it.
                The code that handles
                <filename>SRC_URI_OVERRIDES_PACKAGE_ARCH</filename> is in
                the <filename>meta/classes/base.bbclass</filename> file.
            </para>
        </answer>
    </qandaentry>

    <qandaentry>
        <question>
            <para id='i-am-behind-a-firewall-and-need-to-use-a-proxy-server'>
                I'm behind a firewall and need to use a proxy server. How do I do that?
            </para>
        </question>
        <answer>
            <para>
                Most source fetching by the OpenEmbedded build system is done
                by <filename>wget</filename> and you therefore need to specify
                the proxy settings in a <filename>.wgetrc</filename> file,
                which can be in your home directory if you are a single user
                or can be in <filename>/usr/local/etc/wgetrc</filename> as
                a global user file.
            </para>

            <para>
                Following is the applicable code for setting various proxy
                types in the <filename>.wgetrc</filename> file.
                By default, these settings are disabled with comments.
                To use them, remove the comments:
                <literallayout class='monospaced'>
     # You can set the default proxies for Wget to use for http, https, and ftp.
     # They will override the value in the environment.
     #https_proxy = http://proxy.yoyodyne.com:18023/
     #http_proxy = http://proxy.yoyodyne.com:18023/
     #ftp_proxy = http://proxy.yoyodyne.com:18023/

     # If you do not want to use proxy at all, set this to off.
     #use_proxy = on
                </literallayout>
                The Yocto Project also includes a
                <filename>meta-poky/conf/site.conf.sample</filename> file that
                shows how to configure CVS and Git proxy servers if needed.
                For more information on setting up various proxy types and
                configuring proxy servers, see the
                "<ulink url='&YOCTO_WIKI_URL;/wiki/Working_Behind_a_Network_Proxy'>Working Behind a Network Proxy</ulink>"
                Wiki page.
            </para>
        </answer>
    </qandaentry>

    <qandaentry>
        <question>
            <para>
                What’s the difference between <replaceable>target</replaceable> and <replaceable>target</replaceable><filename>-native</filename>?
            </para>
        </question>
        <answer>
            <para>
                The <filename>*-native</filename> targets are designed to run on the system
                being used for the build.
                These are usually tools that are needed to assist the build in some way such as
                <filename>quilt-native</filename>, which is used to apply patches.
                The non-native version is the one that runs on the target device.
            </para>
        </answer>
    </qandaentry>

    <qandaentry>
        <question>
            <para>
                I'm seeing random build failures. Help?!
            </para>
        </question>
        <answer>
            <para>
                If the same build is failing in totally different and random
                ways, the most likely explanation is:
                <itemizedlist>
                    <listitem><para>The hardware you are running the build on
                        has some problem.</para></listitem>
                    <listitem><para>You are running the build under
                        virtualization, in which case the virtualization
                        probably has bugs.</para></listitem>
                </itemizedlist>
                The OpenEmbedded build system processes a massive amount of
                data that causes lots of network, disk and CPU activity and
                is sensitive to even single-bit failures in any of these areas.
                True random failures have always been traced back to hardware
                or virtualization issues.
            </para>
        </answer>
    </qandaentry>

    <qandaentry>
        <question>
            <para>
                When I try to build a native recipe, the build fails with <filename>iconv.h</filename> problems.
            </para>
        </question>
        <answer>
            <para>
                If you get an error message that indicates GNU
                <filename>libiconv</filename> is not in use but
                <filename>iconv.h</filename> has been included from
                <filename>libiconv</filename>, you need to check to see if
                you have a previously installed version of the header file
                in <filename>/usr/local/include</filename>.
                <literallayout class='monospaced'>
     #error GNU libiconv not in use but included iconv.h is from libiconv
                </literallayout>
                If you find a previously installed file, you should either
                uninstall it or temporarily rename it and try the build again.
            </para>

            <para>
                This issue is just a single manifestation of "system
                leakage" issues caused when the OpenEmbedded build system
                finds and uses previously installed files during a native
                build.
                This type of issue might not be limited to
                <filename>iconv.h</filename>.
                Be sure that leakage cannot occur from
                <filename>/usr/local/include</filename> and
                <filename>/opt</filename> locations.
            </para>
        </answer>
    </qandaentry>

    <qandaentry>
        <question>
            <para>
                What do we need to ship for license compliance?
            </para>
        </question>
        <answer>
            <para>
                This is a difficult question and you need to consult your lawyer
                for the answer for your specific case.
                It is worth bearing in mind that for GPL compliance, there needs
                to be enough information shipped to allow someone else to
                rebuild and produce the same end result you are shipping.
                This means sharing the source code, any patches applied to it,
                and also any configuration information about how that package
                was configured and built.
            </para>

            <para>
                You can find more information on licensing in the
                "<ulink url='&YOCTO_DOCS_OM_URL;#licensing'>Licensing</ulink>"
                section in the Yocto Project Overview and Concepts Manual
                and also in the
                "<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-open-source-license-compliance-during-your-products-lifecycle'>Maintaining Open Source License Compliance During Your Product's Lifecycle</ulink>"
                section in the Yocto Project Development Tasks Manual.
            </para>
        </answer>
    </qandaentry>

    <qandaentry>
        <question>
            <para>
                How do I disable the cursor on my touchscreen device?
            </para>
        </question>
        <answer>
            <para>
                You need to create a form factor file as described in the
                "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-filelayout-misc-recipes'>Miscellaneous BSP-Specific Recipe Files</ulink>"
                section in the Yocto Project Board Support Packages (BSP)
                Developer's Guide.
                Set the <filename>HAVE_TOUCHSCREEN</filename> variable equal to
                one as follows:
                <literallayout class='monospaced'>
     HAVE_TOUCHSCREEN=1
                </literallayout>
            </para>
        </answer>
    </qandaentry>

    <qandaentry>
        <question>
            <para>
                How do I make sure connected network interfaces are brought up by default?
            </para>
        </question>
        <answer>
            <para>
                The default interfaces file provided by the netbase recipe does not
                automatically bring up network interfaces.
                Therefore, you will need to add a BSP-specific netbase that includes an interfaces
                file.
                See the "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-filelayout-misc-recipes'>Miscellaneous BSP-Specific Recipe Files</ulink>"
                section in the Yocto Project Board Support Packages (BSP)
                Developer's Guide for information on creating these types of
                miscellaneous recipe files.
            </para>
            <para>
                For example, add the following files to your layer:
                <literallayout class='monospaced'>
     meta-MACHINE/recipes-bsp/netbase/netbase/MACHINE/interfaces
     meta-MACHINE/recipes-bsp/netbase/netbase_5.0.bbappend
                </literallayout>
            </para>
        </answer>
    </qandaentry>

    <qandaentry>
        <question>
            <para>
                How do I create images with more free space?
            </para>
        </question>
        <answer>
            <para>
                By default, the OpenEmbedded build system creates images
                that are 1.3 times the size of the populated root filesystem.
                To affect the image size, you need to set various
                configurations:
                <itemizedlist>
                    <listitem><para><emphasis>Image Size:</emphasis>
                        The OpenEmbedded build system uses the
                        <link linkend='var-IMAGE_ROOTFS_SIZE'><filename>IMAGE_ROOTFS_SIZE</filename></link>
                        variable to define the size of the image in Kbytes.
                        The build system determines the size by taking into
                        account the initial root filesystem size before any
                        modifications such as requested size for the image and
                        any requested additional free disk space to be
                        added to the image.</para></listitem>
                    <listitem><para><emphasis>Overhead:</emphasis>
                        Use the
                        <link linkend='var-IMAGE_OVERHEAD_FACTOR'><filename>IMAGE_OVERHEAD_FACTOR</filename></link>
                        variable to define the multiplier that the build system
                        applies to the initial image size, which is 1.3 by
                        default.</para></listitem>
                    <listitem><para><emphasis>Additional Free Space:</emphasis>
                        Use the
                        <link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'><filename>IMAGE_ROOTFS_EXTRA_SPACE</filename></link>
                        variable to add additional free space to the image.
                        The build system adds this space to the image after
                        it determines its
                        <filename>IMAGE_ROOTFS_SIZE</filename>.
                        </para></listitem>
                </itemizedlist>
            </para>
        </answer>
    </qandaentry>

    <qandaentry>
        <question>
            <para>
                Why don't you support directories with spaces in the pathnames?
            </para>
        </question>
        <answer>
            <para>
                The Yocto Project team has tried to do this before but too
                many of the tools the OpenEmbedded build system depends on,
                such as <filename>autoconf</filename>, break when they find
                spaces in pathnames.
                Until that situation changes, the team will not support spaces
                in pathnames.
            </para>
        </answer>
    </qandaentry>

    <qandaentry>
        <question>
            <para>
                How do I use an external toolchain?
            </para>
        </question>
        <answer>
            <para>
                The toolchain configuration is very flexible and customizable.
                It is primarily controlled with the
                <filename><link linkend='var-TCMODE'>TCMODE</link></filename>
                variable.
                This variable controls which <filename>tcmode-*.inc</filename>
                file to include from the
                <filename>meta/conf/distro/include</filename> directory within
                the
                <link linkend='source-directory'>Source Directory</link>.
            </para>

            <para>
                The default value of <filename>TCMODE</filename> is "default",
                which tells the OpenEmbedded build system to use its internally
                built toolchain (i.e. <filename>tcmode-default.inc</filename>).
                However, other patterns are accepted.
                In particular, "external-*" refers to external toolchains.
                One example is the Sourcery G++ Toolchain.
                The support for this toolchain resides in the separate
                <filename>meta-sourcery</filename> layer at
                <ulink url='http://github.com/MentorEmbedded/meta-sourcery/'></ulink>.
            </para>

            <para>
                In addition to the toolchain configuration, you also need a
                corresponding toolchain recipe file.
                This recipe file needs to package up any pre-built objects in
                the toolchain such as <filename>libgcc</filename>,
                <filename>libstdcc++</filename>, any locales, and
                <filename>libc</filename>.
            </para>
        </answer>
    </qandaentry>

    <qandaentry>
        <question>
            <para id='how-does-the-yocto-project-obtain-source-code-and-will-it-work-behind-my-firewall-or-proxy-server'>
                How does the OpenEmbedded build system obtain source code and
                will it work behind my firewall or proxy server?
            </para>
        </question>
        <answer>
            <para>
                The way the build system obtains source code is highly
                configurable.
                You can setup the build system to get source code in most
                environments if HTTP transport is available.
            </para>
            <para>
                When the build system searches for source code, it first
                tries the local download directory.
                If that location fails, Poky tries
                <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>,
                the upstream source, and then
                <link linkend='var-MIRRORS'><filename>MIRRORS</filename></link>
                in that order.
            </para>
            <para>
                Assuming your distribution is "poky", the OpenEmbedded build
                system uses the Yocto Project source
                <filename>PREMIRRORS</filename> by default for SCM-based
                sources, upstreams for normal tarballs, and then falls back
                to a number of other mirrors including the Yocto Project
                source mirror if those fail.
            </para>
            <para>
                As an example, you could add a specific server for the
                build system to attempt before any others by adding something
                like the following to the <filename>local.conf</filename>
                configuration file:
                <literallayout class='monospaced'>
     PREMIRRORS_prepend = "\
     git://.*/.* http://www.yoctoproject.org/sources/ \n \
     ftp://.*/.* http://www.yoctoproject.org/sources/ \n \
     http://.*/.* http://www.yoctoproject.org/sources/ \n \
     https://.*/.* http://www.yoctoproject.org/sources/ \n"
                </literallayout>
            </para>
            <para>
                These changes cause the build system to intercept Git, FTP,
                HTTP, and HTTPS requests and direct them to the
                <filename>http://</filename> sources mirror.
                You can use <filename>file://</filename> URLs to point to
                local directories or network shares as well.
            </para>
            <para>
                Aside from the previous technique, these options also exist:
                <literallayout class='monospaced'>
     BB_NO_NETWORK = "1"
                </literallayout>
                This statement tells BitBake to issue an error instead of
                trying to access the Internet.
                This technique is useful if you want to ensure code builds
                only from local sources.
            </para>
            <para>
                Here is another technique:
                <literallayout class='monospaced'>
     BB_FETCH_PREMIRRORONLY = "1"
                </literallayout>
                This statement limits the build system to pulling source
                from the <filename>PREMIRRORS</filename> only.
                Again, this technique is useful for reproducing builds.
            </para>
            <para>
                Here is another technique:
                <literallayout class='monospaced'>
     BB_GENERATE_MIRROR_TARBALLS = "1"
                </literallayout>
                This statement tells the build system to generate mirror
                tarballs.
                This technique is useful if you want to create a mirror server.
                If not, however, the technique can simply waste time during
                the build.
            </para>
            <para>
                Finally, consider an example where you are behind an
                HTTP-only firewall.
                You could make the following changes to the
                <filename>local.conf</filename> configuration file as long as
                the <filename>PREMIRRORS</filename> server is current:
                <literallayout class='monospaced'>
     PREMIRRORS_prepend = "\
     ftp://.*/.* http://www.yoctoproject.org/sources/ \n \
     http://.*/.* http://www.yoctoproject.org/sources/ \n \
     https://.*/.* http://www.yoctoproject.org/sources/ \n"
     BB_FETCH_PREMIRRORONLY = "1"
                </literallayout>
                These changes would cause the build system to successfully
                fetch source over HTTP and any network accesses to anything
                other than the <filename>PREMIRRORS</filename> would fail.
            </para>
            <para>
                The build system also honors the standard shell environment
                variables <filename>http_proxy</filename>,
                <filename>ftp_proxy</filename>,
                <filename>https_proxy</filename>, and
                <filename>all_proxy</filename> to redirect requests through
                proxy servers.
            </para>
            <note>
                 You can find more information on the
                 "<ulink url='&YOCTO_WIKI_URL;/wiki/Working_Behind_a_Network_Proxy'>Working Behind a Network Proxy</ulink>"
                 Wiki page.
            </note>
        </answer>
    </qandaentry>

    <qandaentry>
        <question>
            <para>
                Can I get rid of build output so I can start over?
            </para>
        </question>
        <answer>
            <para>
                Yes - you can easily do this.
                When you use BitBake to build an image, all the build output
                goes into the directory created when you run the
                build environment setup script (i.e.
                <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>).
                By default, this
                <link linkend='build-directory'>Build Directory</link>
                is named <filename>build</filename> but can be named
                anything you want.
            </para>

            <para>
                Within the Build Directory, is the <filename>tmp</filename>
                directory.
                To remove all the build output yet preserve any source code or
                downloaded files from previous builds, simply remove the
                <filename>tmp</filename> directory.
            </para>
        </answer>
    </qandaentry>

    <qandaentry>
        <question>
            <para>
                Why do <filename>${bindir}</filename> and <filename>${libdir}</filename> have strange values for <filename>-native</filename> recipes?
            </para>
        </question>
        <answer>
            <para>
                Executables and libraries might need to be used from a
                directory other than the directory into which they were
                initially installed.
                Complicating this situation is the fact that sometimes these
                executables and libraries are compiled with the expectation
                of being run from that initial installation target directory.
                If this is the case, moving them causes problems.
            </para>

            <para>
                This scenario is a fundamental problem for package maintainers
                of mainstream Linux distributions as well as for the
                OpenEmbedded build system.
                As such, a well-established solution exists.
                Makefiles, Autotools configuration scripts, and other build
                systems are expected to respect environment variables such as
                <filename>bindir</filename>, <filename>libdir</filename>,
                and <filename>sysconfdir</filename> that indicate where
                executables, libraries, and data reside when a program is
                actually run.
                They are also expected to respect a
                <filename>DESTDIR</filename> environment variable, which is
                prepended to all the other variables when the build system
                actually installs the files.
                It is understood that the program does not actually run from
                within <filename>DESTDIR</filename>.
            </para>

            <para>
                When the OpenEmbedded build system uses a recipe to build a
                target-architecture program (i.e. one that is intended for
                inclusion on the image being built), that program eventually
                runs from the root file system of that image.
                Thus, the build system provides a value of "/usr/bin" for
                <filename>bindir</filename>, a value of "/usr/lib" for
                <filename>libdir</filename>, and so forth.
            </para>

            <para>
                Meanwhile, <filename>DESTDIR</filename> is a path within the
                <link linkend='build-directory'>Build Directory</link>.
                However, when the recipe builds a native program (i.e. one
                that is intended to run on the build machine), that program
                is never installed directly to the build machine's root
                file system.
                Consequently, the build system uses paths within the Build
                Directory for <filename>DESTDIR</filename>,
                <filename>bindir</filename> and related variables.
                To better understand this, consider the following two paths
                where the first is relatively normal and the second is not:
                <note>
                    Due to these lengthy examples, the paths are artificially
                    broken across lines for readability.
                </note>
                <literallayout class='monospaced'>
     /home/maxtothemax/poky-bootchart2/build/tmp/work/i586-poky-linux/zlib/
        1.2.8-r0/sysroot-destdir/usr/bin

     /home/maxtothemax/poky-bootchart2/build/tmp/work/x86_64-linux/
        zlib-native/1.2.8-r0/sysroot-destdir/home/maxtothemax/poky-bootchart2/
        build/tmp/sysroots/x86_64-linux/usr/bin
                </literallayout>
                Even if the paths look unusual, they both are correct -
                the first for a target and the second for a native recipe.
                These paths are a consequence of the
                <filename>DESTDIR</filename> mechanism and while they
                appear strange, they are correct and in practice very effective.
            </para>
        </answer>
    </qandaentry>

    <qandaentry>
        <question>
            <para>
                The files provided by my <filename>*-native</filename> recipe do
                not appear to be available to other recipes.
                Files are missing from the native sysroot, my recipe is
                installing to the wrong place, or I am getting permissions
                errors during the do_install task in my recipe! What is wrong?
            </para>
        </question>
        <answer>
            <para>
                This situation results when a build system does
                not recognize the environment variables supplied to it by
                <link linkend='bitbake-term'>BitBake</link>.
                The incident that prompted this FAQ entry involved a Makefile
                that used an environment variable named
                <filename>BINDIR</filename> instead of the more standard
                variable <filename>bindir</filename>.
                The makefile's hardcoded default value of "/usr/bin" worked
                most of the time, but not for the recipe's
                <filename>-native</filename> variant.
                For another example, permissions errors might be caused
                by a Makefile that ignores <filename>DESTDIR</filename> or uses
                a different name for that environment variable.
                Check the the build system to see if these kinds of
                issues exist.
            </para>
        </answer>
    </qandaentry>

</qandaset>
</chapter>
<!--
vim: expandtab tw=80 ts=4
-->