blob: d94cb32a8641e8295b0619e76f3e6bebe951507f [file] [log] [blame]
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<chapter id='faq'>
6<title>FAQ</title>
7<qandaset>
8 <qandaentry>
9 <question>
10 <para>
11 How does Poky differ from <ulink url='&OE_HOME_URL;'>OpenEmbedded</ulink>?
12 </para>
13 </question>
14 <answer>
15 <para>
Brad Bishopd7bf8c12018-02-25 22:55:05 -050016 The term "<link link='poky'>Poky</link>"
Patrick Williamsc124f4f2015-09-15 14:41:29 -050017 refers to the specific reference build system that
18 the Yocto Project provides.
Brad Bishopd7bf8c12018-02-25 22:55:05 -050019 Poky is based on <link linkend='oe-core'>OE-Core</link>
20 and <link linkend='bitbake-term'>BitBake</link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050021 Thus, the generic term used here for the build system is
22 the "OpenEmbedded build system."
23 Development in the Yocto Project using Poky is closely tied to OpenEmbedded, with
24 changes always being merged to OE-Core or BitBake first before being pulled back
25 into Poky.
26 This practice benefits both projects immediately.
27 </para>
28 </answer>
29 </qandaentry>
30
31 <qandaentry>
32 <question>
33 <para id='faq-not-meeting-requirements'>
34 My development system does not meet the
35 required Git, tar, and Python versions.
Andrew Geissler82c905d2020-04-13 13:39:40 -050036 In particular, I do not have Python 3.5.0 or greater.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050037 Can I still use the Yocto Project?
38 </para>
39 </question>
40 <answer>
41 <para>
42 You can get the required tools on your host development
43 system a couple different ways (i.e. building a tarball or
44 downloading a tarball).
45 See the
Andrew Geissler82c905d2020-04-13 13:39:40 -050046 "<link linkend='required-git-tar-python-and-gcc-versions'>Required Git, tar, Python and gcc Versions</link>"
Patrick Williamsc124f4f2015-09-15 14:41:29 -050047 section for steps on how to update your build tools.
48 </para>
49 </answer>
50 </qandaentry>
51
52 <qandaentry>
53 <question>
54 <para>
55 How can you claim Poky / OpenEmbedded-Core is stable?
56 </para>
57 </question>
58 <answer>
59 <para>
60 There are three areas that help with stability;
61 <itemizedlist>
62 <listitem><para>The Yocto Project team keeps
Brad Bishopd7bf8c12018-02-25 22:55:05 -050063 <link linkend='oe-core'>OE-Core</link> small
Patrick Williamsc124f4f2015-09-15 14:41:29 -050064 and focused, containing around 830 recipes as opposed to the thousands
65 available in other OpenEmbedded community layers.
66 Keeping it small makes it easy to test and maintain.</para></listitem>
67 <listitem><para>The Yocto Project team runs manual and automated tests
68 using a small, fixed set of reference hardware as well as emulated
69 targets.</para></listitem>
70 <listitem><para>The Yocto Project uses an autobuilder,
71 which provides continuous build and integration tests.</para></listitem>
72 </itemizedlist>
73 </para>
74 </answer>
75 </qandaentry>
76
77 <qandaentry>
78 <question>
79 <para>
80 How do I get support for my board added to the Yocto Project?
81 </para>
82 </question>
83 <answer>
84 <para>
85 Support for an additional board is added by creating a
86 Board Support Package (BSP) layer for it.
87 For more information on how to create a BSP layer, see the
88 "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -050089 section in the Yocto Project Development Tasks Manual and the
Patrick Williamsc124f4f2015-09-15 14:41:29 -050090 <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>.
91 </para>
92 <para>
93 Usually, if the board is not completely exotic, adding support in
94 the Yocto Project is fairly straightforward.
95 </para>
96 </answer>
97 </qandaentry>
98
99 <qandaentry>
100 <question>
101 <para>
102 Are there any products built using the OpenEmbedded build system?
103 </para>
104 </question>
105 <answer>
106 <para>
107 The software running on the <ulink url='http://vernier.com/labquest/'>Vernier LabQuest</ulink>
108 is built using the OpenEmbedded build system.
109 See the <ulink url='http://www.vernier.com/products/interfaces/labq/'>Vernier LabQuest</ulink>
110 website for more information.
111 There are a number of pre-production devices using the OpenEmbedded build system
112 and the Yocto Project team
113 announces them as soon as they are released.
114 </para>
115 </answer>
116 </qandaentry>
117
118 <qandaentry>
119 <question>
120 <para>
121 What does the OpenEmbedded build system produce as output?
122 </para>
123 </question>
124 <answer>
125 <para>
126 Because you can use the same set of recipes to create output of
127 various formats, the output of an OpenEmbedded build depends on
128 how you start it.
129 Usually, the output is a flashable image ready for the target
130 device.
131 </para>
132 </answer>
133 </qandaentry>
134
135 <qandaentry>
136 <question>
137 <para>
138 How do I add my package to the Yocto Project?
139 </para>
140 </question>
141 <answer>
142 <para>
143 To add a package, you need to create a BitBake recipe.
144 For information on how to create a BitBake recipe, see the
145 "<ulink url='&YOCTO_DOCS_DEV_URL;#new-recipe-writing-a-new-recipe'>Writing a New Recipe</ulink>"
Brad Bishop316dfdd2018-06-25 12:45:53 -0400146 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500147 </para>
148 </answer>
149 </qandaentry>
150
151 <qandaentry>
152 <question>
153 <para>
154 Do I have to reflash my entire board with a new Yocto Project image when recompiling
155 a package?
156 </para>
157 </question>
158 <answer>
159 <para>
160 The OpenEmbedded build system can build packages in various
161 formats such as IPK for OPKG, Debian package
162 (<filename>.deb</filename>), or RPM.
163 You can then upgrade the packages using the package tools on
164 the device, much like on a desktop distribution such as
165 Ubuntu or Fedora.
166 However, package management on the target is entirely optional.
167 </para>
168 </answer>
169 </qandaentry>
170
171 <qandaentry>
172 <question>
173 <para>
174 I see the error '<filename>chmod: XXXXX new permissions are r-xrwxrwx, not r-xr-xr-x</filename>'.
175 What is wrong?
176 </para>
177 </question>
178 <answer>
179 <para>
180 You are probably running the build on an NTFS filesystem.
181 Use <filename>ext2</filename>, <filename>ext3</filename>, or <filename>ext4</filename> instead.
182 </para>
183 </answer>
184 </qandaentry>
185
186<!-- <qandaentry>
187 <question>
188 <para>
189 How do I make the Yocto Project work in RHEL/CentOS?
190 </para>
191 </question>
192 <answer>
193 <para>
194 To get the Yocto Project working under RHEL/CentOS 5.1 you need to first
195 install some required packages.
196 The standard CentOS packages needed are:
197 <itemizedlist>
198 <listitem><para>"Development tools" (selected during installation)</para></listitem>
199 <listitem><para><filename>texi2html</filename></para></listitem>
200 <listitem><para><filename>compat-gcc-34</filename></para></listitem>
201 </itemizedlist>
202 On top of these, you need the following external packages:
203 <itemizedlist>
204 <listitem><para><filename>python-sqlite2</filename> from
205 <ulink url='http://dag.wieers.com/rpm/packages/python-sqlite2/'>DAG repository</ulink>
206 </para></listitem>
207 <listitem><para><filename>help2man</filename> from
208 <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>
209 </itemizedlist>
210 </para>
211
212 <para>
213 Once these packages are installed, the OpenEmbedded build system will be able
214 to build standard images.
215 However, there might be a problem with the QEMU emulator segfaulting.
216 You can either disable the generation of binary locales by setting
217 <filename><link linkend='var-ENABLE_BINARY_LOCALE_GENERATION'>ENABLE_BINARY_LOCALE_GENERATION</link>
218 </filename> to "0" or by removing the <filename>linux-2.6-execshield.patch</filename>
219 from the kernel and rebuilding it since that is the patch that causes the problems with QEMU.
220 </para>
221
222 <note>
223 <para>For information on distributions that the Yocto Project
224 uses during validation, see the
225 <ulink url='&YOCTO_WIKI_URL;/wiki/Distribution_Support'>Distribution Support</ulink>
226 Wiki page.</para>
227 <para>For notes about using the Yocto Project on a RHEL 4-based
228 host, see the
229 <ulink url='&YOCTO_WIKI_URL;/wiki/BuildingOnRHEL4'>Building on RHEL4</ulink>
230 Wiki page.</para>
231 </note>
232 </answer>
233 </qandaentry> -->
234
235 <qandaentry>
236 <question>
237 <para>
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500238 I see lots of 404 responses for files when the OpenEmbedded
239 build system is trying to download sources.
240 Is something wrong?
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500241 </para>
242 </question>
243 <answer>
244 <para>
245 Nothing is wrong.
246 The OpenEmbedded build system checks any configured source mirrors before downloading
247 from the upstream sources.
248 The build system does this searching for both source archives and
249 pre-checked out versions of SCM-managed software.
250 These checks help in large installations because it can reduce load on the SCM servers
251 themselves.
252 The address above is one of the default mirrors configured into the
253 build system.
254 Consequently, if an upstream source disappears, the team
255 can place sources there so builds continue to work.
256 </para>
257 </answer>
258 </qandaentry>
259
260 <qandaentry>
261 <question>
262 <para>
263 I have machine-specific data in a package for one machine only but the package is
264 being marked as machine-specific in all cases, how do I prevent this?
265 </para>
266 </question>
267 <answer>
268 <para>
269 Set <filename><link linkend='var-SRC_URI_OVERRIDES_PACKAGE_ARCH'>SRC_URI_OVERRIDES_PACKAGE_ARCH</link>
270 </filename> = "0" in the <filename>.bb</filename> file but make sure the package is
271 manually marked as
272 machine-specific for the case that needs it.
273 The code that handles
274 <filename>SRC_URI_OVERRIDES_PACKAGE_ARCH</filename> is in
275 the <filename>meta/classes/base.bbclass</filename> file.
276 </para>
277 </answer>
278 </qandaentry>
279
280 <qandaentry>
281 <question>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500282 <para id='i-am-behind-a-firewall-and-need-to-use-a-proxy-server'>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500283 I'm behind a firewall and need to use a proxy server. How do I do that?
284 </para>
285 </question>
286 <answer>
287 <para>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500288 Most source fetching by the OpenEmbedded build system is done
289 by <filename>wget</filename> and you therefore need to specify
290 the proxy settings in a <filename>.wgetrc</filename> file,
291 which can be in your home directory if you are a single user
292 or can be in <filename>/usr/local/etc/wgetrc</filename> as
293 a global user file.
294 </para>
295
296 <para>
297 Following is the applicable code for setting various proxy
298 types in the <filename>.wgetrc</filename> file.
299 By default, these settings are disabled with comments.
300 To use them, remove the comments:
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500301 <literallayout class='monospaced'>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500302 # You can set the default proxies for Wget to use for http, https, and ftp.
303 # They will override the value in the environment.
304 #https_proxy = http://proxy.yoyodyne.com:18023/
305 #http_proxy = http://proxy.yoyodyne.com:18023/
306 #ftp_proxy = http://proxy.yoyodyne.com:18023/
307
308 # If you do not want to use proxy at all, set this to off.
309 #use_proxy = on
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500310 </literallayout>
311 The Yocto Project also includes a
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500312 <filename>meta-poky/conf/site.conf.sample</filename> file that
313 shows how to configure CVS and Git proxy servers if needed.
314 For more information on setting up various proxy types and
315 configuring proxy servers, see the
316 "<ulink url='&YOCTO_WIKI_URL;/wiki/Working_Behind_a_Network_Proxy'>Working Behind a Network Proxy</ulink>"
317 Wiki page.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500318 </para>
319 </answer>
320 </qandaentry>
321
322 <qandaentry>
323 <question>
324 <para>
325 What’s the difference between <replaceable>target</replaceable> and <replaceable>target</replaceable><filename>-native</filename>?
326 </para>
327 </question>
328 <answer>
329 <para>
330 The <filename>*-native</filename> targets are designed to run on the system
331 being used for the build.
332 These are usually tools that are needed to assist the build in some way such as
333 <filename>quilt-native</filename>, which is used to apply patches.
334 The non-native version is the one that runs on the target device.
335 </para>
336 </answer>
337 </qandaentry>
338
339 <qandaentry>
340 <question>
341 <para>
342 I'm seeing random build failures. Help?!
343 </para>
344 </question>
345 <answer>
346 <para>
347 If the same build is failing in totally different and random
348 ways, the most likely explanation is:
349 <itemizedlist>
350 <listitem><para>The hardware you are running the build on
351 has some problem.</para></listitem>
352 <listitem><para>You are running the build under
353 virtualization, in which case the virtualization
354 probably has bugs.</para></listitem>
355 </itemizedlist>
356 The OpenEmbedded build system processes a massive amount of
357 data that causes lots of network, disk and CPU activity and
358 is sensitive to even single-bit failures in any of these areas.
359 True random failures have always been traced back to hardware
360 or virtualization issues.
361 </para>
362 </answer>
363 </qandaentry>
364
365 <qandaentry>
366 <question>
367 <para>
368 When I try to build a native recipe, the build fails with <filename>iconv.h</filename> problems.
369 </para>
370 </question>
371 <answer>
372 <para>
373 If you get an error message that indicates GNU
374 <filename>libiconv</filename> is not in use but
375 <filename>iconv.h</filename> has been included from
376 <filename>libiconv</filename>, you need to check to see if
377 you have a previously installed version of the header file
378 in <filename>/usr/local/include</filename>.
379 <literallayout class='monospaced'>
380 #error GNU libiconv not in use but included iconv.h is from libiconv
381 </literallayout>
382 If you find a previously installed file, you should either
383 uninstall it or temporarily rename it and try the build again.
384 </para>
385
386 <para>
387 This issue is just a single manifestation of "system
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500388 leakage" issues caused when the OpenEmbedded build system
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500389 finds and uses previously installed files during a native
390 build.
391 This type of issue might not be limited to
392 <filename>iconv.h</filename>.
393 Be sure that leakage cannot occur from
394 <filename>/usr/local/include</filename> and
395 <filename>/opt</filename> locations.
396 </para>
397 </answer>
398 </qandaentry>
399
400 <qandaentry>
401 <question>
402 <para>
403 What do we need to ship for license compliance?
404 </para>
405 </question>
406 <answer>
407 <para>
408 This is a difficult question and you need to consult your lawyer
409 for the answer for your specific case.
410 It is worth bearing in mind that for GPL compliance, there needs
411 to be enough information shipped to allow someone else to
412 rebuild and produce the same end result you are shipping.
413 This means sharing the source code, any patches applied to it,
414 and also any configuration information about how that package
415 was configured and built.
416 </para>
417
418 <para>
419 You can find more information on licensing in the
Brad Bishop316dfdd2018-06-25 12:45:53 -0400420 "<ulink url='&YOCTO_DOCS_OM_URL;#licensing'>Licensing</ulink>"
421 section in the Yocto Project Overview and Concepts Manual
422 and also in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500423 "<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>"
Brad Bishop316dfdd2018-06-25 12:45:53 -0400424 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500425 </para>
426 </answer>
427 </qandaentry>
428
429 <qandaentry>
430 <question>
431 <para>
432 How do I disable the cursor on my touchscreen device?
433 </para>
434 </question>
435 <answer>
436 <para>
437 You need to create a form factor file as described in the
438 "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-filelayout-misc-recipes'>Miscellaneous BSP-Specific Recipe Files</ulink>"
439 section in the Yocto Project Board Support Packages (BSP)
440 Developer's Guide.
441 Set the <filename>HAVE_TOUCHSCREEN</filename> variable equal to
442 one as follows:
443 <literallayout class='monospaced'>
444 HAVE_TOUCHSCREEN=1
445 </literallayout>
446 </para>
447 </answer>
448 </qandaentry>
449
450 <qandaentry>
451 <question>
452 <para>
453 How do I make sure connected network interfaces are brought up by default?
454 </para>
455 </question>
456 <answer>
457 <para>
458 The default interfaces file provided by the netbase recipe does not
459 automatically bring up network interfaces.
460 Therefore, you will need to add a BSP-specific netbase that includes an interfaces
461 file.
462 See the "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-filelayout-misc-recipes'>Miscellaneous BSP-Specific Recipe Files</ulink>"
463 section in the Yocto Project Board Support Packages (BSP)
464 Developer's Guide for information on creating these types of
465 miscellaneous recipe files.
466 </para>
467 <para>
468 For example, add the following files to your layer:
469 <literallayout class='monospaced'>
470 meta-MACHINE/recipes-bsp/netbase/netbase/MACHINE/interfaces
471 meta-MACHINE/recipes-bsp/netbase/netbase_5.0.bbappend
472 </literallayout>
473 </para>
474 </answer>
475 </qandaentry>
476
477 <qandaentry>
478 <question>
479 <para>
480 How do I create images with more free space?
481 </para>
482 </question>
483 <answer>
484 <para>
485 By default, the OpenEmbedded build system creates images
486 that are 1.3 times the size of the populated root filesystem.
487 To affect the image size, you need to set various
488 configurations:
489 <itemizedlist>
490 <listitem><para><emphasis>Image Size:</emphasis>
491 The OpenEmbedded build system uses the
492 <link linkend='var-IMAGE_ROOTFS_SIZE'><filename>IMAGE_ROOTFS_SIZE</filename></link>
493 variable to define the size of the image in Kbytes.
494 The build system determines the size by taking into
495 account the initial root filesystem size before any
496 modifications such as requested size for the image and
497 any requested additional free disk space to be
498 added to the image.</para></listitem>
499 <listitem><para><emphasis>Overhead:</emphasis>
500 Use the
501 <link linkend='var-IMAGE_OVERHEAD_FACTOR'><filename>IMAGE_OVERHEAD_FACTOR</filename></link>
502 variable to define the multiplier that the build system
503 applies to the initial image size, which is 1.3 by
504 default.</para></listitem>
505 <listitem><para><emphasis>Additional Free Space:</emphasis>
506 Use the
507 <link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'><filename>IMAGE_ROOTFS_EXTRA_SPACE</filename></link>
508 variable to add additional free space to the image.
509 The build system adds this space to the image after
510 it determines its
511 <filename>IMAGE_ROOTFS_SIZE</filename>.
512 </para></listitem>
513 </itemizedlist>
514 </para>
515 </answer>
516 </qandaentry>
517
518 <qandaentry>
519 <question>
520 <para>
521 Why don't you support directories with spaces in the pathnames?
522 </para>
523 </question>
524 <answer>
525 <para>
526 The Yocto Project team has tried to do this before but too
527 many of the tools the OpenEmbedded build system depends on,
528 such as <filename>autoconf</filename>, break when they find
529 spaces in pathnames.
530 Until that situation changes, the team will not support spaces
531 in pathnames.
532 </para>
533 </answer>
534 </qandaentry>
535
536 <qandaentry>
537 <question>
538 <para>
539 How do I use an external toolchain?
540 </para>
541 </question>
542 <answer>
543 <para>
544 The toolchain configuration is very flexible and customizable.
545 It is primarily controlled with the
546 <filename><link linkend='var-TCMODE'>TCMODE</link></filename>
547 variable.
548 This variable controls which <filename>tcmode-*.inc</filename>
549 file to include from the
550 <filename>meta/conf/distro/include</filename> directory within
551 the
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500552 <link linkend='source-directory'>Source Directory</link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500553 </para>
554
555 <para>
556 The default value of <filename>TCMODE</filename> is "default",
557 which tells the OpenEmbedded build system to use its internally
558 built toolchain (i.e. <filename>tcmode-default.inc</filename>).
559 However, other patterns are accepted.
560 In particular, "external-*" refers to external toolchains.
561 One example is the Sourcery G++ Toolchain.
562 The support for this toolchain resides in the separate
563 <filename>meta-sourcery</filename> layer at
564 <ulink url='http://github.com/MentorEmbedded/meta-sourcery/'></ulink>.
565 </para>
566
567 <para>
568 In addition to the toolchain configuration, you also need a
569 corresponding toolchain recipe file.
570 This recipe file needs to package up any pre-built objects in
571 the toolchain such as <filename>libgcc</filename>,
572 <filename>libstdcc++</filename>, any locales, and
573 <filename>libc</filename>.
574 </para>
575 </answer>
576 </qandaentry>
577
578 <qandaentry>
579 <question>
580 <para id='how-does-the-yocto-project-obtain-source-code-and-will-it-work-behind-my-firewall-or-proxy-server'>
581 How does the OpenEmbedded build system obtain source code and
582 will it work behind my firewall or proxy server?
583 </para>
584 </question>
585 <answer>
586 <para>
587 The way the build system obtains source code is highly
588 configurable.
589 You can setup the build system to get source code in most
590 environments if HTTP transport is available.
591 </para>
592 <para>
593 When the build system searches for source code, it first
594 tries the local download directory.
595 If that location fails, Poky tries
596 <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>,
597 the upstream source, and then
598 <link linkend='var-MIRRORS'><filename>MIRRORS</filename></link>
599 in that order.
600 </para>
601 <para>
602 Assuming your distribution is "poky", the OpenEmbedded build
603 system uses the Yocto Project source
604 <filename>PREMIRRORS</filename> by default for SCM-based
605 sources, upstreams for normal tarballs, and then falls back
606 to a number of other mirrors including the Yocto Project
607 source mirror if those fail.
608 </para>
609 <para>
610 As an example, you could add a specific server for the
611 build system to attempt before any others by adding something
612 like the following to the <filename>local.conf</filename>
613 configuration file:
614 <literallayout class='monospaced'>
615 PREMIRRORS_prepend = "\
616 git://.*/.* http://www.yoctoproject.org/sources/ \n \
617 ftp://.*/.* http://www.yoctoproject.org/sources/ \n \
618 http://.*/.* http://www.yoctoproject.org/sources/ \n \
619 https://.*/.* http://www.yoctoproject.org/sources/ \n"
620 </literallayout>
621 </para>
622 <para>
623 These changes cause the build system to intercept Git, FTP,
624 HTTP, and HTTPS requests and direct them to the
625 <filename>http://</filename> sources mirror.
626 You can use <filename>file://</filename> URLs to point to
627 local directories or network shares as well.
628 </para>
629 <para>
630 Aside from the previous technique, these options also exist:
631 <literallayout class='monospaced'>
632 BB_NO_NETWORK = "1"
633 </literallayout>
634 This statement tells BitBake to issue an error instead of
635 trying to access the Internet.
636 This technique is useful if you want to ensure code builds
637 only from local sources.
638 </para>
639 <para>
640 Here is another technique:
641 <literallayout class='monospaced'>
642 BB_FETCH_PREMIRRORONLY = "1"
643 </literallayout>
644 This statement limits the build system to pulling source
645 from the <filename>PREMIRRORS</filename> only.
646 Again, this technique is useful for reproducing builds.
647 </para>
648 <para>
649 Here is another technique:
650 <literallayout class='monospaced'>
651 BB_GENERATE_MIRROR_TARBALLS = "1"
652 </literallayout>
653 This statement tells the build system to generate mirror
654 tarballs.
655 This technique is useful if you want to create a mirror server.
656 If not, however, the technique can simply waste time during
657 the build.
658 </para>
659 <para>
660 Finally, consider an example where you are behind an
661 HTTP-only firewall.
662 You could make the following changes to the
663 <filename>local.conf</filename> configuration file as long as
664 the <filename>PREMIRRORS</filename> server is current:
665 <literallayout class='monospaced'>
666 PREMIRRORS_prepend = "\
667 ftp://.*/.* http://www.yoctoproject.org/sources/ \n \
668 http://.*/.* http://www.yoctoproject.org/sources/ \n \
669 https://.*/.* http://www.yoctoproject.org/sources/ \n"
670 BB_FETCH_PREMIRRORONLY = "1"
671 </literallayout>
672 These changes would cause the build system to successfully
673 fetch source over HTTP and any network accesses to anything
674 other than the <filename>PREMIRRORS</filename> would fail.
675 </para>
676 <para>
677 The build system also honors the standard shell environment
678 variables <filename>http_proxy</filename>,
679 <filename>ftp_proxy</filename>,
680 <filename>https_proxy</filename>, and
681 <filename>all_proxy</filename> to redirect requests through
682 proxy servers.
683 </para>
684 <note>
685 You can find more information on the
686 "<ulink url='&YOCTO_WIKI_URL;/wiki/Working_Behind_a_Network_Proxy'>Working Behind a Network Proxy</ulink>"
687 Wiki page.
688 </note>
689 </answer>
690 </qandaentry>
691
692 <qandaentry>
693 <question>
694 <para>
695 Can I get rid of build output so I can start over?
696 </para>
697 </question>
698 <answer>
699 <para>
700 Yes - you can easily do this.
701 When you use BitBake to build an image, all the build output
702 goes into the directory created when you run the
703 build environment setup script (i.e.
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500704 <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>).
705 By default, this
706 <link linkend='build-directory'>Build Directory</link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500707 is named <filename>build</filename> but can be named
708 anything you want.
709 </para>
710
711 <para>
712 Within the Build Directory, is the <filename>tmp</filename>
713 directory.
714 To remove all the build output yet preserve any source code or
715 downloaded files from previous builds, simply remove the
716 <filename>tmp</filename> directory.
717 </para>
718 </answer>
719 </qandaentry>
720
721 <qandaentry>
722 <question>
723 <para>
724 Why do <filename>${bindir}</filename> and <filename>${libdir}</filename> have strange values for <filename>-native</filename> recipes?
725 </para>
726 </question>
727 <answer>
728 <para>
729 Executables and libraries might need to be used from a
730 directory other than the directory into which they were
731 initially installed.
732 Complicating this situation is the fact that sometimes these
733 executables and libraries are compiled with the expectation
734 of being run from that initial installation target directory.
735 If this is the case, moving them causes problems.
736 </para>
737
738 <para>
739 This scenario is a fundamental problem for package maintainers
740 of mainstream Linux distributions as well as for the
741 OpenEmbedded build system.
742 As such, a well-established solution exists.
743 Makefiles, Autotools configuration scripts, and other build
744 systems are expected to respect environment variables such as
745 <filename>bindir</filename>, <filename>libdir</filename>,
746 and <filename>sysconfdir</filename> that indicate where
747 executables, libraries, and data reside when a program is
748 actually run.
749 They are also expected to respect a
750 <filename>DESTDIR</filename> environment variable, which is
751 prepended to all the other variables when the build system
752 actually installs the files.
753 It is understood that the program does not actually run from
754 within <filename>DESTDIR</filename>.
755 </para>
756
757 <para>
758 When the OpenEmbedded build system uses a recipe to build a
759 target-architecture program (i.e. one that is intended for
760 inclusion on the image being built), that program eventually
761 runs from the root file system of that image.
762 Thus, the build system provides a value of "/usr/bin" for
763 <filename>bindir</filename>, a value of "/usr/lib" for
764 <filename>libdir</filename>, and so forth.
765 </para>
766
767 <para>
768 Meanwhile, <filename>DESTDIR</filename> is a path within the
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500769 <link linkend='build-directory'>Build Directory</link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500770 However, when the recipe builds a native program (i.e. one
771 that is intended to run on the build machine), that program
772 is never installed directly to the build machine's root
773 file system.
774 Consequently, the build system uses paths within the Build
775 Directory for <filename>DESTDIR</filename>,
776 <filename>bindir</filename> and related variables.
777 To better understand this, consider the following two paths
778 where the first is relatively normal and the second is not:
779 <note>
780 Due to these lengthy examples, the paths are artificially
781 broken across lines for readability.
782 </note>
783 <literallayout class='monospaced'>
784 /home/maxtothemax/poky-bootchart2/build/tmp/work/i586-poky-linux/zlib/
785 1.2.8-r0/sysroot-destdir/usr/bin
786
787 /home/maxtothemax/poky-bootchart2/build/tmp/work/x86_64-linux/
788 zlib-native/1.2.8-r0/sysroot-destdir/home/maxtothemax/poky-bootchart2/
789 build/tmp/sysroots/x86_64-linux/usr/bin
790 </literallayout>
791 Even if the paths look unusual, they both are correct -
792 the first for a target and the second for a native recipe.
793 These paths are a consequence of the
794 <filename>DESTDIR</filename> mechanism and while they
795 appear strange, they are correct and in practice very effective.
796 </para>
797 </answer>
798 </qandaentry>
799
800 <qandaentry>
801 <question>
802 <para>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500803 The files provided by my <filename>*-native</filename> recipe do
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500804 not appear to be available to other recipes.
805 Files are missing from the native sysroot, my recipe is
806 installing to the wrong place, or I am getting permissions
807 errors during the do_install task in my recipe! What is wrong?
808 </para>
809 </question>
810 <answer>
811 <para>
812 This situation results when a build system does
813 not recognize the environment variables supplied to it by
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500814 <link linkend='bitbake-term'>BitBake</link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500815 The incident that prompted this FAQ entry involved a Makefile
816 that used an environment variable named
817 <filename>BINDIR</filename> instead of the more standard
818 variable <filename>bindir</filename>.
819 The makefile's hardcoded default value of "/usr/bin" worked
820 most of the time, but not for the recipe's
821 <filename>-native</filename> variant.
822 For another example, permissions errors might be caused
823 by a Makefile that ignores <filename>DESTDIR</filename> or uses
824 a different name for that environment variable.
825 Check the the build system to see if these kinds of
826 issues exist.
827 </para>
828 </answer>
829 </qandaentry>
830
831</qandaset>
832</chapter>
833<!--
834vim: expandtab tw=80 ts=4
835-->