diff options
Diffstat (limited to 'documentation/ref-manual/faq.xml')
-rw-r--r-- | documentation/ref-manual/faq.xml | 836 |
1 files changed, 0 insertions, 836 deletions
diff --git a/documentation/ref-manual/faq.xml b/documentation/ref-manual/faq.xml deleted file mode 100644 index 2f8fcf3242..0000000000 --- a/documentation/ref-manual/faq.xml +++ /dev/null | |||
@@ -1,836 +0,0 @@ | |||
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 | <!--SPDX-License-Identifier: CC-BY-2.0-UK--> | ||
5 | |||
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> | ||
17 | The term "<link link='poky'>Poky</link>" | ||
18 | refers to the specific reference build system that | ||
19 | the Yocto Project provides. | ||
20 | Poky is based on <link linkend='oe-core'>OE-Core</link> | ||
21 | and <link linkend='bitbake-term'>BitBake</link>. | ||
22 | 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. | ||
37 | In particular, I do not have Python 3.5.0 or greater. | ||
38 | 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 | ||
47 | "<link linkend='required-git-tar-python-and-gcc-versions'>Required Git, tar, Python and gcc Versions</link>" | ||
48 | 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 | ||
64 | <link linkend='oe-core'>OE-Core</link> small | ||
65 | 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>" | ||
90 | section in the Yocto Project Development Tasks Manual and the | ||
91 | <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>" | ||
147 | section in the Yocto Project Development Tasks Manual. | ||
148 | </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> | ||
239 | I see lots of 404 responses for files when the OpenEmbedded | ||
240 | build system is trying to download sources. | ||
241 | Is something wrong? | ||
242 | </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> | ||
283 | <para id='i-am-behind-a-firewall-and-need-to-use-a-proxy-server'> | ||
284 | 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> | ||
289 | 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: | ||
302 | <literallayout class='monospaced'> | ||
303 | # 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 | ||
311 | </literallayout> | ||
312 | The Yocto Project also includes a | ||
313 | <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. | ||
319 | </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 | ||
389 | leakage" issues caused when the OpenEmbedded build system | ||
390 | 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 | ||
421 | "<ulink url='&YOCTO_DOCS_OM_URL;#licensing'>Licensing</ulink>" | ||
422 | section in the Yocto Project Overview and Concepts Manual | ||
423 | and also in the | ||
424 | "<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>" | ||
425 | section in the Yocto Project Development Tasks Manual. | ||
426 | </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 | ||
553 | <link linkend='source-directory'>Source Directory</link>. | ||
554 | </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. | ||
705 | <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>). | ||
706 | By default, this | ||
707 | <link linkend='build-directory'>Build Directory</link> | ||
708 | 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 | ||
770 | <link linkend='build-directory'>Build Directory</link>. | ||
771 | 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> | ||
804 | The files provided by my <filename>*-native</filename> recipe do | ||
805 | 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 | ||
815 | <link linkend='bitbake-term'>BitBake</link>. | ||
816 | 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 | <!-- | ||
835 | vim: expandtab tw=80 ts=4 | ||
836 | --> | ||