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