blob: c7322e7623aea22d104efd2732a338326f453b00 [file] [log] [blame]
Andrew Geisslerf0343792020-11-18 10:42:21 -06001.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002
3***
4FAQ
5***
6
Andrew Geissler4c19ea12020-10-27 13:52:24 -05007**Q:** How does Poky differ from :oe_home:`OpenEmbedded <>`?
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008
9**A:** The term ``Poky`` refers to the specific reference build
10system that the Yocto Project provides. Poky is based on
11:term:`OpenEmbedded-Core (OE-Core)` and :term:`BitBake`. Thus, the
12generic term used here for the build system is the "OpenEmbedded build
13system." Development in the Yocto Project using Poky is closely tied to
14OpenEmbedded, with changes always being merged to OE-Core or BitBake
15first before being pulled back into Poky. This practice benefits both
16projects immediately.
17
18**Q:** My development system does not meet the required Git, tar, and
Andrew Geissler3b8a17c2021-04-15 15:55:55 -050019Python versions. In particular, I do not have Python &MIN_PYTHON_VERSION; or greater.
Andrew Geisslerc9f78652020-09-18 14:11:35 -050020Can I still use the Yocto Project?
21
22**A:** You can get the required tools on your host development system a
23couple different ways (i.e. building a tarball or downloading a
Andrew Geissler4c19ea12020-10-27 13:52:24 -050024tarball). See the
Andrew Geissler09209ee2020-12-13 08:44:15 -060025":ref:`ref-manual/system-requirements:required git, tar, python and gcc versions`"
Andrew Geissler4c19ea12020-10-27 13:52:24 -050026section for steps on how to update your build tools.
Andrew Geisslerc9f78652020-09-18 14:11:35 -050027
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
46Support Package (BSP) layer for it. For more information on how to
47create a BSP layer, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -060048":ref:`dev-manual/common-tasks:understanding and creating layers`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -050049section in the Yocto Project Development Tasks Manual and the
Andrew Geissler09209ee2020-12-13 08:44:15 -060050:doc:`/bsp-guide/index`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -050051
52Usually, if the board is not completely exotic, adding support in the
53Yocto 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
Andrew Geisslerd1e89492021-02-12 15:35:20 -060058LabQuest <https://vernier.com/labquest/>`__ is built using the
Andrew Geisslerc9f78652020-09-18 14:11:35 -050059OpenEmbedded build system. See the `Vernier
Andrew Geisslerd1e89492021-02-12 15:35:20 -060060LabQuest <https://www.vernier.com/products/interfaces/labq/>`__ website
Andrew Geisslerc9f78652020-09-18 14:11:35 -050061for more information. There are a number of pre-production devices using
62the OpenEmbedded build system and the Yocto Project team announces them
63as 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
68various formats, the output of an OpenEmbedded build depends on how you
69start it. Usually, the output is a flashable image ready for the target
70device.
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
75information on how to create a BitBake recipe, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -060076":ref:`dev-manual/common-tasks:writing a new recipe`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -050077section in the Yocto Project Development Tasks Manual.
78
79**Q:** Do I have to reflash my entire board with a new Yocto Project
80image when recompiling a package?
81
82**A:** The OpenEmbedded build system can build packages in various
83formats such as IPK for OPKG, Debian package (``.deb``), or RPM. You can
84then upgrade the packages using the package tools on the device, much
85like on a desktop distribution such as Ubuntu or Fedora. However,
86package 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
90wrong?
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
96system is trying to download sources. Is something wrong?
97
98**A:** Nothing is wrong. The OpenEmbedded build system checks any
99configured source mirrors before downloading from the upstream sources.
100The build system does this searching for both source archives and
101pre-checked out versions of SCM-managed software. These checks help in
102large installations because it can reduce load on the SCM servers
103themselves. The address above is one of the default mirrors configured
104into the build system. Consequently, if an upstream source disappears,
105the 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
108but the package is being marked as machine-specific in all cases, how do
109I prevent this?
110
Andrew Geissler09036742021-06-25 14:25:14 -0500111**A:** Set :term:`SRC_URI_OVERRIDES_PACKAGE_ARCH` = "0" in the ``.bb`` file
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500112but make sure the package is manually marked as machine-specific for the
113case that needs it. The code that handles
Andrew Geissler09036742021-06-25 14:25:14 -0500114:term:`SRC_URI_OVERRIDES_PACKAGE_ARCH` is in the
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500115``meta/classes/base.bbclass`` file.
116
117**Q:** I'm behind a firewall and need to use a proxy server. How do I do
118that?
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
123single user or can be in ``/usr/local/etc/wgetrc`` as a global user
124file.
125
126Following is the applicable code for setting various proxy types in the
127``.wgetrc`` file. By default, these settings are disabled with comments.
Andrew Geisslerc926e172021-05-07 16:11:35 -0500128To use them, remove the comments::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500129
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
139The Yocto Project also includes a
140``meta-poky/conf/site.conf.sample`` file that shows how to configure CVS
141and Git proxy servers if needed. For more information on setting up
142various proxy types and configuring proxy servers, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600143":yocto_wiki:`Working Behind a Network Proxy </Working_Behind_a_Network_Proxy>`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500144Wiki 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
149used for the build. These are usually tools that are needed to assist
150the build in some way such as ``quilt-native``, which is used to apply
151patches. The non-native version is the one that runs on the target
152device.
153
154**Q:** I'm seeing random build failures. Help?!
155
156**A:** If the same build is failing in totally different and random
157ways, 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
164The OpenEmbedded build system processes a massive amount of data that
165causes lots of network, disk and CPU activity and is sensitive to even
166single-bit failures in any of these areas. True random failures have
167always 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
173not in use but ``iconv.h`` has been included from ``libiconv``, you need
174to check to see if you have a previously installed version of the header
175file in ``/usr/local/include``.
176::
177
178 #error GNU libiconv not in use but included iconv.h is from libiconv
179
180If you find a previously installed
181file, you should either uninstall it or temporarily rename it and try
182the build again.
183
184This issue is just a single manifestation of "system leakage" issues
185caused when the OpenEmbedded build system finds and uses previously
186installed files during a native build. This type of issue might not be
187limited 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
193for the answer for your specific case. It is worth bearing in mind that
194for GPL compliance, there needs to be enough information shipped to
195allow someone else to rebuild and produce the same end result you are
196shipping. This means sharing the source code, any patches applied to it,
197and also any configuration information about how that package was
198configured and built.
199
200You can find more information on licensing in the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600201":ref:`overview-manual/development-environment:licensing`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500202section in the Yocto
203Project Overview and Concepts Manual and also in the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600204":ref:`dev-manual/common-tasks:maintaining open source license compliance during your product's lifecycle`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500205section 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
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600210":ref:`bsp-guide/bsp:miscellaneous bsp-specific recipe files`" section in
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500211the Yocto Project Board Support Packages (BSP) Developer's Guide. Set
Andrew Geisslerc926e172021-05-07 16:11:35 -0500212the ``HAVE_TOUCHSCREEN`` variable equal to one as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500213
214 HAVE_TOUCHSCREEN=1
215
216**Q:** How do I make sure connected network interfaces are brought up by
217default?
218
219**A:** The default interfaces file provided by the netbase recipe does
220not automatically bring up network interfaces. Therefore, you will need
221to add a BSP-specific netbase that includes an interfaces file. See the
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600222":ref:`bsp-guide/bsp:miscellaneous bsp-specific recipe files`" section in
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500223the Yocto Project Board Support Packages (BSP) Developer's Guide for
224information on creating these types of miscellaneous recipe files.
225
Andrew Geisslerc926e172021-05-07 16:11:35 -0500226For example, add the following files to your layer::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500227
228 meta-MACHINE/recipes-bsp/netbase/netbase/MACHINE/interfaces
229 meta-MACHINE/recipes-bsp/netbase/netbase_5.0.bbappend
230
231**Q:** How do I create images with more free space?
232
233**A:** By default, the OpenEmbedded build system creates images that are
2341.3 times the size of the populated root filesystem. To affect the image
235size, you need to set various configurations:
236
237- *Image Size:* The OpenEmbedded build system uses the
238 :term:`IMAGE_ROOTFS_SIZE` variable to define
239 the size of the image in Kbytes. The build system determines the size
240 by taking into account the initial root filesystem size before any
241 modifications such as requested size for the image and any requested
242 additional free disk space to be added to the image.
243
244- *Overhead:* Use the
245 :term:`IMAGE_OVERHEAD_FACTOR` variable
246 to define the multiplier that the build system applies to the initial
247 image size, which is 1.3 by default.
248
249- *Additional Free Space:* Use the
250 :term:`IMAGE_ROOTFS_EXTRA_SPACE`
251 variable to add additional free space to the image. The build system
252 adds this space to the image after it determines its
Andrew Geissler09036742021-06-25 14:25:14 -0500253 :term:`IMAGE_ROOTFS_SIZE`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500254
255**Q:** Why don't you support directories with spaces in the pathnames?
256
257**A:** The Yocto Project team has tried to do this before but too many
258of the tools the OpenEmbedded build system depends on, such as
259``autoconf``, break when they find spaces in pathnames. Until that
260situation changes, the team will not support spaces in pathnames.
261
262**Q:** How do I use an external toolchain?
263
264**A:** The toolchain configuration is very flexible and customizable. It
Andrew Geissler09036742021-06-25 14:25:14 -0500265is primarily controlled with the :term:`TCMODE` variable. This variable
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500266controls which ``tcmode-*.inc`` file to include from the
267``meta/conf/distro/include`` directory within the :term:`Source Directory`.
268
Andrew Geissler09036742021-06-25 14:25:14 -0500269The default value of :term:`TCMODE` is "default", which tells the
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500270OpenEmbedded build system to use its internally built toolchain (i.e.
271``tcmode-default.inc``). However, other patterns are accepted. In
272particular, "external-\*" refers to external toolchains. One example is
273the Sourcery G++ Toolchain. The support for this toolchain resides in
274the separate ``meta-sourcery`` layer at
Andrew Geisslerd1e89492021-02-12 15:35:20 -0600275https://github.com/MentorEmbedded/meta-sourcery/.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500276
277In addition to the toolchain configuration, you also need a
278corresponding toolchain recipe file. This recipe file needs to package
279up any pre-built objects in the toolchain such as ``libgcc``,
280``libstdcc++``, any locales, and ``libc``.
281
282**Q:** How does the OpenEmbedded build system obtain source code and
283will it work behind my firewall or proxy server?
284
285**A:** The way the build system obtains source code is highly
286configurable. You can setup the build system to get source code in most
287environments if HTTP transport is available.
288
289When the build system searches for source code, it first tries the local
290download directory. If that location fails, Poky tries
291:term:`PREMIRRORS`, the upstream source, and then
292:term:`MIRRORS` in that order.
293
294Assuming your distribution is "poky", the OpenEmbedded build system uses
Andrew Geissler5f350902021-07-23 13:09:54 -0400295the Yocto Project source :term:`PREMIRRORS` by default for SCM-based
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500296sources, upstreams for normal tarballs, and then falls back to a number
297of other mirrors including the Yocto Project source mirror if those
298fail.
299
300As an example, you could add a specific server for the build system to
301attempt before any others by adding something like the following to the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500302``local.conf`` configuration file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500303
304 PREMIRRORS_prepend = "\
305 git://.*/.* http://www.yoctoproject.org/sources/ \n \
306 ftp://.*/.* http://www.yoctoproject.org/sources/ \n \
307 http://.*/.* http://www.yoctoproject.org/sources/ \n \
308 https://.*/.* http://www.yoctoproject.org/sources/ \n"
309
310These changes cause the build system to intercept Git, FTP, HTTP, and
311HTTPS requests and direct them to the ``http://`` sources mirror. You
312can use ``file://`` URLs to point to local directories or network shares
313as well.
314
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700315Here are other options::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500316
317 BB_NO_NETWORK = "1"
318
319This statement tells BitBake to issue an error
320instead of trying to access the Internet. This technique is useful if
321you want to ensure code builds only from local sources.
322
Andrew Geisslerc926e172021-05-07 16:11:35 -0500323Here is another technique::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500324
325 BB_FETCH_PREMIRRORONLY = "1"
326
327This statement
Andrew Geissler09036742021-06-25 14:25:14 -0500328limits the build system to pulling source from the :term:`PREMIRRORS` only.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500329Again, this technique is useful for reproducing builds.
330
Andrew Geisslerc926e172021-05-07 16:11:35 -0500331Here is another technique::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500332
333 BB_GENERATE_MIRROR_TARBALLS = "1"
334
335This
336statement tells the build system to generate mirror tarballs. This
337technique is useful if you want to create a mirror server. If not,
338however, the technique can simply waste time during the build.
339
340Finally, consider an example where you are behind an HTTP-only firewall.
341You could make the following changes to the ``local.conf`` configuration
Andrew Geissler09036742021-06-25 14:25:14 -0500342file as long as the :term:`PREMIRRORS` server is current::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500343
344 PREMIRRORS_prepend = "\
345 ftp://.*/.* http://www.yoctoproject.org/sources/ \n \
346 http://.*/.* http://www.yoctoproject.org/sources/ \n \
347 https://.*/.* http://www.yoctoproject.org/sources/ \n"
348 BB_FETCH_PREMIRRORONLY = "1"
349
350These changes would cause the build system to successfully fetch source
351over HTTP and any network accesses to anything other than the
Andrew Geissler09036742021-06-25 14:25:14 -0500352:term:`PREMIRRORS` would fail.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500353
354The build system also honors the standard shell environment variables
355``http_proxy``, ``ftp_proxy``, ``https_proxy``, and ``all_proxy`` to
356redirect requests through proxy servers.
357
358.. note::
359
360 You can find more information on the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600361 ":yocto_wiki:`Working Behind a Network Proxy </Working_Behind_a_Network_Proxy>`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500362 Wiki page.
363
364**Q:** Can I get rid of build output so I can start over?
365
366**A:** Yes - you can easily do this. When you use BitBake to build an
367image, all the build output goes into the directory created when you run
368the build environment setup script (i.e.
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500369:ref:`structure-core-script`). By default, this :term:`Build Directory`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500370is named ``build`` but can be named
371anything you want.
372
373Within the Build Directory, is the ``tmp`` directory. To remove all the
374build output yet preserve any source code or downloaded files from
375previous builds, simply remove the ``tmp`` directory.
376
377**Q:** Why do ``${bindir}`` and ``${libdir}`` have strange values for
378``-native`` recipes?
379
380**A:** Executables and libraries might need to be used from a directory
381other than the directory into which they were initially installed.
382Complicating this situation is the fact that sometimes these executables
383and libraries are compiled with the expectation of being run from that
384initial installation target directory. If this is the case, moving them
385causes problems.
386
387This scenario is a fundamental problem for package maintainers of
388mainstream Linux distributions as well as for the OpenEmbedded build
389system. As such, a well-established solution exists. Makefiles,
390Autotools configuration scripts, and other build systems are expected to
391respect environment variables such as ``bindir``, ``libdir``, and
392``sysconfdir`` that indicate where executables, libraries, and data
393reside when a program is actually run. They are also expected to respect
394a ``DESTDIR`` environment variable, which is prepended to all the other
395variables when the build system actually installs the files. It is
396understood that the program does not actually run from within
397``DESTDIR``.
398
399When the OpenEmbedded build system uses a recipe to build a
400target-architecture program (i.e. one that is intended for inclusion on
401the image being built), that program eventually runs from the root file
402system of that image. Thus, the build system provides a value of
403"/usr/bin" for ``bindir``, a value of "/usr/lib" for ``libdir``, and so
404forth.
405
406Meanwhile, ``DESTDIR`` is a path within the :term:`Build Directory`.
407However, when the recipe builds a
408native program (i.e. one that is intended to run on the build machine),
409that program is never installed directly to the build machine's root
410file system. Consequently, the build system uses paths within the Build
411Directory for ``DESTDIR``, ``bindir`` and related variables. To better
412understand this, consider the following two paths where the first is
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500413relatively normal and the second is not:
414
415.. note::
416
417 Due to these lengthy examples, the paths are artificially broken
418 across lines for readability.
419
420::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500421
422 /home/maxtothemax/poky-bootchart2/build/tmp/work/i586-poky-linux/zlib/
423 1.2.8-r0/sysroot-destdir/usr/bin
424
425 /home/maxtothemax/poky-bootchart2/build/tmp/work/x86_64-linux/
426 zlib-native/1.2.8-r0/sysroot-destdir/home/maxtothemax/poky-bootchart2/
427 build/tmp/sysroots/x86_64-linux/usr/bin
428
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500429Even if the paths look unusual,
430they both are correct - the first for a target and the second for a
431native recipe. These paths are a consequence of the ``DESTDIR``
432mechanism and while they appear strange, they are correct and in
433practice very effective.
434
435**Q:** The files provided by my ``*-native`` recipe do not appear to be
436available to other recipes. Files are missing from the native sysroot,
437my recipe is installing to the wrong place, or I am getting permissions
438errors during the do_install task in my recipe! What is wrong?
439
440**A:** This situation results when a build system does not recognize the
441environment variables supplied to it by :term:`BitBake`. The
442incident that prompted this FAQ entry involved a Makefile that used an
443environment variable named ``BINDIR`` instead of the more standard
444variable ``bindir``. The makefile's hardcoded default value of
445"/usr/bin" worked most of the time, but not for the recipe's ``-native``
446variant. For another example, permissions errors might be caused by a
447Makefile that ignores ``DESTDIR`` or uses a different name for that
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500448environment variable. Check the build system to see if these kinds
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500449of issues exist.
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600450
451**Q:** I'm adding a binary in a recipe but it's different in the image, what is
452changing it?
453
454**A:** The first most obvious change is the system stripping debug symbols from
455it. Setting :term:`INHIBIT_PACKAGE_STRIP` to stop debug symbols being stripped and/or
456:term:`INHIBIT_PACKAGE_DEBUG_SPLIT` to stop debug symbols being split into a separate
457file will ensure the binary is unchanged. The other less obvious thing that can
458happen is prelinking of the image. This is set by default in local.conf via
459:term:`USER_CLASSES` which can contain 'image-prelink'. If you remove that, the
460image will not be prelinked meaning the binaries would be unchanged.