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 48Building environment 49==================== 50 51Missing dependencies on the development system? 52----------------------------------------------- 53 54If 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. 59 60How does OpenEmbedded fetch source code? Will it work through a firewall or proxy server? 61----------------------------------------------------------------------------------------- 62 63The way the build system obtains source code is highly 64configurable. 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 73the Yocto Project source :term:`PREMIRRORS` by default for SCM-based 74sources, 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 80``local.conf`` configuration file:: 81 82 PREMIRRORS:prepend = "\ 83 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/" 87 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 93Another option is to set:: 94 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 101Here is another technique:: 102 103 BB_FETCH_PREMIRRORONLY = "1" 104 105This statement limits the build system to pulling source from the 106:term:`PREMIRRORS` only. Again, this technique is useful for reproducing 107builds. 108 109Here is yet another technique:: 110 111 BB_GENERATE_MIRROR_TARBALLS = "1" 112 113This statement tells the build system to generate mirror tarballs. This 114technique 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 119file as long as the :term:`PREMIRRORS` server is current:: 120 121 PREMIRRORS:prepend = "\ 122 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/" 126 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 130:term:`PREMIRRORS` would fail. 131 132Most 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 138Here 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. 158 159.. note:: 160 161 You can find more information on the 162 ":yocto_wiki:`Working Behind a Network Proxy </Working_Behind_a_Network_Proxy>`" 163 Wiki page. 164 165Using the OpenEmbedded Build system 166=================================== 167 168How do I use an external toolchain? 169----------------------------------- 170 171See the ":ref:`dev-manual/external-toolchain:optionally using an external toolchain`" 172section in the Development Task manual. 173 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 253image, all the build output goes into the directory created when you run 254the build environment setup script (i.e. :ref:`structure-core-script`). 255By default, this :term:`Build Directory` is named ``build`` but can be named 256anything you want. 257 258Within the :term:`Build Directory`, is the ``tmp`` directory. To remove all the 259build output yet preserve any source code or downloaded files from 260previous builds, simply remove the ``tmp`` directory. 261 262Customizing generated images 263============================ 264 265What 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 279":ref:`dev-manual/layers:understanding and creating layers`" 280section 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 291":ref:`dev-manual/new-recipe:writing a new recipe`" 292section 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 308":ref:`dev-manual/licenses:maintaining open source license compliance during your product's lifecycle`" 309section 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 343other 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`. 369However, 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:: 376 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 384Even 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. 388 389How do I create images with more free space? 390-------------------------------------------- 391 392By 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: 395 396- *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. 402 403- *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 457