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