1.. SPDX-License-Identifier: CC-BY-SA-2.0-UK 2 3*** 4FAQ 5*** 6 7**Q:** How does Poky differ from :oe_home:`OpenEmbedded <>`? 8 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 19Python versions. In particular, I do not have Python 3.5.0 or greater. 20Can 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 24tarball). See the 25":ref:`ref-manual/system-requirements:required git, tar, python and gcc versions`" 26section for steps on how to update your build tools. 27 28**Q:** How can you claim Poky / OpenEmbedded-Core is stable? 29 30**A:** There are three areas that help with stability; 31 32- The Yocto Project team keeps :term:`OpenEmbedded-Core (OE-Core)` small and 33 focused, containing around 830 recipes as opposed to the thousands 34 available in other OpenEmbedded community layers. Keeping it small 35 makes it easy to test and maintain. 36 37- The Yocto Project team runs manual and automated tests using a small, 38 fixed set of reference hardware as well as emulated targets. 39 40- The Yocto Project uses an autobuilder, which provides continuous 41 build and integration tests. 42 43**Q:** How do I get support for my board added to the Yocto Project? 44 45**A:** Support for an additional board is added by creating a Board 46Support Package (BSP) layer for it. For more information on how to 47create a BSP layer, see the 48":ref:`dev-manual/common-tasks:understanding and creating layers`" 49section in the Yocto Project Development Tasks Manual and the 50:doc:`/bsp-guide/index`. 51 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 58LabQuest <https://vernier.com/labquest/>`__ is built using the 59OpenEmbedded build system. See the `Vernier 60LabQuest <https://www.vernier.com/products/interfaces/labq/>`__ website 61for 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 76":ref:`dev-manual/common-tasks:writing a new recipe`" 77section 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 111**A:** Set ``SRC_URI_OVERRIDES_PACKAGE_ARCH`` = "0" in the ``.bb`` file 112but make sure the package is manually marked as machine-specific for the 113case that needs it. The code that handles 114``SRC_URI_OVERRIDES_PACKAGE_ARCH`` is in the 115``meta/classes/base.bbclass`` file. 116 117**Q:** I'm behind a firewall and need to use a proxy server. How do I do 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. 128To use them, remove the comments: :: 129 130 # You can set the default proxies for Wget to use for http, https, and ftp. 131 # They will override the value in the environment. 132 #https_proxy = http://proxy.yoyodyne.com:18023/ 133 #http_proxy = http://proxy.yoyodyne.com:18023/ 134 #ftp_proxy = http://proxy.yoyodyne.com:18023/ 135 136 # If you do not want to use proxy at all, set this to off. 137 #use_proxy = on 138 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 143":yocto_wiki:`Working Behind a Network Proxy </Working_Behind_a_Network_Proxy>`" 144Wiki 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 201":ref:`overview-manual/development-environment:licensing`" 202section in the Yocto 203Project Overview and Concepts Manual and also in the 204":ref:`dev-manual/common-tasks:maintaining open source license compliance during your product's lifecycle`" 205section in the Yocto Project Development Tasks Manual. 206 207**Q:** How do I disable the cursor on my touchscreen device? 208 209**A:** You need to create a form factor file as described in the 210":ref:`bsp-guide/bsp:miscellaneous bsp-specific recipe files`" section in 211the Yocto Project Board Support Packages (BSP) Developer's Guide. Set 212the ``HAVE_TOUCHSCREEN`` variable equal to one as follows: 213:: 214 215 HAVE_TOUCHSCREEN=1 216 217**Q:** How do I make sure connected network interfaces are brought up by 218default? 219 220**A:** The default interfaces file provided by the netbase recipe does 221not automatically bring up network interfaces. Therefore, you will need 222to add a BSP-specific netbase that includes an interfaces file. See the 223":ref:`bsp-guide/bsp:miscellaneous bsp-specific recipe files`" section in 224the Yocto Project Board Support Packages (BSP) Developer's Guide for 225information on creating these types of miscellaneous recipe files. 226 227For example, add the following files to your layer: :: 228 229 meta-MACHINE/recipes-bsp/netbase/netbase/MACHINE/interfaces 230 meta-MACHINE/recipes-bsp/netbase/netbase_5.0.bbappend 231 232**Q:** How do I create images with more free space? 233 234**A:** By default, the OpenEmbedded build system creates images that are 2351.3 times the size of the populated root filesystem. To affect the image 236size, you need to set various configurations: 237 238- *Image Size:* The OpenEmbedded build system uses the 239 :term:`IMAGE_ROOTFS_SIZE` variable to define 240 the size of the image in Kbytes. The build system determines the size 241 by taking into account the initial root filesystem size before any 242 modifications such as requested size for the image and any requested 243 additional free disk space to be added to the image. 244 245- *Overhead:* Use the 246 :term:`IMAGE_OVERHEAD_FACTOR` variable 247 to define the multiplier that the build system applies to the initial 248 image size, which is 1.3 by default. 249 250- *Additional Free Space:* Use the 251 :term:`IMAGE_ROOTFS_EXTRA_SPACE` 252 variable to add additional free space to the image. The build system 253 adds this space to the image after it determines its 254 ``IMAGE_ROOTFS_SIZE``. 255 256**Q:** Why don't you support directories with spaces in the pathnames? 257 258**A:** The Yocto Project team has tried to do this before but too many 259of the tools the OpenEmbedded build system depends on, such as 260``autoconf``, break when they find spaces in pathnames. Until that 261situation changes, the team will not support spaces in pathnames. 262 263**Q:** How do I use an external toolchain? 264 265**A:** The toolchain configuration is very flexible and customizable. It 266is primarily controlled with the ``TCMODE`` variable. This variable 267controls which ``tcmode-*.inc`` file to include from the 268``meta/conf/distro/include`` directory within the :term:`Source Directory`. 269 270The default value of ``TCMODE`` is "default", which tells the 271OpenEmbedded build system to use its internally built toolchain (i.e. 272``tcmode-default.inc``). However, other patterns are accepted. In 273particular, "external-\*" refers to external toolchains. One example is 274the Sourcery G++ Toolchain. The support for this toolchain resides in 275the separate ``meta-sourcery`` layer at 276https://github.com/MentorEmbedded/meta-sourcery/. 277 278In addition to the toolchain configuration, you also need a 279corresponding toolchain recipe file. This recipe file needs to package 280up any pre-built objects in the toolchain such as ``libgcc``, 281``libstdcc++``, any locales, and ``libc``. 282 283**Q:** How does the OpenEmbedded build system obtain source code and 284will it work behind my firewall or proxy server? 285 286**A:** The way the build system obtains source code is highly 287configurable. You can setup the build system to get source code in most 288environments if HTTP transport is available. 289 290When the build system searches for source code, it first tries the local 291download directory. If that location fails, Poky tries 292:term:`PREMIRRORS`, the upstream source, and then 293:term:`MIRRORS` in that order. 294 295Assuming your distribution is "poky", the OpenEmbedded build system uses 296the Yocto Project source ``PREMIRRORS`` by default for SCM-based 297sources, upstreams for normal tarballs, and then falls back to a number 298of other mirrors including the Yocto Project source mirror if those 299fail. 300 301As an example, you could add a specific server for the build system to 302attempt before any others by adding something like the following to the 303``local.conf`` configuration file: :: 304 305 PREMIRRORS_prepend = "\ 306 git://.*/.* http://www.yoctoproject.org/sources/ \n \ 307 ftp://.*/.* http://www.yoctoproject.org/sources/ \n \ 308 http://.*/.* http://www.yoctoproject.org/sources/ \n \ 309 https://.*/.* http://www.yoctoproject.org/sources/ \n" 310 311These changes cause the build system to intercept Git, FTP, HTTP, and 312HTTPS requests and direct them to the ``http://`` sources mirror. You 313can use ``file://`` URLs to point to local directories or network shares 314as well. 315 316Aside from the previous technique, these options also exist: 317:: 318 319 BB_NO_NETWORK = "1" 320 321This statement tells BitBake to issue an error 322instead of trying to access the Internet. This technique is useful if 323you want to ensure code builds only from local sources. 324 325Here is another technique: 326:: 327 328 BB_FETCH_PREMIRRORONLY = "1" 329 330This statement 331limits the build system to pulling source from the ``PREMIRRORS`` only. 332Again, this technique is useful for reproducing builds. 333 334Here is another technique: 335:: 336 337 BB_GENERATE_MIRROR_TARBALLS = "1" 338 339This 340statement tells the build system to generate mirror tarballs. This 341technique is useful if you want to create a mirror server. If not, 342however, the technique can simply waste time during the build. 343 344Finally, consider an example where you are behind an HTTP-only firewall. 345You could make the following changes to the ``local.conf`` configuration 346file as long as the ``PREMIRRORS`` server is current: :: 347 348 PREMIRRORS_prepend = "\ 349 ftp://.*/.* http://www.yoctoproject.org/sources/ \n \ 350 http://.*/.* http://www.yoctoproject.org/sources/ \n \ 351 https://.*/.* http://www.yoctoproject.org/sources/ \n" 352 BB_FETCH_PREMIRRORONLY = "1" 353 354These changes would cause the build system to successfully fetch source 355over HTTP and any network accesses to anything other than the 356``PREMIRRORS`` would fail. 357 358The build system also honors the standard shell environment variables 359``http_proxy``, ``ftp_proxy``, ``https_proxy``, and ``all_proxy`` to 360redirect requests through proxy servers. 361 362.. note:: 363 364 You can find more information on the 365 ":yocto_wiki:`Working Behind a Network Proxy </Working_Behind_a_Network_Proxy>`" 366 Wiki page. 367 368**Q:** Can I get rid of build output so I can start over? 369 370**A:** Yes - you can easily do this. When you use BitBake to build an 371image, all the build output goes into the directory created when you run 372the build environment setup script (i.e. 373:ref:`structure-core-script`). By default, this :term:`Build Directory` 374is named ``build`` but can be named 375anything you want. 376 377Within the Build Directory, is the ``tmp`` directory. To remove all the 378build output yet preserve any source code or downloaded files from 379previous builds, simply remove the ``tmp`` directory. 380 381**Q:** Why do ``${bindir}`` and ``${libdir}`` have strange values for 382``-native`` recipes? 383 384**A:** Executables and libraries might need to be used from a directory 385other than the directory into which they were initially installed. 386Complicating this situation is the fact that sometimes these executables 387and libraries are compiled with the expectation of being run from that 388initial installation target directory. If this is the case, moving them 389causes problems. 390 391This scenario is a fundamental problem for package maintainers of 392mainstream Linux distributions as well as for the OpenEmbedded build 393system. As such, a well-established solution exists. Makefiles, 394Autotools configuration scripts, and other build systems are expected to 395respect environment variables such as ``bindir``, ``libdir``, and 396``sysconfdir`` that indicate where executables, libraries, and data 397reside when a program is actually run. They are also expected to respect 398a ``DESTDIR`` environment variable, which is prepended to all the other 399variables when the build system actually installs the files. It is 400understood that the program does not actually run from within 401``DESTDIR``. 402 403When the OpenEmbedded build system uses a recipe to build a 404target-architecture program (i.e. one that is intended for inclusion on 405the image being built), that program eventually runs from the root file 406system of that image. Thus, the build system provides a value of 407"/usr/bin" for ``bindir``, a value of "/usr/lib" for ``libdir``, and so 408forth. 409 410Meanwhile, ``DESTDIR`` is a path within the :term:`Build Directory`. 411However, when the recipe builds a 412native program (i.e. one that is intended to run on the build machine), 413that program is never installed directly to the build machine's root 414file system. Consequently, the build system uses paths within the Build 415Directory for ``DESTDIR``, ``bindir`` and related variables. To better 416understand this, consider the following two paths where the first is 417relatively normal and the second is not: 418 419.. note:: 420 421 Due to these lengthy examples, the paths are artificially broken 422 across lines for readability. 423 424:: 425 426 /home/maxtothemax/poky-bootchart2/build/tmp/work/i586-poky-linux/zlib/ 427 1.2.8-r0/sysroot-destdir/usr/bin 428 429 /home/maxtothemax/poky-bootchart2/build/tmp/work/x86_64-linux/ 430 zlib-native/1.2.8-r0/sysroot-destdir/home/maxtothemax/poky-bootchart2/ 431 build/tmp/sysroots/x86_64-linux/usr/bin 432 433Even if the paths look unusual, 434they both are correct - the first for a target and the second for a 435native recipe. These paths are a consequence of the ``DESTDIR`` 436mechanism and while they appear strange, they are correct and in 437practice very effective. 438 439**Q:** The files provided by my ``*-native`` recipe do not appear to be 440available to other recipes. Files are missing from the native sysroot, 441my recipe is installing to the wrong place, or I am getting permissions 442errors during the do_install task in my recipe! What is wrong? 443 444**A:** This situation results when a build system does not recognize the 445environment variables supplied to it by :term:`BitBake`. The 446incident that prompted this FAQ entry involved a Makefile that used an 447environment variable named ``BINDIR`` instead of the more standard 448variable ``bindir``. The makefile's hardcoded default value of 449"/usr/bin" worked most of the time, but not for the recipe's ``-native`` 450variant. For another example, permissions errors might be caused by a 451Makefile that ignores ``DESTDIR`` or uses a different name for that 452environment variable. Check the the build system to see if these kinds 453of issues exist. 454 455**Q:** I'm adding a binary in a recipe but it's different in the image, what is 456changing it? 457 458**A:** The first most obvious change is the system stripping debug symbols from 459it. Setting :term:`INHIBIT_PACKAGE_STRIP` to stop debug symbols being stripped and/or 460:term:`INHIBIT_PACKAGE_DEBUG_SPLIT` to stop debug symbols being split into a separate 461file will ensure the binary is unchanged. The other less obvious thing that can 462happen is prelinking of the image. This is set by default in local.conf via 463:term:`USER_CLASSES` which can contain 'image-prelink'. If you remove that, the 464image will not be prelinked meaning the binaries would be unchanged. 465