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.xml606
1 files changed, 606 insertions, 0 deletions
diff --git a/documentation/ref-manual/faq.xml b/documentation/ref-manual/faq.xml
new file mode 100644
index 0000000000..176573de28
--- /dev/null
+++ b/documentation/ref-manual/faq.xml
@@ -0,0 +1,606 @@
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 "Poky" refers to the specific reference build system that
17 the Yocto Project provides.
18 Poky is based on <ulink url='&YOCTO_DOCS_DEV_URL;#oe-core'>OE-Core</ulink>
19 and BitBake.
20 Thus, the generic term used here for the build system is
21 the "OpenEmbedded build system."
22 Development in the Yocto Project using Poky is closely tied to OpenEmbedded, with
23 changes always being merged to OE-Core or BitBake first before being pulled back
24 into Poky.
25 This practice benefits both projects immediately.
26 For a fuller description of the term "Poky", see the
27 <ulink url='&YOCTO_DOCS_DEV_URL;#poky'>poky</ulink> term in the Yocto Project
28 Development Manual.
29 </para>
30 </answer>
31 </qandaentry>
32
33 <qandaentry>
34 <question>
35 <para>
36 I only have Python 2.4 or 2.5 but BitBake requires Python 2.6 or 2.7.
37 Can I still use the Yocto Project?
38 </para>
39 </question>
40 <answer>
41 <para>
42 You can use a stand-alone tarball to provide Python 2.6.
43 You can find pre-built 32 and 64-bit versions of Python 2.6 at the following locations:
44 <itemizedlist>
45 <listitem><para><ulink url='&YOCTO_PYTHON-i686_DL_URL;'>32-bit tarball</ulink></para></listitem>
46 <listitem><para><ulink url='&YOCTO_PYTHON-x86_64_DL_URL;'>64-bit tarball</ulink></para></listitem>
47 </itemizedlist>
48 </para>
49 <para>
50 These tarballs are self-contained with all required libraries and should work
51 on most Linux systems.
52 To use the tarballs extract them into the root
53 directory and run the appropriate command:
54 <literallayout class='monospaced'>
55 $ export PATH=/opt/poky/sysroots/i586-pokysdk-linux/usr/bin/:$PATH
56 $ export PATH=/opt/poky/sysroots/x86_64-pokysdk-linux/usr/bin/:$PATH
57 </literallayout>
58 </para>
59 <para>
60 Once you run the command, BitBake uses Python 2.6.
61 </para>
62 </answer>
63 </qandaentry>
64
65 <qandaentry>
66 <question>
67 <para>
68 How can you claim Poky / OpenEmbedded-Core is stable?
69 </para>
70 </question>
71 <answer>
72 <para>
73 There are three areas that help with stability;
74 <itemizedlist>
75 <listitem><para>The Yocto Project team keeps
76 <ulink url='&YOCTO_DOCS_DEV_URL;#oe-core'>OE-Core</ulink> small
77 and focused, containing around 830 recipes as opposed to the thousands
78 available in other OpenEmbedded community layers.
79 Keeping it small makes it easy to test and maintain.</para></listitem>
80 <listitem><para>The Yocto Project team runs manual and automated tests
81 using a small, fixed set of reference hardware as well as emulated
82 targets.</para></listitem>
83 <listitem><para>The Yocto Project uses an an autobuilder,
84 which provides continuous build and integration tests.</para></listitem>
85 </itemizedlist>
86 </para>
87 </answer>
88 </qandaentry>
89
90 <qandaentry>
91 <question>
92 <para>
93 How do I get support for my board added to the Yocto Project?
94 </para>
95 </question>
96 <answer>
97 <para>
98 Support for an additional board is added by creating a BSP layer for it.
99 For more information on how to create a BSP layer, see the
100 <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>.
101 </para>
102 <para>
103 Usually, if the board is not completely exotic, adding support in
104 the Yocto Project is fairly straightforward.
105 </para>
106 </answer>
107 </qandaentry>
108
109 <qandaentry>
110 <question>
111 <para>
112 Are there any products built using the OpenEmbedded build system?
113 </para>
114 </question>
115 <answer>
116 <para>
117 The software running on the <ulink url='http://vernier.com/labquest/'>Vernier LabQuest</ulink>
118 is built using the OpenEmbedded build system.
119 See the <ulink url='http://www.vernier.com/products/interfaces/labq/'>Vernier LabQuest</ulink>
120 website for more information.
121 There are a number of pre-production devices using the OpenEmbedded build system
122 and the Yocto Project team
123 announces them as soon as they are released.
124 </para>
125 </answer>
126 </qandaentry>
127
128 <qandaentry>
129 <question>
130 <para>
131 What does the OpenEmbedded build system produce as output?
132 </para>
133 </question>
134 <answer>
135 <para>
136 Because the same set of recipes can be used to create output of various formats, the
137 output of an OpenEmbedded build depends on how it was started.
138 Usually, the output is a flashable image ready for the target device.
139 </para>
140 </answer>
141 </qandaentry>
142
143 <qandaentry>
144 <question>
145 <para>
146 How do I add my package to the Yocto Project?
147 </para>
148 </question>
149 <answer>
150 <para>
151 To add a package, you need to create a BitBake recipe.
152 For information on how to add a package, see the section
153 "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-extend-addpkg'>Adding a Package</ulink>"
154 in the Yocto Project Development Manual.
155 </para>
156 </answer>
157 </qandaentry>
158
159 <qandaentry>
160 <question>
161 <para>
162 Do I have to reflash my entire board with a new Yocto Project image when recompiling
163 a package?
164 </para>
165 </question>
166 <answer>
167 <para>
168 The OpenEmbedded build system can build packages in various formats such as
169 <filename>ipk</filename> for <filename>opkg</filename>,
170 Debian package (<filename>.deb</filename>), or RPM.
171 The packages can then be upgraded using the package tools on the device, much like
172 on a desktop distribution such as Ubuntu or Fedora.
173 </para>
174 </answer>
175 </qandaentry>
176
177 <qandaentry>
178 <question>
179 <para>
180 What is GNOME Mobile and what is the difference between GNOME Mobile and GNOME?
181 </para>
182 </question>
183 <answer>
184 <para>
185 GNOME Mobile is a subset of the <ulink url='http://www.gnome.org'>GNOME</ulink>
186 platform targeted at mobile and embedded devices.
187 The the main difference between GNOME Mobile and standard GNOME is that
188 desktop-orientated libraries have been removed, along with deprecated libraries,
189 creating a much smaller footprint.
190 </para>
191 </answer>
192 </qandaentry>
193
194 <qandaentry>
195 <question>
196 <para>
197 I see the error '<filename>chmod: XXXXX new permissions are r-xrwxrwx, not r-xr-xr-x</filename>'.
198 What is wrong?
199 </para>
200 </question>
201 <answer>
202 <para>
203 You are probably running the build on an NTFS filesystem.
204 Use <filename>ext2</filename>, <filename>ext3</filename>, or <filename>ext4</filename> instead.
205 </para>
206 </answer>
207 </qandaentry>
208
209 <qandaentry>
210 <question>
211 <para>
212 How do I make the Yocto Project work in RHEL/CentOS?
213 </para>
214 </question>
215 <answer>
216 <para>
217 To get the Yocto Project working under RHEL/CentOS 5.1 you need to first
218 install some required packages.
219 The standard CentOS packages needed are:
220 <itemizedlist>
221 <listitem><para>"Development tools" (selected during installation)</para></listitem>
222 <listitem><para><filename>texi2html</filename></para></listitem>
223 <listitem><para><filename>compat-gcc-34</filename></para></listitem>
224 </itemizedlist>
225 On top of these, you need the following external packages:
226 <itemizedlist>
227 <listitem><para><filename>python-sqlite2</filename> from
228 <ulink url='http://dag.wieers.com/rpm/packages/python-sqlite2/'>DAG repository</ulink>
229 </para></listitem>
230 <listitem><para><filename>help2man</filename> from
231 <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>
232 </itemizedlist>
233 </para>
234
235 <para>
236 Once these packages are installed, the OpenEmbedded build system will be able
237 to build standard images.
238 However, there might be a problem with the QEMU emulator segfaulting.
239 You can either disable the generation of binary locales by setting
240 <filename><link linkend='var-ENABLE_BINARY_LOCALE_GENERATION'>ENABLE_BINARY_LOCALE_GENERATION</link>
241 </filename> to "0" or by removing the <filename>linux-2.6-execshield.patch</filename>
242 from the kernel and rebuilding it since that is the patch that causes the problems with QEMU.
243 </para>
244 </answer>
245 </qandaentry>
246
247 <qandaentry>
248 <question>
249 <para>
250 I see lots of 404 responses for files on
251 <filename>http://www.yoctoproject.org/sources/*</filename>. Is something wrong?
252 </para>
253 </question>
254 <answer>
255 <para>
256 Nothing is wrong.
257 The OpenEmbedded build system checks any configured source mirrors before downloading
258 from the upstream sources.
259 The build system does this searching for both source archives and
260 pre-checked out versions of SCM managed software.
261 These checks help in large installations because it can reduce load on the SCM servers
262 themselves.
263 The address above is one of the default mirrors configured into the
264 build system.
265 Consequently, if an upstream source disappears, the team
266 can place sources there so builds continue to work.
267 </para>
268 </answer>
269 </qandaentry>
270
271 <qandaentry>
272 <question>
273 <para>
274 I have machine-specific data in a package for one machine only but the package is
275 being marked as machine-specific in all cases, how do I prevent this?
276 </para>
277 </question>
278 <answer>
279 <para>
280 Set <filename><link linkend='var-SRC_URI_OVERRIDES_PACKAGE_ARCH'>SRC_URI_OVERRIDES_PACKAGE_ARCH</link>
281 </filename> = "0" in the <filename>.bb</filename> file but make sure the package is
282 manually marked as
283 machine-specific in the case that needs it.
284 The code that handles <filename>SRC_URI_OVERRIDES_PACKAGE_ARCH</filename> is in <filename>base.bbclass</filename>.
285 </para>
286 </answer>
287 </qandaentry>
288
289 <qandaentry>
290 <question>
291 <para>
292 I'm behind a firewall and need to use a proxy server. How do I do that?
293 </para>
294 </question>
295 <answer>
296 <para>
297 Most source fetching by the OpenEmbedded build system is done by <filename>wget</filename>
298 and you therefore need to specify the proxy settings in a
299 <filename>.wgetrc</filename> file in your home directory.
300 Example settings in that file would be
301 <literallayout class='monospaced'>
302 http_proxy = http://proxy.yoyodyne.com:18023/
303 ftp_proxy = http://proxy.yoyodyne.com:18023/
304 </literallayout>
305 The Yocto Project also includes a <filename>site.conf.sample</filename>
306 file that shows how to configure CVS and Git proxy servers
307 if needed.
308 </para>
309 </answer>
310 </qandaentry>
311
312 <qandaentry>
313 <question>
314 <para>
315 What’s the difference between <filename>foo</filename> and <filename>foo-native</filename>?
316 </para>
317 </question>
318 <answer>
319 <para>
320 The <filename>*-native</filename> targets are designed to run on the system
321 being used for the build.
322 These are usually tools that are needed to assist the build in some way such as
323 <filename>quilt-native</filename>, which is used to apply patches.
324 The non-native version is the one that runs on the target device.
325 </para>
326 </answer>
327 </qandaentry>
328
329 <qandaentry>
330 <question>
331 <para>
332 I'm seeing random build failures. Help?!
333 </para>
334 </question>
335 <answer>
336 <para>
337 If the same build is failing in totally different and random ways,
338 the most likely explanation is that either the hardware you're running the
339 build on has some problem, or, if you are running the build under virtualisation,
340 the virtualisation probably has bugs.
341 The OpenEmbedded build system processes a massive amount of data causing lots of network, disk and
342 CPU activity and is sensitive to even single bit failures in any of these areas.
343 True random failures have always been traced back to hardware or virtualisation issues.
344 </para>
345 </answer>
346 </qandaentry>
347
348 <qandaentry>
349 <question>
350 <para>
351 What do we need to ship for license compliance?
352 </para>
353 </question>
354 <answer>
355 <para>
356 This is a difficult question and you need to consult your lawyer for the answer
357 for your specific case.
358 It is worth bearing in mind that for GPL compliance there needs to be enough
359 information shipped to allow someone else to rebuild the same end result
360 you are shipping.
361 This means sharing the source code, any patches applied to it, and also any
362 configuration information about how that package was configured and built.
363 </para>
364 </answer>
365 </qandaentry>
366
367 <qandaentry>
368 <question>
369 <para>
370 How do I disable the cursor on my touchscreen device?
371 </para>
372 </question>
373 <answer>
374 <para>
375 You need to create a form factor file as described in the
376 "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-filelayout-misc-recipes'>Miscellaneous Recipe Files</ulink>"
377 section and set the <filename>HAVE_TOUCHSCREEN</filename> variable equal to one as follows:
378 <literallayout class='monospaced'>
379 HAVE_TOUCHSCREEN=1
380 </literallayout>
381 </para>
382 </answer>
383 </qandaentry>
384
385 <qandaentry>
386 <question>
387 <para>
388 How do I make sure connected network interfaces are brought up by default?
389 </para>
390 </question>
391 <answer>
392 <para>
393 The default interfaces file provided by the netbase recipe does not
394 automatically bring up network interfaces.
395 Therefore, you will need to add a BSP-specific netbase that includes an interfaces
396 file.
397 See the "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-filelayout-misc-recipes'>Miscellaneous Recipe Files</ulink>"
398 section for information on creating these types of miscellaneous recipe files.
399 </para>
400 <para>
401 For example, add the following files to your layer:
402 <literallayout class='monospaced'>
403 meta-MACHINE/recipes-bsp/netbase/netbase/MACHINE/interfaces
404 meta-MACHINE/recipes-bsp/netbase/netbase_5.0.bbappend
405 </literallayout>
406 </para>
407 </answer>
408 </qandaentry>
409
410 <qandaentry>
411 <question>
412 <para>
413 How do I create images with more free space?
414 </para>
415 </question>
416 <answer>
417 <para>
418 Images are created to be 1.2 times the size of the populated root filesystem.
419 To modify this ratio so that there is more free space available, you need to
420 set the configuration value <filename>IMAGE_OVERHEAD_FACTOR</filename>.
421 For example, setting <filename>IMAGE_OVERHEAD_FACTOR</filename> to 1.5 sets
422 the image size ratio to one and a half times the size of the populated
423 root filesystem.
424 <literallayout class='monospaced'>
425 IMAGE_OVERHEAD_FACTOR = "1.5"
426 </literallayout>
427 </para>
428 </answer>
429 </qandaentry>
430
431 <qandaentry>
432 <question>
433 <para>
434 Why don't you support directories with spaces in the pathnames?
435 </para>
436 </question>
437 <answer>
438 <para>
439 The Yocto Project team has tried to do this before but too many of the tools
440 the OpenEmbedded build system depends on such as <filename>autoconf</filename>
441 break when they find spaces in pathnames.
442 Until that situation changes, the team will not support spaces in pathnames.
443 </para>
444 </answer>
445 </qandaentry>
446
447 <qandaentry>
448 <question>
449 <para>
450 How do I use an external toolchain?
451 </para>
452 </question>
453 <answer>
454 <para>
455 The toolchain configuration is very flexible and customizable.
456 It is primarily controlled with the
457 <filename><link linkend='var-TCMODE'>TCMODE</link></filename> variable.
458 This variable controls which <filename>tcmode-*.inc</filename> file to include
459 from the <filename>meta/conf/distro/include</filename> directory within the
460 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>source directory</ulink>.
461 </para>
462
463 <para>
464 The default value of <filename>TCMODE</filename> is "default"
465 (i.e. <filename>tcmode-default.inc</filename>).
466 However, other patterns are accepted.
467 In particular, "external-*" refers to external toolchains of which there are some
468 basic examples included in the OpenEmbedded Core (<filename>meta</filename>).
469 You can use your own custom toolchain definition in your own layer
470 (or as defined in the <filename>local.conf</filename> file) at the location
471 <filename>conf/distro/include/tcmode-*.inc</filename>.
472 </para>
473
474 <para>
475 In addition to the toolchain configuration, you also need a corresponding toolchain recipe file.
476 This recipe file needs to package up any pre-built objects in the toolchain such as
477 <filename>libgcc</filename>, <filename>libstdcc++</filename>,
478 any locales, and <filename>libc</filename>.
479 An example is the <filename>external-sourcery-toolchain.bb</filename>, which is located
480 in <filename>meta/recipes-core/meta/</filename> within the source directory.
481 </para>
482 </answer>
483 </qandaentry>
484
485 <qandaentry>
486 <question>
487 <para id='how-does-the-yocto-project-obtain-source-code-and-will-it-work-behind-my-firewall-or-proxy-server'>
488 How does the OpenEmbedded build system obtain source code and will it work behind my
489 firewall or proxy server?
490 </para>
491 </question>
492 <answer>
493 <para>
494 The way the build system obtains source code is highly configurable.
495 You can setup the build system to get source code in most environments if
496 HTTP transport is available.
497 </para>
498 <para>
499 When the build system searches for source code, it first tries the local download directory.
500 If that location fails, Poky tries PREMIRRORS, the upstream source,
501 and then MIRRORS in that order.
502 </para>
503 <para>
504 By default, the OpenEmbedded build system uses the Yocto Project source PREMIRRORS
505 for SCM-based sources,
506 upstreams for normal tarballs, and then falls back to a number of other mirrors
507 including the Yocto Project source mirror if those fail.
508 </para>
509 <para>
510 As an example, you could add a specific server for Poky to attempt before any
511 others by adding something like the following to the <filename>local.conf</filename>
512 configuration file:
513 <literallayout class='monospaced'>
514 PREMIRRORS_prepend = "\
515 git://.*/.* http://www.yoctoproject.org/sources/ \n \
516 ftp://.*/.* http://www.yoctoproject.org/sources/ \n \
517 http://.*/.* http://www.yoctoproject.org/sources/ \n \
518 https://.*/.* http://www.yoctoproject.org/sources/ \n"
519 </literallayout>
520 </para>
521 <para>
522 These changes cause Poky to intercept Git, FTP, HTTP, and HTTPS
523 requests and direct them to the <filename>http://</filename> sources mirror.
524 You can use <filename>file://</filename> URLs to point to local directories
525 or network shares as well.
526 </para>
527 <para>
528 Aside from the previous technique, these options also exist:
529 <literallayout class='monospaced'>
530 BB_NO_NETWORK = "1"
531 </literallayout>
532 This statement tells BitBake to throw an error instead of trying to access the
533 Internet.
534 This technique is useful if you want to ensure code builds only from local sources.
535 </para>
536 <para>
537 Here is another technique:
538 <literallayout class='monospaced'>
539 BB_FETCH_PREMIRRORONLY = "1"
540 </literallayout>
541 This statement limits Poky to pulling source from the PREMIRRORS only.
542 Again, this technique is useful for reproducing builds.
543 </para>
544 <para>
545 Here is another technique:
546 <literallayout class='monospaced'>
547 BB_GENERATE_MIRROR_TARBALLS = "1"
548 </literallayout>
549 This statement tells Poky to generate mirror tarballs.
550 This technique is useful if you want to create a mirror server.
551 If not, however, the technique can simply waste time during the build.
552 </para>
553 <para>
554 Finally, consider an example where you are behind an HTTP-only firewall.
555 You could make the following changes to the <filename>local.conf</filename>
556 configuration file as long as the PREMIRROR server is up to date:
557 <literallayout class='monospaced'>
558 PREMIRRORS_prepend = "\
559 ftp://.*/.* http://www.yoctoproject.org/sources/ \n \
560 http://.*/.* http://www.yoctoproject.org/sources/ \n \
561 https://.*/.* http://www.yoctoproject.org/sources/ \n"
562 BB_FETCH_PREMIRRORONLY = "1"
563 </literallayout>
564 These changes would cause Poky to successfully fetch source over HTTP and
565 any network accesses to anything other than the PREMIRROR would fail.
566 </para>
567 <para>
568 The build system also honors the standard shell environment variables
569 <filename>http_proxy</filename>, <filename>ftp_proxy</filename>,
570 <filename>https_proxy</filename>, and <filename>all_proxy</filename>
571 to redirect requests through proxy servers.
572 </para>
573 </answer>
574 </qandaentry>
575
576 <qandaentry>
577 <question>
578 <para>
579 Can I get rid of build output so I can start over?
580 </para>
581 </question>
582 <answer>
583 <para>
584 Yes - you can easily do this.
585 When you use BitBake to build an image, all the build output goes into the
586 directory created when you source the <filename>oe-init-build-env</filename>
587 setup file.
588 By default, this <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>build directory</ulink>
589 is named <filename>build</filename> but can be named
590 anything you want.
591 </para>
592
593 <para>
594 Within the build directory is the <filename>tmp</filename> directory.
595 To remove all the build output yet preserve any source code or downloaded files
596 from previous builds, simply remove the <filename>tmp</filename> directory.
597 </para>
598 </answer>
599 </qandaentry>
600
601
602</qandaset>
603</chapter>
604<!--
605vim: expandtab tw=80 ts=4
606-->
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-11-14 11:13:41 +0000