blob: a3a15506c3b083fdc93af6c114a291182db7a0ee [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
Patrick Williams975a06f2022-10-21 14:42:47 -05007.. contents::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008
Patrick Williams975a06f2022-10-21 14:42:47 -05009General questions
10=================
11
12How does Poky differ from OpenEmbedded?
13---------------------------------------
14
15The term ``Poky`` refers to the specific reference build
Andrew Geisslerc9f78652020-09-18 14:11:35 -050016system that the Yocto Project provides. Poky is based on
17:term:`OpenEmbedded-Core (OE-Core)` and :term:`BitBake`. Thus, the
18generic term used here for the build system is the "OpenEmbedded build
19system." Development in the Yocto Project using Poky is closely tied to
20OpenEmbedded, with changes always being merged to OE-Core or BitBake
21first before being pulled back into Poky. This practice benefits both
22projects immediately.
23
Patrick Williams975a06f2022-10-21 14:42:47 -050024How can you claim Poky / OpenEmbedded-Core is stable?
25-----------------------------------------------------
Andrew Geisslerc9f78652020-09-18 14:11:35 -050026
Patrick Williams975a06f2022-10-21 14:42:47 -050027There are three areas that help with stability;
Andrew Geisslerc9f78652020-09-18 14:11:35 -050028
29- The Yocto Project team keeps :term:`OpenEmbedded-Core (OE-Core)` small and
30 focused, containing around 830 recipes as opposed to the thousands
31 available in other OpenEmbedded community layers. Keeping it small
32 makes it easy to test and maintain.
33
34- The Yocto Project team runs manual and automated tests using a small,
35 fixed set of reference hardware as well as emulated targets.
36
Patrick Williams975a06f2022-10-21 14:42:47 -050037- The Yocto Project uses an :yocto_ab:`autobuilder <>`, which provides
38 continuous build and integration tests.
Andrew Geisslerc9f78652020-09-18 14:11:35 -050039
Patrick Williams975a06f2022-10-21 14:42:47 -050040Are there any products built using the OpenEmbedded build system?
41-----------------------------------------------------------------
Andrew Geisslerc9f78652020-09-18 14:11:35 -050042
Patrick Williams975a06f2022-10-21 14:42:47 -050043See :yocto_wiki:`Products that use the Yocto Project
Patrick Williams2194f502022-10-16 14:26:09 -050044</Project_Users#Products_that_use_the_Yocto_Project>` in the Yocto Project
45Wiki. Don't hesitate to contribute to this page if you know other such
46products.
Andrew Geisslerc9f78652020-09-18 14:11:35 -050047
Patrick Williams975a06f2022-10-21 14:42:47 -050048Building environment
49====================
Andrew Geisslerc9f78652020-09-18 14:11:35 -050050
Patrick Williams975a06f2022-10-21 14:42:47 -050051Missing dependencies on the development system?
52-----------------------------------------------
Andrew Geisslerc9f78652020-09-18 14:11:35 -050053
Patrick Williams975a06f2022-10-21 14:42:47 -050054If your development system does not meet the required Git, tar, and
55Python versions, you can get the required tools on your host development
56system in different ways (i.e. building a tarball or downloading a
57tarball). See the ":ref:`ref-manual/system-requirements:required git, tar, python, make and gcc versions`"
58section for steps on how to update your build tools.
Andrew Geisslerc9f78652020-09-18 14:11:35 -050059
Patrick Williams975a06f2022-10-21 14:42:47 -050060How does OpenEmbedded fetch source code? Will it work through a firewall or proxy server?
61-----------------------------------------------------------------------------------------
Andrew Geisslerc9f78652020-09-18 14:11:35 -050062
Patrick Williams975a06f2022-10-21 14:42:47 -050063The way the build system obtains source code is highly
Andrew Geisslerc9f78652020-09-18 14:11:35 -050064configurable. You can setup the build system to get source code in most
65environments if HTTP transport is available.
66
67When the build system searches for source code, it first tries the local
68download directory. If that location fails, Poky tries
69:term:`PREMIRRORS`, the upstream source, and then
70:term:`MIRRORS` in that order.
71
72Assuming your distribution is "poky", the OpenEmbedded build system uses
Andrew Geissler5f350902021-07-23 13:09:54 -040073the Yocto Project source :term:`PREMIRRORS` by default for SCM-based
Andrew Geisslerc9f78652020-09-18 14:11:35 -050074sources, upstreams for normal tarballs, and then falls back to a number
75of other mirrors including the Yocto Project source mirror if those
76fail.
77
78As an example, you could add a specific server for the build system to
79attempt before any others by adding something like the following to the
Andrew Geisslerc926e172021-05-07 16:11:35 -050080``local.conf`` configuration file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -050081
Patrick Williams0ca19cc2021-08-16 14:03:13 -050082 PREMIRRORS:prepend = "\
Andrew Geissler595f6302022-01-24 19:11:47 +000083 git://.*/.* &YOCTO_DL_URL;/mirror/sources/ \
84 ftp://.*/.* &YOCTO_DL_URL;/mirror/sources/ \
85 http://.*/.* &YOCTO_DL_URL;/mirror/sources/ \
86 https://.*/.* &YOCTO_DL_URL;/mirror/sources/"
Andrew Geisslerc9f78652020-09-18 14:11:35 -050087
88These changes cause the build system to intercept Git, FTP, HTTP, and
89HTTPS requests and direct them to the ``http://`` sources mirror. You
90can use ``file://`` URLs to point to local directories or network shares
91as well.
92
William A. Kennington IIIac69b482021-06-02 12:28:27 -070093Here are other options::
Andrew Geisslerc9f78652020-09-18 14:11:35 -050094
95 BB_NO_NETWORK = "1"
96
97This statement tells BitBake to issue an error
98instead of trying to access the Internet. This technique is useful if
99you want to ensure code builds only from local sources.
100
Andrew Geisslerc926e172021-05-07 16:11:35 -0500101Here is another technique::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500102
103 BB_FETCH_PREMIRRORONLY = "1"
104
Patrick Williams975a06f2022-10-21 14:42:47 -0500105This statement limits the build system to pulling source from the
106:term:`PREMIRRORS` only. Again, this technique is useful for reproducing
107builds.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500108
Andrew Geisslerc926e172021-05-07 16:11:35 -0500109Here is another technique::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500110
111 BB_GENERATE_MIRROR_TARBALLS = "1"
112
Patrick Williams975a06f2022-10-21 14:42:47 -0500113This statement tells the build system to generate mirror tarballs. This
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500114technique is useful if you want to create a mirror server. If not,
115however, the technique can simply waste time during the build.
116
117Finally, consider an example where you are behind an HTTP-only firewall.
118You could make the following changes to the ``local.conf`` configuration
Andrew Geissler09036742021-06-25 14:25:14 -0500119file as long as the :term:`PREMIRRORS` server is current::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500120
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500121 PREMIRRORS:prepend = "\
Andrew Geissler595f6302022-01-24 19:11:47 +0000122 git://.*/.* &YOCTO_DL_URL;/mirror/sources/ \
123 ftp://.*/.* &YOCTO_DL_URL;/mirror/sources/ \
124 http://.*/.* &YOCTO_DL_URL;/mirror/sources/ \
125 https://.*/.* &YOCTO_DL_URL;/mirror/sources/"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500126 BB_FETCH_PREMIRRORONLY = "1"
127
128These changes would cause the build system to successfully fetch source
129over HTTP and any network accesses to anything other than the
Andrew Geissler09036742021-06-25 14:25:14 -0500130:term:`PREMIRRORS` would fail.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500131
Patrick Williams975a06f2022-10-21 14:42:47 -0500132Most source fetching by the OpenEmbedded build system is done by
133``wget`` and you therefore need to specify the proxy settings in a
134``.wgetrc`` file, which can be in your home directory if you are a
135single user or can be in ``/usr/local/etc/wgetrc`` as a global user
136file.
137
138Following is the applicable code for setting various proxy types in the
139``.wgetrc`` file. By default, these settings are disabled with comments.
140To use them, remove the comments::
141
142 # You can set the default proxies for Wget to use for http, https, and ftp.
143 # They will override the value in the environment.
144 #https_proxy = http://proxy.yoyodyne.com:18023/
145 #http_proxy = http://proxy.yoyodyne.com:18023/
146 #ftp_proxy = http://proxy.yoyodyne.com:18023/
147
148 # If you do not want to use proxy at all, set this to off.
149 #use_proxy = on
150
151The build system also accepts ``http_proxy``, ``ftp_proxy``, ``https_proxy``,
152and ``all_proxy`` set as to standard shell environment variables to redirect
153requests through proxy servers.
154
155The Yocto Project also includes a
156``meta-poky/conf/templates/default/site.conf.sample`` file that shows
157how to configure CVS and Git proxy servers if needed.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500158
159.. note::
160
161 You can find more information on the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600162 ":yocto_wiki:`Working Behind a Network Proxy </Working_Behind_a_Network_Proxy>`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500163 Wiki page.
164
Patrick Williams975a06f2022-10-21 14:42:47 -0500165Using the OpenEmbedded Build system
166===================================
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500167
Patrick Williams975a06f2022-10-21 14:42:47 -0500168How do I use an external toolchain?
169-----------------------------------
170
Andrew Geissler517393d2023-01-13 08:55:19 -0600171See the ":ref:`dev-manual/external-toolchain:optionally using an external toolchain`"
172section in the Development Task manual.
Patrick Williams975a06f2022-10-21 14:42:47 -0500173
174Why do I get chmod permission issues?
175-------------------------------------
176
177If you see the error
178``chmod: XXXXX new permissions are r-xrwxrwx, not r-xr-xr-x``,
179you are probably running the build on an NTFS filesystem. Instead,
180run the build system on a partition with a modern Linux filesystem such as
181``ext4``, ``btrfs`` or ``xfs``.
182
183I see many 404 errors trying to download sources. Is anything wrong?
184--------------------------------------------------------------------
185
186Nothing is wrong. The OpenEmbedded build system checks any
187configured source mirrors before downloading from the upstream sources.
188The build system does this searching for both source archives and
189pre-checked out versions of SCM-managed software. These checks help in
190large installations because it can reduce load on the SCM servers
191themselves. This can also allow builds to continue to work if an
192upstream source disappears.
193
194Why do I get random build failures?
195-----------------------------------
196
197If the same build is failing in totally different and random
198ways, the most likely explanation is:
199
200- The hardware you are running the build on has some problem.
201
202- You are running the build under virtualization, in which case the
203 virtualization probably has bugs.
204
205The OpenEmbedded build system processes a massive amount of data that
206causes lots of network, disk and CPU activity and is sensitive to even
207single-bit failures in any of these areas. True random failures have
208always been traced back to hardware or virtualization issues.
209
210Why does the build fail with ``iconv.h`` problems?
211--------------------------------------------------
212
213When you try to build a native recipe, you may get an error message that
214indicates that GNU ``libiconv`` is not in use but ``iconv.h`` has been
215included from ``libiconv``::
216
217 #error GNU libiconv not in use but included iconv.h is from libiconv
218
219When this happens, you need to check whether you have a previously
220installed version of the header file in ``/usr/local/include/``.
221If that's the case, you should either uninstall it or temporarily rename
222it and try the build again.
223
224This issue is just a single manifestation of "system leakage" issues
225caused when the OpenEmbedded build system finds and uses previously
226installed files during a native build. This type of issue might not be
227limited to ``iconv.h``. Make sure that leakage cannot occur from
228``/usr/local/include`` and ``/opt`` locations.
229
230Why don't other recipes find the files provided by my ``*-native`` recipe?
231--------------------------------------------------------------------------
232
233Files provided by your native recipe could be missing from the native
234sysroot, your recipe could also be installing to the wrong place, or you
235could be getting permission errors during the :ref:`ref-tasks-install`
236task in your recipe.
237
238This situation happens when the build system used by a package does not
239recognize the environment variables supplied to it by :term:`BitBake`. The
240incident that prompted this FAQ entry involved a Makefile that used an
241environment variable named ``BINDIR`` instead of the more standard
242variable ``bindir``. The makefile's hardcoded default value of
243"/usr/bin" worked most of the time, but not for the recipe's ``-native``
244variant. For another example, permission errors might be caused by a
245Makefile that ignores ``DESTDIR`` or uses a different name for that
246environment variable. Check the build system of the package to see if
247these kinds of issues exist.
248
249Can I get rid of build output so I can start over?
250--------------------------------------------------
251
252Yes --- you can easily do this. When you use BitBake to build an
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500253image, all the build output goes into the directory created when you run
Patrick Williams975a06f2022-10-21 14:42:47 -0500254the build environment setup script (i.e. :ref:`structure-core-script`).
255By default, this :term:`Build Directory` is named ``build`` but can be named
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500256anything you want.
257
Patrick Williams2390b1b2022-11-03 13:47:49 -0500258Within the :term:`Build Directory`, is the ``tmp`` directory. To remove all the
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500259build output yet preserve any source code or downloaded files from
260previous builds, simply remove the ``tmp`` directory.
261
Patrick Williams975a06f2022-10-21 14:42:47 -0500262Customizing generated images
263============================
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500264
Patrick Williams975a06f2022-10-21 14:42:47 -0500265What does the OpenEmbedded build system produce as output?
266----------------------------------------------------------
267
268Because you can use the same set of recipes to create output of
269various formats, the output of an OpenEmbedded build depends on how you
270start it. Usually, the output is a flashable image ready for the target
271device.
272
273How do I make the Yocto Project support my board?
274-------------------------------------------------
275
276Support for an additional board is added by creating a Board
277Support Package (BSP) layer for it. For more information on how to
278create a BSP layer, see the
Andrew Geissler517393d2023-01-13 08:55:19 -0600279":ref:`dev-manual/layers:understanding and creating layers`"
Patrick Williams975a06f2022-10-21 14:42:47 -0500280section in the Yocto Project Development Tasks Manual and the
281:doc:`/bsp-guide/index`.
282
283Usually, if the board is not completely exotic, adding support in the
284Yocto Project is fairly straightforward.
285
286How do I make the Yocto Project support my package?
287---------------------------------------------------
288
289To add a package, you need to create a BitBake recipe. For
290information on how to create a BitBake recipe, see the
Andrew Geissler517393d2023-01-13 08:55:19 -0600291":ref:`dev-manual/new-recipe:writing a new recipe`"
Patrick Williams975a06f2022-10-21 14:42:47 -0500292section in the Yocto Project Development Tasks Manual.
293
294What do I need to ship for license compliance?
295----------------------------------------------
296
297This is a difficult question and you need to consult your lawyer
298for the answer for your specific case. It is worth bearing in mind that
299for GPL compliance, there needs to be enough information shipped to
300allow someone else to rebuild and produce the same end result you are
301shipping. This means sharing the source code, any patches applied to it,
302and also any configuration information about how that package was
303configured and built.
304
305You can find more information on licensing in the
306":ref:`overview-manual/development-environment:licensing`"
307section in the Yocto Project Overview and Concepts Manual and also in the
Andrew Geissler517393d2023-01-13 08:55:19 -0600308":ref:`dev-manual/licenses:maintaining open source license compliance during your product's lifecycle`"
Patrick Williams975a06f2022-10-21 14:42:47 -0500309section in the Yocto Project Development Tasks Manual.
310
311Do I have to make a full reflash after recompiling one package?
312---------------------------------------------------------------
313
314The OpenEmbedded build system can build packages in various
315formats such as IPK for OPKG, Debian package (``.deb``), or RPM. You can
316then upgrade only the modified packages using the package tools on the device,
317much like on a desktop distribution such as Ubuntu or Fedora. However,
318package management on the target is entirely optional.
319
320How to prevent my package from being marked as machine specific?
321----------------------------------------------------------------
322
323If you have machine-specific data in a package for one machine only
324but the package is being marked as machine-specific in all cases,
325you can set :term:`SRC_URI_OVERRIDES_PACKAGE_ARCH` = "0" in the ``.bb`` file.
326However, but make sure the package is manually marked as machine-specific for the
327case that needs it. The code that handles :term:`SRC_URI_OVERRIDES_PACKAGE_ARCH`
328is in the ``meta/classes-global/base.bbclass`` file.
329
330What's the difference between ``target`` and ``target-native``?
331---------------------------------------------------------------
332
333The ``*-native`` targets are designed to run on the system being
334used for the build. These are usually tools that are needed to assist
335the build in some way such as ``quilt-native``, which is used to apply
336patches. The non-native version is the one that runs on the target
337device.
338
339Why do ``${bindir}`` and ``${libdir}`` have strange values for ``-native`` recipes?
340-----------------------------------------------------------------------------------
341
342Executables and libraries might need to be used from a directory
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500343other than the directory into which they were initially installed.
344Complicating this situation is the fact that sometimes these executables
345and libraries are compiled with the expectation of being run from that
346initial installation target directory. If this is the case, moving them
347causes problems.
348
349This scenario is a fundamental problem for package maintainers of
350mainstream Linux distributions as well as for the OpenEmbedded build
351system. As such, a well-established solution exists. Makefiles,
352Autotools configuration scripts, and other build systems are expected to
353respect environment variables such as ``bindir``, ``libdir``, and
354``sysconfdir`` that indicate where executables, libraries, and data
355reside when a program is actually run. They are also expected to respect
356a ``DESTDIR`` environment variable, which is prepended to all the other
357variables when the build system actually installs the files. It is
358understood that the program does not actually run from within
359``DESTDIR``.
360
361When the OpenEmbedded build system uses a recipe to build a
362target-architecture program (i.e. one that is intended for inclusion on
363the image being built), that program eventually runs from the root file
364system of that image. Thus, the build system provides a value of
365"/usr/bin" for ``bindir``, a value of "/usr/lib" for ``libdir``, and so
366forth.
367
368Meanwhile, ``DESTDIR`` is a path within the :term:`Build Directory`.
Patrick Williams2390b1b2022-11-03 13:47:49 -0500369However, when the recipe builds a native program (i.e. one that is
370intended to run on the build machine), that program is never installed
371directly to the build machine's root file system. Consequently, the build
372system uses paths within the Build Directory for ``DESTDIR``, ``bindir``
373and related variables. To better understand this, consider the following
374two paths (artificially broken across lines for readability) where the
375first is relatively normal and the second is not::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500376
377 /home/maxtothemax/poky-bootchart2/build/tmp/work/i586-poky-linux/zlib/
378 1.2.8-r0/sysroot-destdir/usr/bin
379
380 /home/maxtothemax/poky-bootchart2/build/tmp/work/x86_64-linux/
381 zlib-native/1.2.8-r0/sysroot-destdir/home/maxtothemax/poky-bootchart2/
382 build/tmp/sysroots/x86_64-linux/usr/bin
383
Patrick Williams975a06f2022-10-21 14:42:47 -0500384Even if the paths look unusual, they both are correct --- the first for
385a target and the second for a native recipe. These paths are a consequence
386of the ``DESTDIR`` mechanism and while they appear strange, they are correct
387and in practice very effective.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500388
Patrick Williams975a06f2022-10-21 14:42:47 -0500389How do I create images with more free space?
390--------------------------------------------
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500391
Patrick Williams975a06f2022-10-21 14:42:47 -0500392By default, the OpenEmbedded build system creates images that are
3931.3 times the size of the populated root filesystem. To affect the image
394size, you need to set various configurations:
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600395
Patrick Williams975a06f2022-10-21 14:42:47 -0500396- *Image Size:* The OpenEmbedded build system uses the
397 :term:`IMAGE_ROOTFS_SIZE` variable to define
398 the size of the image in Kbytes. The build system determines the size
399 by taking into account the initial root filesystem size before any
400 modifications such as requested size for the image and any requested
401 additional free disk space to be added to the image.
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600402
Patrick Williams975a06f2022-10-21 14:42:47 -0500403- *Overhead:* Use the
404 :term:`IMAGE_OVERHEAD_FACTOR` variable
405 to define the multiplier that the build system applies to the initial
406 image size, which is 1.3 by default.
407
408- *Additional Free Space:* Use the
409 :term:`IMAGE_ROOTFS_EXTRA_SPACE`
410 variable to add additional free space to the image. The build system
411 adds this space to the image after it determines its
412 :term:`IMAGE_ROOTFS_SIZE`.
413
414Why aren't spaces in path names supported?
415------------------------------------------
416
417The Yocto Project team has tried to do this before but too many
418of the tools the OpenEmbedded build system depends on, such as
419``autoconf``, break when they find spaces in pathnames. Until that
420situation changes, the team will not support spaces in pathnames.
421
422I'm adding a binary in a recipe. Why is it different in the image?
423------------------------------------------------------------------
424
425The first most obvious change is the system stripping debug symbols from
426it. Setting :term:`INHIBIT_PACKAGE_STRIP` to stop debug symbols being
427stripped and/or :term:`INHIBIT_PACKAGE_DEBUG_SPLIT` to stop debug symbols
428being split into a separate file will ensure the binary is unchanged.
429
430Issues on the running system
431============================
432
433How do I disable the cursor on my touchscreen device?
434-----------------------------------------------------
435
436You need to create a form factor file as described in the
437":ref:`bsp-guide/bsp:miscellaneous bsp-specific recipe files`" section in
438the Yocto Project Board Support Packages (BSP) Developer's Guide. Set
439the ``HAVE_TOUCHSCREEN`` variable equal to one as follows::
440
441 HAVE_TOUCHSCREEN=1
442
443How to always bring up connected network interfaces?
444----------------------------------------------------
445
446The default interfaces file provided by the netbase recipe does
447not automatically bring up network interfaces. Therefore, you will need
448to add a BSP-specific netbase that includes an interfaces file. See the
449":ref:`bsp-guide/bsp:miscellaneous bsp-specific recipe files`" section in
450the Yocto Project Board Support Packages (BSP) Developer's Guide for
451information on creating these types of miscellaneous recipe files.
452
453For example, add the following files to your layer::
454
455 meta-MACHINE/recipes-bsp/netbase/netbase/MACHINE/interfaces
456 meta-MACHINE/recipes-bsp/netbase/netbase_5.0.bbappend