1.. SPDX-License-Identifier: CC-BY-SA-2.0-UK 2 3*** 4FAQ 5*** 6 7.. contents:: 8 9General questions 10================= 11 12How does Poky differ from OpenEmbedded? 13--------------------------------------- 14 15The term ``Poky`` refers to the specific reference build 16system 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 24How can you claim Poky / OpenEmbedded-Core is stable? 25----------------------------------------------------- 26 27There are three areas that help with stability; 28 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 37- The Yocto Project uses an :yocto_ab:`autobuilder <>`, which provides 38 continuous build and integration tests. 39 40Are there any products built using the OpenEmbedded build system? 41----------------------------------------------------------------- 42 43See :yocto_wiki:`Products that use the Yocto Project 44</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. 47 48Why isn't systemd the default init system for OpenEmbedded-Core/Yocto Project or in Poky? 49----------------------------------------------------------------------------------------- 50 51`systemd <https://systemd.io/>`__ is a desktop Linux init system with a specific 52focus that is not entirely aligned with a customisable "embedded" build 53system/environment. 54 55It understandably mandates certain layouts and configurations which may 56or may not align with what the objectives and direction :term:`OpenEmbedded-Core 57(OE-Core)` or Yocto Project want to take. It doesn't support all of our targets. 58For example `musl <https://www.musl-libc.org/>`__ support in systemd is 59problematic. 60 61If it were our default, we would have to align with all their choices 62and this doesn't make sense. It is therefore a configuration option and 63available to anyone where the design goals align. But we are clear it 64is not the only way to handle init. 65 66Our automated testing includes it through the ``poky-altcfg`` :term:`DISTRO` and 67we don't really need it to be the default: it is tested, it works, and people 68can choose to use it. 69 70Building environment 71==================== 72 73Missing dependencies on the development system? 74----------------------------------------------- 75 76If your development system does not meet the required Git, tar, and 77Python versions, you can get the required tools on your host development 78system in different ways (i.e. building a tarball or downloading a 79tarball). See the ":ref:`ref-manual/system-requirements:required git, tar, python, make and gcc versions`" 80section for steps on how to update your build tools. 81 82How does OpenEmbedded fetch source code? Will it work through a firewall or proxy server? 83----------------------------------------------------------------------------------------- 84 85The way the build system obtains source code is highly 86configurable. You can setup the build system to get source code in most 87environments if HTTP transport is available. 88 89When the build system searches for source code, it first tries the local 90download directory. If that location fails, Poky tries 91:term:`PREMIRRORS`, the upstream source, and then 92:term:`MIRRORS` in that order. 93 94Assuming your distribution is "poky", the OpenEmbedded build system uses 95the Yocto Project source :term:`PREMIRRORS` by default for SCM-based 96sources, upstreams for normal tarballs, and then falls back to a number 97of other mirrors including the Yocto Project source mirror if those 98fail. 99 100As an example, you could add a specific server for the build system to 101attempt before any others by adding something like the following to the 102``local.conf`` configuration file:: 103 104 PREMIRRORS:prepend = "\ 105 git://.*/.* &YOCTO_DL_URL;/mirror/sources/ \ 106 ftp://.*/.* &YOCTO_DL_URL;/mirror/sources/ \ 107 http://.*/.* &YOCTO_DL_URL;/mirror/sources/ \ 108 https://.*/.* &YOCTO_DL_URL;/mirror/sources/" 109 110These changes cause the build system to intercept Git, FTP, HTTP, and 111HTTPS requests and direct them to the ``http://`` sources mirror. You 112can use ``file://`` URLs to point to local directories or network shares 113as well. 114 115Another option is to set:: 116 117 BB_NO_NETWORK = "1" 118 119This statement tells BitBake to issue an error 120instead of trying to access the Internet. This technique is useful if 121you want to ensure code builds only from local sources. 122 123Here is another technique:: 124 125 BB_FETCH_PREMIRRORONLY = "1" 126 127This statement limits the build system to pulling source from the 128:term:`PREMIRRORS` only. Again, this technique is useful for reproducing 129builds. 130 131Here is yet another technique:: 132 133 BB_GENERATE_MIRROR_TARBALLS = "1" 134 135This statement tells the build system to generate mirror tarballs. This 136technique is useful if you want to create a mirror server. If not, 137however, the technique can simply waste time during the build. 138 139Finally, consider an example where you are behind an HTTP-only firewall. 140You could make the following changes to the ``local.conf`` configuration 141file as long as the :term:`PREMIRRORS` server is current:: 142 143 PREMIRRORS:prepend = "\ 144 git://.*/.* &YOCTO_DL_URL;/mirror/sources/ \ 145 ftp://.*/.* &YOCTO_DL_URL;/mirror/sources/ \ 146 http://.*/.* &YOCTO_DL_URL;/mirror/sources/ \ 147 https://.*/.* &YOCTO_DL_URL;/mirror/sources/" 148 BB_FETCH_PREMIRRORONLY = "1" 149 150These changes would cause the build system to successfully fetch source 151over HTTP and any network accesses to anything other than the 152:term:`PREMIRRORS` would fail. 153 154Most source fetching by the OpenEmbedded build system is done by 155``wget`` and you therefore need to specify the proxy settings in a 156``.wgetrc`` file, which can be in your home directory if you are a 157single user or can be in ``/usr/local/etc/wgetrc`` as a global user 158file. 159 160Here is the applicable code for setting various proxy types in the 161``.wgetrc`` file. By default, these settings are disabled with comments. 162To use them, remove the comments:: 163 164 # You can set the default proxies for Wget to use for http, https, and ftp. 165 # They will override the value in the environment. 166 #https_proxy = http://proxy.yoyodyne.com:18023/ 167 #http_proxy = http://proxy.yoyodyne.com:18023/ 168 #ftp_proxy = http://proxy.yoyodyne.com:18023/ 169 170 # If you do not want to use proxy at all, set this to off. 171 #use_proxy = on 172 173The build system also accepts ``http_proxy``, ``ftp_proxy``, ``https_proxy``, 174and ``all_proxy`` set as to standard shell environment variables to redirect 175requests through proxy servers. 176 177The Yocto Project also includes a 178``meta-poky/conf/templates/default/site.conf.sample`` file that shows 179how to configure CVS and Git proxy servers if needed. 180 181.. note:: 182 183 You can find more information on the 184 ":yocto_wiki:`Working Behind a Network Proxy </Working_Behind_a_Network_Proxy>`" 185 Wiki page. 186 187Using the OpenEmbedded Build system 188=================================== 189 190How do I use an external toolchain? 191----------------------------------- 192 193See the ":ref:`dev-manual/external-toolchain:optionally using an external toolchain`" 194section in the Development Task manual. 195 196Why do I get chmod permission issues? 197------------------------------------- 198 199If you see the error 200``chmod: XXXXX new permissions are r-xrwxrwx, not r-xr-xr-x``, 201you are probably running the build on an NTFS filesystem. Instead, 202run the build system on a partition with a modern Linux filesystem such as 203``ext4``, ``btrfs`` or ``xfs``. 204 205I see many 404 errors trying to download sources. Is anything wrong? 206-------------------------------------------------------------------- 207 208Nothing is wrong. The OpenEmbedded build system checks any 209configured source mirrors before downloading from the upstream sources. 210The build system does this searching for both source archives and 211pre-checked out versions of SCM-managed software. These checks help in 212large installations because it can reduce load on the SCM servers 213themselves. This can also allow builds to continue to work if an 214upstream source disappears. 215 216Why do I get random build failures? 217----------------------------------- 218 219If the same build is failing in totally different and random 220ways, the most likely explanation is: 221 222- The hardware you are running the build on has some problem. 223 224- You are running the build under virtualization, in which case the 225 virtualization probably has bugs. 226 227The OpenEmbedded build system processes a massive amount of data that 228causes lots of network, disk and CPU activity and is sensitive to even 229single-bit failures in any of these areas. True random failures have 230always been traced back to hardware or virtualization issues. 231 232Why does the build fail with ``iconv.h`` problems? 233-------------------------------------------------- 234 235When you try to build a native recipe, you may get an error message that 236indicates that GNU ``libiconv`` is not in use but ``iconv.h`` has been 237included from ``libiconv``:: 238 239 #error GNU libiconv not in use but included iconv.h is from libiconv 240 241When this happens, you need to check whether you have a previously 242installed version of the header file in ``/usr/local/include/``. 243If that's the case, you should either uninstall it or temporarily rename 244it and try the build again. 245 246This issue is just a single manifestation of "system leakage" issues 247caused when the OpenEmbedded build system finds and uses previously 248installed files during a native build. This type of issue might not be 249limited to ``iconv.h``. Make sure that leakage cannot occur from 250``/usr/local/include`` and ``/opt`` locations. 251 252Why don't other recipes find the files provided by my ``*-native`` recipe? 253-------------------------------------------------------------------------- 254 255Files provided by your native recipe could be missing from the native 256sysroot, your recipe could also be installing to the wrong place, or you 257could be getting permission errors during the :ref:`ref-tasks-install` 258task in your recipe. 259 260This situation happens when the build system used by a package does not 261recognize the environment variables supplied to it by :term:`BitBake`. The 262incident that prompted this FAQ entry involved a Makefile that used an 263environment variable named ``BINDIR`` instead of the more standard 264variable ``bindir``. The makefile's hardcoded default value of 265"/usr/bin" worked most of the time, but not for the recipe's ``-native`` 266variant. For another example, permission errors might be caused by a 267Makefile that ignores ``DESTDIR`` or uses a different name for that 268environment variable. Check the build system of the package to see if 269these kinds of issues exist. 270 271Can I get rid of build output so I can start over? 272-------------------------------------------------- 273 274Yes --- you can easily do this. When you use BitBake to build an 275image, all the build output goes into the directory created when you run 276the build environment setup script (i.e. :ref:`structure-core-script`). 277By default, this :term:`Build Directory` is named ``build`` but can be named 278anything you want. 279 280Within the :term:`Build Directory`, is the ``tmp`` directory. To remove all the 281build output yet preserve any source code or downloaded files from 282previous builds, simply remove the ``tmp`` directory. 283 284Why isn't there a way to append bbclass files like bbappend for recipes? 285------------------------------------------------------------------------ 286 287The Yocto Project has consciously chosen not to implement such functionality. 288Class code is designed to be shared and reused, and exposes some level of 289configuration to its users. We want to encourage people to share these changes 290so we can build the best classes. 291 292If the ``append`` functionality was available for classes, our evidence and 293experience suggest that people would create their custom changes in their 294layer instead of sharing and discussing the issues and/or limitations they 295encountered. This would lead to bizarre class interactions when new layers are 296included. We therefore consciously choose to have a natural pressure to share 297class code improvements or fixes. 298 299There are also technical considerations like which recipes a class append would 300apply to and how that would fit within the layer model. These are complications 301we think we can live without! 302 303Customizing generated images 304============================ 305 306What does the OpenEmbedded build system produce as output? 307---------------------------------------------------------- 308 309Because you can use the same set of recipes to create output of 310various formats, the output of an OpenEmbedded build depends on how you 311start it. Usually, the output is a flashable image ready for the target 312device. 313 314How do I make the Yocto Project support my board? 315------------------------------------------------- 316 317Support for an additional board is added by creating a Board 318Support Package (BSP) layer for it. For more information on how to 319create a BSP layer, see the 320":ref:`dev-manual/layers:understanding and creating layers`" 321section in the Yocto Project Development Tasks Manual and the 322:doc:`/bsp-guide/index`. 323 324Usually, if the board is not completely exotic, adding support in the 325Yocto Project is fairly straightforward. 326 327How do I make the Yocto Project support my package? 328--------------------------------------------------- 329 330To add a package, you need to create a BitBake recipe. For 331information on how to create a BitBake recipe, see the 332":ref:`dev-manual/new-recipe:writing a new recipe`" 333section in the Yocto Project Development Tasks Manual. 334 335What do I need to ship for license compliance? 336---------------------------------------------- 337 338This is a difficult question and you need to consult your lawyer 339for the answer for your specific case. It is worth bearing in mind that 340for GPL compliance, there needs to be enough information shipped to 341allow someone else to rebuild and produce the same end result you are 342shipping. This means sharing the source code, any patches applied to it, 343and also any configuration information about how that package was 344configured and built. 345 346You can find more information on licensing in the 347":ref:`overview-manual/development-environment:licensing`" 348section in the Yocto Project Overview and Concepts Manual and also in the 349":ref:`dev-manual/licenses:maintaining open source license compliance during your product's lifecycle`" 350section in the Yocto Project Development Tasks Manual. 351 352Do I have to make a full reflash after recompiling one package? 353--------------------------------------------------------------- 354 355The OpenEmbedded build system can build packages in various 356formats such as IPK for OPKG, Debian package (``.deb``), or RPM. You can 357then upgrade only the modified packages using the package tools on the device, 358much like on a desktop distribution such as Ubuntu or Fedora. However, 359package management on the target is entirely optional. 360 361How to prevent my package from being marked as machine specific? 362---------------------------------------------------------------- 363 364If you have machine-specific data in a package for one machine only 365but the package is being marked as machine-specific in all cases, 366you can set :term:`SRC_URI_OVERRIDES_PACKAGE_ARCH` = "0" in the ``.bb`` file. 367However, but make sure the package is manually marked as machine-specific for the 368case that needs it. The code that handles :term:`SRC_URI_OVERRIDES_PACKAGE_ARCH` 369is in the ``meta/classes-global/base.bbclass`` file. 370 371What's the difference between ``target`` and ``target-native``? 372--------------------------------------------------------------- 373 374The ``*-native`` targets are designed to run on the system being 375used for the build. These are usually tools that are needed to assist 376the build in some way such as ``quilt-native``, which is used to apply 377patches. The non-native version is the one that runs on the target 378device. 379 380Why do ``${bindir}`` and ``${libdir}`` have strange values for ``-native`` recipes? 381----------------------------------------------------------------------------------- 382 383Executables and libraries might need to be used from a directory 384other than the directory into which they were initially installed. 385Complicating this situation is the fact that sometimes these executables 386and libraries are compiled with the expectation of being run from that 387initial installation target directory. If this is the case, moving them 388causes problems. 389 390This scenario is a fundamental problem for package maintainers of 391mainstream Linux distributions as well as for the OpenEmbedded build 392system. As such, a well-established solution exists. Makefiles, 393Autotools configuration scripts, and other build systems are expected to 394respect environment variables such as ``bindir``, ``libdir``, and 395``sysconfdir`` that indicate where executables, libraries, and data 396reside when a program is actually run. They are also expected to respect 397a ``DESTDIR`` environment variable, which is prepended to all the other 398variables when the build system actually installs the files. It is 399understood that the program does not actually run from within 400``DESTDIR``. 401 402When the OpenEmbedded build system uses a recipe to build a 403target-architecture program (i.e. one that is intended for inclusion on 404the image being built), that program eventually runs from the root file 405system of that image. Thus, the build system provides a value of 406"/usr/bin" for ``bindir``, a value of "/usr/lib" for ``libdir``, and so 407forth. 408 409Meanwhile, ``DESTDIR`` is a path within the :term:`Build Directory`. 410However, when the recipe builds a native program (i.e. one that is 411intended to run on the build machine), that program is never installed 412directly to the build machine's root file system. Consequently, the build 413system uses paths within the Build Directory for ``DESTDIR``, ``bindir`` 414and related variables. To better understand this, consider the following 415two paths (artificially broken across lines for readability) where the 416first is relatively normal and the second is not:: 417 418 /home/maxtothemax/poky-bootchart2/build/tmp/work/i586-poky-linux/zlib/ 419 1.2.8-r0/sysroot-destdir/usr/bin 420 421 /home/maxtothemax/poky-bootchart2/build/tmp/work/x86_64-linux/ 422 zlib-native/1.2.8-r0/sysroot-destdir/home/maxtothemax/poky-bootchart2/ 423 build/tmp/sysroots/x86_64-linux/usr/bin 424 425Even if the paths look unusual, they both are correct --- the first for 426a target and the second for a native recipe. These paths are a consequence 427of the ``DESTDIR`` mechanism and while they appear strange, they are correct 428and in practice very effective. 429 430How do I create images with more free space? 431-------------------------------------------- 432 433By default, the OpenEmbedded build system creates images that are 4341.3 times the size of the populated root filesystem. To affect the image 435size, you need to set various configurations: 436 437- *Image Size:* The OpenEmbedded build system uses the 438 :term:`IMAGE_ROOTFS_SIZE` variable to define 439 the size of the image in Kbytes. The build system determines the size 440 by taking into account the initial root filesystem size before any 441 modifications such as requested size for the image and any requested 442 additional free disk space to be added to the image. 443 444- *Overhead:* Use the 445 :term:`IMAGE_OVERHEAD_FACTOR` variable 446 to define the multiplier that the build system applies to the initial 447 image size, which is 1.3 by default. 448 449- *Additional Free Space:* Use the 450 :term:`IMAGE_ROOTFS_EXTRA_SPACE` 451 variable to add additional free space to the image. The build system 452 adds this space to the image after it determines its 453 :term:`IMAGE_ROOTFS_SIZE`. 454 455Why aren't spaces in path names supported? 456------------------------------------------ 457 458The Yocto Project team has tried to do this before but too many 459of the tools the OpenEmbedded build system depends on, such as 460``autoconf``, break when they find spaces in pathnames. Until that 461situation changes, the team will not support spaces in pathnames. 462 463I'm adding a binary in a recipe. Why is it different in the image? 464------------------------------------------------------------------ 465 466The first most obvious change is the system stripping debug symbols from 467it. Setting :term:`INHIBIT_PACKAGE_STRIP` to stop debug symbols being 468stripped and/or :term:`INHIBIT_PACKAGE_DEBUG_SPLIT` to stop debug symbols 469being split into a separate file will ensure the binary is unchanged. 470 471Issues on the running system 472============================ 473 474How do I disable the cursor on my touchscreen device? 475----------------------------------------------------- 476 477You need to create a form factor file as described in the 478":ref:`bsp-guide/bsp:miscellaneous bsp-specific recipe files`" section in 479the Yocto Project Board Support Packages (BSP) Developer's Guide. Set 480the ``HAVE_TOUCHSCREEN`` variable equal to one as follows:: 481 482 HAVE_TOUCHSCREEN=1 483 484How to always bring up connected network interfaces? 485---------------------------------------------------- 486 487The default interfaces file provided by the netbase recipe does 488not automatically bring up network interfaces. Therefore, you will need 489to add a BSP-specific netbase that includes an interfaces file. See the 490":ref:`bsp-guide/bsp:miscellaneous bsp-specific recipe files`" section in 491the Yocto Project Board Support Packages (BSP) Developer's Guide for 492information on creating these types of miscellaneous recipe files. 493 494For example, add the following files to your layer:: 495 496 meta-MACHINE/recipes-bsp/netbase/netbase/MACHINE/interfaces 497 meta-MACHINE/recipes-bsp/netbase/netbase_5.0.bbappend 498