diff options
Diffstat (limited to 'documentation/ref-manual/faq.rst')
-rw-r--r-- | documentation/ref-manual/faq.rst | 451 |
1 files changed, 451 insertions, 0 deletions
diff --git a/documentation/ref-manual/faq.rst b/documentation/ref-manual/faq.rst new file mode 100644 index 0000000000..2d2aaad0a9 --- /dev/null +++ b/documentation/ref-manual/faq.rst | |||
@@ -0,0 +1,451 @@ | |||
1 | .. SPDX-License-Identifier: CC-BY-2.0-UK | ||
2 | |||
3 | *** | ||
4 | FAQ | ||
5 | *** | ||
6 | |||
7 | **Q:** How does Poky differ from `OpenEmbedded <http://www.openembedded.org/>`__? | ||
8 | |||
9 | **A:** The term ``Poky`` refers to the specific reference build | ||
10 | system that the Yocto Project provides. Poky is based on | ||
11 | :term:`OpenEmbedded-Core (OE-Core)` and :term:`BitBake`. Thus, the | ||
12 | generic term used here for the build system is the "OpenEmbedded build | ||
13 | system." Development in the Yocto Project using Poky is closely tied to | ||
14 | OpenEmbedded, with changes always being merged to OE-Core or BitBake | ||
15 | first before being pulled back into Poky. This practice benefits both | ||
16 | projects immediately. | ||
17 | |||
18 | **Q:** My development system does not meet the required Git, tar, and | ||
19 | Python versions. In particular, I do not have Python 3.5.0 or greater. | ||
20 | Can I still use the Yocto Project? | ||
21 | |||
22 | **A:** You can get the required tools on your host development system a | ||
23 | couple different ways (i.e. building a tarball or downloading a | ||
24 | tarball). See the "`Required Git, tar, Python and gcc | ||
25 | Versions <#required-git-tar-python-and-gcc-versions>`__" section for | ||
26 | steps on how to update your build tools. | ||
27 | |||
28 | **Q:** How can you claim Poky / OpenEmbedded-Core is stable? | ||
29 | |||
30 | **A:** There are three areas that help with stability; | ||
31 | |||
32 | - The Yocto Project team keeps :term:`OpenEmbedded-Core (OE-Core)` small and | ||
33 | focused, containing around 830 recipes as opposed to the thousands | ||
34 | available in other OpenEmbedded community layers. Keeping it small | ||
35 | makes it easy to test and maintain. | ||
36 | |||
37 | - The Yocto Project team runs manual and automated tests using a small, | ||
38 | fixed set of reference hardware as well as emulated targets. | ||
39 | |||
40 | - The Yocto Project uses an autobuilder, which provides continuous | ||
41 | build and integration tests. | ||
42 | |||
43 | **Q:** How do I get support for my board added to the Yocto Project? | ||
44 | |||
45 | **A:** Support for an additional board is added by creating a Board | ||
46 | Support Package (BSP) layer for it. For more information on how to | ||
47 | create a BSP layer, see the | ||
48 | ":ref:`dev-manual/dev-manual-common-tasks:understanding and creating layers`" | ||
49 | section in the Yocto Project Development Tasks Manual and the | ||
50 | :doc:`../bsp-guide/bsp-guide`. | ||
51 | |||
52 | Usually, if the board is not completely exotic, adding support in the | ||
53 | Yocto Project is fairly straightforward. | ||
54 | |||
55 | **Q:** Are there any products built using the OpenEmbedded build system? | ||
56 | |||
57 | **A:** The software running on the `Vernier | ||
58 | LabQuest <http://vernier.com/labquest/>`__ is built using the | ||
59 | OpenEmbedded build system. See the `Vernier | ||
60 | LabQuest <http://www.vernier.com/products/interfaces/labq/>`__ website | ||
61 | for more information. There are a number of pre-production devices using | ||
62 | the OpenEmbedded build system and the Yocto Project team announces them | ||
63 | as soon as they are released. | ||
64 | |||
65 | **Q:** What does the OpenEmbedded build system produce as output? | ||
66 | |||
67 | **A:** Because you can use the same set of recipes to create output of | ||
68 | various formats, the output of an OpenEmbedded build depends on how you | ||
69 | start it. Usually, the output is a flashable image ready for the target | ||
70 | device. | ||
71 | |||
72 | **Q:** How do I add my package to the Yocto Project? | ||
73 | |||
74 | **A:** To add a package, you need to create a BitBake recipe. For | ||
75 | information on how to create a BitBake recipe, see the | ||
76 | ":ref:`dev-manual/dev-manual-common-tasks:writing a new recipe`" | ||
77 | section in the Yocto Project Development Tasks Manual. | ||
78 | |||
79 | **Q:** Do I have to reflash my entire board with a new Yocto Project | ||
80 | image when recompiling a package? | ||
81 | |||
82 | **A:** The OpenEmbedded build system can build packages in various | ||
83 | formats such as IPK for OPKG, Debian package (``.deb``), or RPM. You can | ||
84 | then upgrade the packages using the package tools on the device, much | ||
85 | like on a desktop distribution such as Ubuntu or Fedora. However, | ||
86 | package management on the target is entirely optional. | ||
87 | |||
88 | **Q:** I see the error | ||
89 | '``chmod: XXXXX new permissions are r-xrwxrwx, not r-xr-xr-x``'. What is | ||
90 | wrong? | ||
91 | |||
92 | **A:** You are probably running the build on an NTFS filesystem. Use | ||
93 | ``ext2``, ``ext3``, or ``ext4`` instead. | ||
94 | |||
95 | **Q:** I see lots of 404 responses for files when the OpenEmbedded build | ||
96 | system is trying to download sources. Is something wrong? | ||
97 | |||
98 | **A:** Nothing is wrong. The OpenEmbedded build system checks any | ||
99 | configured source mirrors before downloading from the upstream sources. | ||
100 | The build system does this searching for both source archives and | ||
101 | pre-checked out versions of SCM-managed software. These checks help in | ||
102 | large installations because it can reduce load on the SCM servers | ||
103 | themselves. The address above is one of the default mirrors configured | ||
104 | into the build system. Consequently, if an upstream source disappears, | ||
105 | the team can place sources there so builds continue to work. | ||
106 | |||
107 | **Q:** I have machine-specific data in a package for one machine only | ||
108 | but the package is being marked as machine-specific in all cases, how do | ||
109 | I prevent this? | ||
110 | |||
111 | **A:** Set ``SRC_URI_OVERRIDES_PACKAGE_ARCH`` = "0" in the ``.bb`` file | ||
112 | but make sure the package is manually marked as machine-specific for the | ||
113 | case that needs it. The code that handles | ||
114 | ``SRC_URI_OVERRIDES_PACKAGE_ARCH`` is in the | ||
115 | ``meta/classes/base.bbclass`` file. | ||
116 | |||
117 | **Q:** I'm behind a firewall and need to use a proxy server. How do I do | ||
118 | that? | ||
119 | |||
120 | **A:** Most source fetching by the OpenEmbedded build system is done by | ||
121 | ``wget`` and you therefore need to specify the proxy settings in a | ||
122 | ``.wgetrc`` file, which can be in your home directory if you are a | ||
123 | single user or can be in ``/usr/local/etc/wgetrc`` as a global user | ||
124 | file. | ||
125 | |||
126 | Following is the applicable code for setting various proxy types in the | ||
127 | ``.wgetrc`` file. By default, these settings are disabled with comments. | ||
128 | To use them, remove the comments: :: | ||
129 | |||
130 | # You can set the default proxies for Wget to use for http, https, and ftp. | ||
131 | # They will override the value in the environment. | ||
132 | #https_proxy = http://proxy.yoyodyne.com:18023/ | ||
133 | #http_proxy = http://proxy.yoyodyne.com:18023/ | ||
134 | #ftp_proxy = http://proxy.yoyodyne.com:18023/ | ||
135 | |||
136 | # If you do not want to use proxy at all, set this to off. | ||
137 | #use_proxy = on | ||
138 | |||
139 | The Yocto Project also includes a | ||
140 | ``meta-poky/conf/site.conf.sample`` file that shows how to configure CVS | ||
141 | and Git proxy servers if needed. For more information on setting up | ||
142 | various proxy types and configuring proxy servers, see the | ||
143 | ":yocto_wiki:`Working Behind a Network Proxy </wiki/Working_Behind_a_Network_Proxy>`" | ||
144 | Wiki page. | ||
145 | |||
146 | **Q:** What's the difference between target and target\ ``-native``? | ||
147 | |||
148 | **A:** The ``*-native`` targets are designed to run on the system being | ||
149 | used for the build. These are usually tools that are needed to assist | ||
150 | the build in some way such as ``quilt-native``, which is used to apply | ||
151 | patches. The non-native version is the one that runs on the target | ||
152 | device. | ||
153 | |||
154 | **Q:** I'm seeing random build failures. Help?! | ||
155 | |||
156 | **A:** If the same build is failing in totally different and random | ||
157 | ways, the most likely explanation is: | ||
158 | |||
159 | - The hardware you are running the build on has some problem. | ||
160 | |||
161 | - You are running the build under virtualization, in which case the | ||
162 | virtualization probably has bugs. | ||
163 | |||
164 | The OpenEmbedded build system processes a massive amount of data that | ||
165 | causes lots of network, disk and CPU activity and is sensitive to even | ||
166 | single-bit failures in any of these areas. True random failures have | ||
167 | always been traced back to hardware or virtualization issues. | ||
168 | |||
169 | **Q:** When I try to build a native recipe, the build fails with | ||
170 | ``iconv.h`` problems. | ||
171 | |||
172 | **A:** If you get an error message that indicates GNU ``libiconv`` is | ||
173 | not in use but ``iconv.h`` has been included from ``libiconv``, you need | ||
174 | to check to see if you have a previously installed version of the header | ||
175 | file in ``/usr/local/include``. | ||
176 | :: | ||
177 | |||
178 | #error GNU libiconv not in use but included iconv.h is from libiconv | ||
179 | |||
180 | If you find a previously installed | ||
181 | file, you should either uninstall it or temporarily rename it and try | ||
182 | the build again. | ||
183 | |||
184 | This issue is just a single manifestation of "system leakage" issues | ||
185 | caused when the OpenEmbedded build system finds and uses previously | ||
186 | installed files during a native build. This type of issue might not be | ||
187 | limited to ``iconv.h``. Be sure that leakage cannot occur from | ||
188 | ``/usr/local/include`` and ``/opt`` locations. | ||
189 | |||
190 | **Q:** What do we need to ship for license compliance? | ||
191 | |||
192 | **A:** This is a difficult question and you need to consult your lawyer | ||
193 | for the answer for your specific case. It is worth bearing in mind that | ||
194 | for GPL compliance, there needs to be enough information shipped to | ||
195 | allow someone else to rebuild and produce the same end result you are | ||
196 | shipping. This means sharing the source code, any patches applied to it, | ||
197 | and also any configuration information about how that package was | ||
198 | configured and built. | ||
199 | |||
200 | You can find more information on licensing in the | ||
201 | ":ref:`overview-manual/overview-manual-development-environment:licensing`" | ||
202 | section in the Yocto | ||
203 | Project Overview and Concepts Manual and also in the | ||
204 | ":ref:`dev-manual/dev-manual-common-tasks:maintaining open source license compliance during your product's lifecycle`" | ||
205 | section in the Yocto Project Development Tasks Manual. | ||
206 | |||
207 | **Q:** How do I disable the cursor on my touchscreen device? | ||
208 | |||
209 | **A:** You need to create a form factor file as described in the | ||
210 | ":ref:`bsp-filelayout-misc-recipes`" section in | ||
211 | the Yocto Project Board Support Packages (BSP) Developer's Guide. Set | ||
212 | the ``HAVE_TOUCHSCREEN`` variable equal to one as follows: | ||
213 | :: | ||
214 | |||
215 | HAVE_TOUCHSCREEN=1 | ||
216 | |||
217 | **Q:** How do I make sure connected network interfaces are brought up by | ||
218 | default? | ||
219 | |||
220 | **A:** The default interfaces file provided by the netbase recipe does | ||
221 | not automatically bring up network interfaces. Therefore, you will need | ||
222 | to add a BSP-specific netbase that includes an interfaces file. See the | ||
223 | ":ref:`bsp-filelayout-misc-recipes`" section in | ||
224 | the Yocto Project Board Support Packages (BSP) Developer's Guide for | ||
225 | information on creating these types of miscellaneous recipe files. | ||
226 | |||
227 | For example, add the following files to your layer: :: | ||
228 | |||
229 | meta-MACHINE/recipes-bsp/netbase/netbase/MACHINE/interfaces | ||
230 | meta-MACHINE/recipes-bsp/netbase/netbase_5.0.bbappend | ||
231 | |||
232 | **Q:** How do I create images with more free space? | ||
233 | |||
234 | **A:** By default, the OpenEmbedded build system creates images that are | ||
235 | 1.3 times the size of the populated root filesystem. To affect the image | ||
236 | size, you need to set various configurations: | ||
237 | |||
238 | - *Image Size:* The OpenEmbedded build system uses the | ||
239 | :term:`IMAGE_ROOTFS_SIZE` variable to define | ||
240 | the size of the image in Kbytes. The build system determines the size | ||
241 | by taking into account the initial root filesystem size before any | ||
242 | modifications such as requested size for the image and any requested | ||
243 | additional free disk space to be added to the image. | ||
244 | |||
245 | - *Overhead:* Use the | ||
246 | :term:`IMAGE_OVERHEAD_FACTOR` variable | ||
247 | to define the multiplier that the build system applies to the initial | ||
248 | image size, which is 1.3 by default. | ||
249 | |||
250 | - *Additional Free Space:* Use the | ||
251 | :term:`IMAGE_ROOTFS_EXTRA_SPACE` | ||
252 | variable to add additional free space to the image. The build system | ||
253 | adds this space to the image after it determines its | ||
254 | ``IMAGE_ROOTFS_SIZE``. | ||
255 | |||
256 | **Q:** Why don't you support directories with spaces in the pathnames? | ||
257 | |||
258 | **A:** The Yocto Project team has tried to do this before but too many | ||
259 | of the tools the OpenEmbedded build system depends on, such as | ||
260 | ``autoconf``, break when they find spaces in pathnames. Until that | ||
261 | situation changes, the team will not support spaces in pathnames. | ||
262 | |||
263 | **Q:** How do I use an external toolchain? | ||
264 | |||
265 | **A:** The toolchain configuration is very flexible and customizable. It | ||
266 | is primarily controlled with the ``TCMODE`` variable. This variable | ||
267 | controls which ``tcmode-*.inc`` file to include from the | ||
268 | ``meta/conf/distro/include`` directory within the :term:`Source Directory`. | ||
269 | |||
270 | The default value of ``TCMODE`` is "default", which tells the | ||
271 | OpenEmbedded build system to use its internally built toolchain (i.e. | ||
272 | ``tcmode-default.inc``). However, other patterns are accepted. In | ||
273 | particular, "external-\*" refers to external toolchains. One example is | ||
274 | the Sourcery G++ Toolchain. The support for this toolchain resides in | ||
275 | the separate ``meta-sourcery`` layer at | ||
276 | http://github.com/MentorEmbedded/meta-sourcery/. | ||
277 | |||
278 | In addition to the toolchain configuration, you also need a | ||
279 | corresponding toolchain recipe file. This recipe file needs to package | ||
280 | up any pre-built objects in the toolchain such as ``libgcc``, | ||
281 | ``libstdcc++``, any locales, and ``libc``. | ||
282 | |||
283 | **Q:** How does the OpenEmbedded build system obtain source code and | ||
284 | will it work behind my firewall or proxy server? | ||
285 | |||
286 | **A:** The way the build system obtains source code is highly | ||
287 | configurable. You can setup the build system to get source code in most | ||
288 | environments if HTTP transport is available. | ||
289 | |||
290 | When the build system searches for source code, it first tries the local | ||
291 | download directory. If that location fails, Poky tries | ||
292 | :term:`PREMIRRORS`, the upstream source, and then | ||
293 | :term:`MIRRORS` in that order. | ||
294 | |||
295 | Assuming your distribution is "poky", the OpenEmbedded build system uses | ||
296 | the Yocto Project source ``PREMIRRORS`` by default for SCM-based | ||
297 | sources, upstreams for normal tarballs, and then falls back to a number | ||
298 | of other mirrors including the Yocto Project source mirror if those | ||
299 | fail. | ||
300 | |||
301 | As an example, you could add a specific server for the build system to | ||
302 | attempt before any others by adding something like the following to the | ||
303 | ``local.conf`` configuration file: :: | ||
304 | |||
305 | PREMIRRORS_prepend = "\ | ||
306 | git://.*/.* http://www.yoctoproject.org/sources/ \n \ | ||
307 | ftp://.*/.* http://www.yoctoproject.org/sources/ \n \ | ||
308 | http://.*/.* http://www.yoctoproject.org/sources/ \n \ | ||
309 | https://.*/.* http://www.yoctoproject.org/sources/ \n" | ||
310 | |||
311 | These changes cause the build system to intercept Git, FTP, HTTP, and | ||
312 | HTTPS requests and direct them to the ``http://`` sources mirror. You | ||
313 | can use ``file://`` URLs to point to local directories or network shares | ||
314 | as well. | ||
315 | |||
316 | Aside from the previous technique, these options also exist: | ||
317 | :: | ||
318 | |||
319 | BB_NO_NETWORK = "1" | ||
320 | |||
321 | This statement tells BitBake to issue an error | ||
322 | instead of trying to access the Internet. This technique is useful if | ||
323 | you want to ensure code builds only from local sources. | ||
324 | |||
325 | Here is another technique: | ||
326 | :: | ||
327 | |||
328 | BB_FETCH_PREMIRRORONLY = "1" | ||
329 | |||
330 | This statement | ||
331 | limits the build system to pulling source from the ``PREMIRRORS`` only. | ||
332 | Again, this technique is useful for reproducing builds. | ||
333 | |||
334 | Here is another technique: | ||
335 | :: | ||
336 | |||
337 | BB_GENERATE_MIRROR_TARBALLS = "1" | ||
338 | |||
339 | This | ||
340 | statement tells the build system to generate mirror tarballs. This | ||
341 | technique is useful if you want to create a mirror server. If not, | ||
342 | however, the technique can simply waste time during the build. | ||
343 | |||
344 | Finally, consider an example where you are behind an HTTP-only firewall. | ||
345 | You could make the following changes to the ``local.conf`` configuration | ||
346 | file as long as the ``PREMIRRORS`` server is current: :: | ||
347 | |||
348 | PREMIRRORS_prepend = "\ | ||
349 | ftp://.*/.* http://www.yoctoproject.org/sources/ \n \ | ||
350 | http://.*/.* http://www.yoctoproject.org/sources/ \n \ | ||
351 | https://.*/.* http://www.yoctoproject.org/sources/ \n" | ||
352 | BB_FETCH_PREMIRRORONLY = "1" | ||
353 | |||
354 | These changes would cause the build system to successfully fetch source | ||
355 | over HTTP and any network accesses to anything other than the | ||
356 | ``PREMIRRORS`` would fail. | ||
357 | |||
358 | The build system also honors the standard shell environment variables | ||
359 | ``http_proxy``, ``ftp_proxy``, ``https_proxy``, and ``all_proxy`` to | ||
360 | redirect requests through proxy servers. | ||
361 | |||
362 | .. note:: | ||
363 | |||
364 | You can find more information on the | ||
365 | ":yocto_wiki:`Working Behind a Network Proxy </wiki/Working_Behind_a_Network_Proxy>`" | ||
366 | Wiki page. | ||
367 | |||
368 | **Q:** Can I get rid of build output so I can start over? | ||
369 | |||
370 | **A:** Yes - you can easily do this. When you use BitBake to build an | ||
371 | image, all the build output goes into the directory created when you run | ||
372 | the build environment setup script (i.e. | ||
373 | ````` <#structure-core-script>`__). By default, this :term:`Build Directory` | ||
374 | is named ``build`` but can be named | ||
375 | anything you want. | ||
376 | |||
377 | Within the Build Directory, is the ``tmp`` directory. To remove all the | ||
378 | build output yet preserve any source code or downloaded files from | ||
379 | previous builds, simply remove the ``tmp`` directory. | ||
380 | |||
381 | **Q:** Why do ``${bindir}`` and ``${libdir}`` have strange values for | ||
382 | ``-native`` recipes? | ||
383 | |||
384 | **A:** Executables and libraries might need to be used from a directory | ||
385 | other than the directory into which they were initially installed. | ||
386 | Complicating this situation is the fact that sometimes these executables | ||
387 | and libraries are compiled with the expectation of being run from that | ||
388 | initial installation target directory. If this is the case, moving them | ||
389 | causes problems. | ||
390 | |||
391 | This scenario is a fundamental problem for package maintainers of | ||
392 | mainstream Linux distributions as well as for the OpenEmbedded build | ||
393 | system. As such, a well-established solution exists. Makefiles, | ||
394 | Autotools configuration scripts, and other build systems are expected to | ||
395 | respect environment variables such as ``bindir``, ``libdir``, and | ||
396 | ``sysconfdir`` that indicate where executables, libraries, and data | ||
397 | reside when a program is actually run. They are also expected to respect | ||
398 | a ``DESTDIR`` environment variable, which is prepended to all the other | ||
399 | variables when the build system actually installs the files. It is | ||
400 | understood that the program does not actually run from within | ||
401 | ``DESTDIR``. | ||
402 | |||
403 | When the OpenEmbedded build system uses a recipe to build a | ||
404 | target-architecture program (i.e. one that is intended for inclusion on | ||
405 | the image being built), that program eventually runs from the root file | ||
406 | system of that image. Thus, the build system provides a value of | ||
407 | "/usr/bin" for ``bindir``, a value of "/usr/lib" for ``libdir``, and so | ||
408 | forth. | ||
409 | |||
410 | Meanwhile, ``DESTDIR`` is a path within the :term:`Build Directory`. | ||
411 | However, when the recipe builds a | ||
412 | native program (i.e. one that is intended to run on the build machine), | ||
413 | that program is never installed directly to the build machine's root | ||
414 | file system. Consequently, the build system uses paths within the Build | ||
415 | Directory for ``DESTDIR``, ``bindir`` and related variables. To better | ||
416 | understand this, consider the following two paths where the first is | ||
417 | relatively normal and the second is not: :: | ||
418 | |||
419 | /home/maxtothemax/poky-bootchart2/build/tmp/work/i586-poky-linux/zlib/ | ||
420 | 1.2.8-r0/sysroot-destdir/usr/bin | ||
421 | |||
422 | /home/maxtothemax/poky-bootchart2/build/tmp/work/x86_64-linux/ | ||
423 | zlib-native/1.2.8-r0/sysroot-destdir/home/maxtothemax/poky-bootchart2/ | ||
424 | build/tmp/sysroots/x86_64-linux/usr/bin | ||
425 | |||
426 | .. note:: | ||
427 | |||
428 | Due to these lengthy examples, the paths are artificially broken | ||
429 | across lines for readability. | ||
430 | |||
431 | Even if the paths look unusual, | ||
432 | they both are correct - the first for a target and the second for a | ||
433 | native recipe. These paths are a consequence of the ``DESTDIR`` | ||
434 | mechanism and while they appear strange, they are correct and in | ||
435 | practice very effective. | ||
436 | |||
437 | **Q:** The files provided by my ``*-native`` recipe do not appear to be | ||
438 | available to other recipes. Files are missing from the native sysroot, | ||
439 | my recipe is installing to the wrong place, or I am getting permissions | ||
440 | errors during the do_install task in my recipe! What is wrong? | ||
441 | |||
442 | **A:** This situation results when a build system does not recognize the | ||
443 | environment variables supplied to it by :term:`BitBake`. The | ||
444 | incident that prompted this FAQ entry involved a Makefile that used an | ||
445 | environment variable named ``BINDIR`` instead of the more standard | ||
446 | variable ``bindir``. The makefile's hardcoded default value of | ||
447 | "/usr/bin" worked most of the time, but not for the recipe's ``-native`` | ||
448 | variant. For another example, permissions errors might be caused by a | ||
449 | Makefile that ignores ``DESTDIR`` or uses a different name for that | ||
450 | environment variable. Check the the build system to see if these kinds | ||
451 | of issues exist. | ||