| .. SPDX-License-Identifier: CC-BY-SA-2.0-UK |
| |
| *** |
| FAQ |
| *** |
| |
| .. contents:: |
| |
| General questions |
| ================= |
| |
| How does Poky differ from OpenEmbedded? |
| --------------------------------------- |
| |
| The term ``Poky`` refers to the specific reference build |
| system that the Yocto Project provides. Poky is based on |
| :term:`OpenEmbedded-Core (OE-Core)` and :term:`BitBake`. Thus, the |
| generic term used here for the build system is the "OpenEmbedded build |
| system." Development in the Yocto Project using Poky is closely tied to |
| OpenEmbedded, with changes always being merged to OE-Core or BitBake |
| first before being pulled back into Poky. This practice benefits both |
| projects immediately. |
| |
| How can you claim Poky / OpenEmbedded-Core is stable? |
| ----------------------------------------------------- |
| |
| There are three areas that help with stability; |
| |
| - The Yocto Project team keeps :term:`OpenEmbedded-Core (OE-Core)` small and |
| focused, containing around 830 recipes as opposed to the thousands |
| available in other OpenEmbedded community layers. Keeping it small |
| makes it easy to test and maintain. |
| |
| - The Yocto Project team runs manual and automated tests using a small, |
| fixed set of reference hardware as well as emulated targets. |
| |
| - The Yocto Project uses an :yocto_ab:`autobuilder <>`, which provides |
| continuous build and integration tests. |
| |
| Are there any products built using the OpenEmbedded build system? |
| ----------------------------------------------------------------- |
| |
| See :yocto_wiki:`Products that use the Yocto Project |
| </Project_Users#Products_that_use_the_Yocto_Project>` in the Yocto Project |
| Wiki. Don't hesitate to contribute to this page if you know other such |
| products. |
| |
| Building environment |
| ==================== |
| |
| Missing dependencies on the development system? |
| ----------------------------------------------- |
| |
| If your development system does not meet the required Git, tar, and |
| Python versions, you can get the required tools on your host development |
| system in different ways (i.e. building a tarball or downloading a |
| tarball). See the ":ref:`ref-manual/system-requirements:required git, tar, python, make and gcc versions`" |
| section for steps on how to update your build tools. |
| |
| How does OpenEmbedded fetch source code? Will it work through a firewall or proxy server? |
| ----------------------------------------------------------------------------------------- |
| |
| The way the build system obtains source code is highly |
| configurable. You can setup the build system to get source code in most |
| environments if HTTP transport is available. |
| |
| When the build system searches for source code, it first tries the local |
| download directory. If that location fails, Poky tries |
| :term:`PREMIRRORS`, the upstream source, and then |
| :term:`MIRRORS` in that order. |
| |
| Assuming your distribution is "poky", the OpenEmbedded build system uses |
| the Yocto Project source :term:`PREMIRRORS` by default for SCM-based |
| sources, upstreams for normal tarballs, and then falls back to a number |
| of other mirrors including the Yocto Project source mirror if those |
| fail. |
| |
| As an example, you could add a specific server for the build system to |
| attempt before any others by adding something like the following to the |
| ``local.conf`` configuration file:: |
| |
| PREMIRRORS:prepend = "\ |
| git://.*/.* &YOCTO_DL_URL;/mirror/sources/ \ |
| ftp://.*/.* &YOCTO_DL_URL;/mirror/sources/ \ |
| http://.*/.* &YOCTO_DL_URL;/mirror/sources/ \ |
| https://.*/.* &YOCTO_DL_URL;/mirror/sources/" |
| |
| These changes cause the build system to intercept Git, FTP, HTTP, and |
| HTTPS requests and direct them to the ``http://`` sources mirror. You |
| can use ``file://`` URLs to point to local directories or network shares |
| as well. |
| |
| Here are other options:: |
| |
| BB_NO_NETWORK = "1" |
| |
| This statement tells BitBake to issue an error |
| instead of trying to access the Internet. This technique is useful if |
| you want to ensure code builds only from local sources. |
| |
| Here is another technique:: |
| |
| BB_FETCH_PREMIRRORONLY = "1" |
| |
| This statement limits the build system to pulling source from the |
| :term:`PREMIRRORS` only. Again, this technique is useful for reproducing |
| builds. |
| |
| Here is another technique:: |
| |
| BB_GENERATE_MIRROR_TARBALLS = "1" |
| |
| This statement tells the build system to generate mirror tarballs. This |
| technique is useful if you want to create a mirror server. If not, |
| however, the technique can simply waste time during the build. |
| |
| Finally, consider an example where you are behind an HTTP-only firewall. |
| You could make the following changes to the ``local.conf`` configuration |
| file as long as the :term:`PREMIRRORS` server is current:: |
| |
| PREMIRRORS:prepend = "\ |
| git://.*/.* &YOCTO_DL_URL;/mirror/sources/ \ |
| ftp://.*/.* &YOCTO_DL_URL;/mirror/sources/ \ |
| http://.*/.* &YOCTO_DL_URL;/mirror/sources/ \ |
| https://.*/.* &YOCTO_DL_URL;/mirror/sources/" |
| BB_FETCH_PREMIRRORONLY = "1" |
| |
| These changes would cause the build system to successfully fetch source |
| over HTTP and any network accesses to anything other than the |
| :term:`PREMIRRORS` would fail. |
| |
| Most source fetching by the OpenEmbedded build system is done by |
| ``wget`` and you therefore need to specify the proxy settings in a |
| ``.wgetrc`` file, which can be in your home directory if you are a |
| single user or can be in ``/usr/local/etc/wgetrc`` as a global user |
| file. |
| |
| Following is the applicable code for setting various proxy types in the |
| ``.wgetrc`` file. By default, these settings are disabled with comments. |
| To use them, remove the comments:: |
| |
| # You can set the default proxies for Wget to use for http, https, and ftp. |
| # They will override the value in the environment. |
| #https_proxy = http://proxy.yoyodyne.com:18023/ |
| #http_proxy = http://proxy.yoyodyne.com:18023/ |
| #ftp_proxy = http://proxy.yoyodyne.com:18023/ |
| |
| # If you do not want to use proxy at all, set this to off. |
| #use_proxy = on |
| |
| The build system also accepts ``http_proxy``, ``ftp_proxy``, ``https_proxy``, |
| and ``all_proxy`` set as to standard shell environment variables to redirect |
| requests through proxy servers. |
| |
| The Yocto Project also includes a |
| ``meta-poky/conf/templates/default/site.conf.sample`` file that shows |
| how to configure CVS and Git proxy servers if needed. |
| |
| .. note:: |
| |
| You can find more information on the |
| ":yocto_wiki:`Working Behind a Network Proxy </Working_Behind_a_Network_Proxy>`" |
| Wiki page. |
| |
| Using the OpenEmbedded Build system |
| =================================== |
| |
| How do I use an external toolchain? |
| ----------------------------------- |
| |
| The toolchain configuration is very flexible and customizable. It |
| is primarily controlled with the :term:`TCMODE` variable. This variable |
| controls which ``tcmode-*.inc`` file to include from the |
| ``meta/conf/distro/include`` directory within the :term:`Source Directory`. |
| |
| The default value of :term:`TCMODE` is "default", which tells the |
| OpenEmbedded build system to use its internally built toolchain (i.e. |
| ``tcmode-default.inc``). However, other patterns are accepted. In |
| particular, "external-\*" refers to external toolchains. One example is |
| the Sourcery G++ Toolchain. The support for this toolchain resides in |
| the separate ``meta-sourcery`` layer at |
| https://github.com/MentorEmbedded/meta-sourcery/. |
| |
| In addition to the toolchain configuration, you also need a |
| corresponding toolchain recipe file. This recipe file needs to package |
| up any pre-built objects in the toolchain such as ``libgcc``, |
| ``libstdcc++``, any locales, and ``libc``. |
| |
| Why do I get chmod permission issues? |
| ------------------------------------- |
| |
| If you see the error |
| ``chmod: XXXXX new permissions are r-xrwxrwx, not r-xr-xr-x``, |
| you are probably running the build on an NTFS filesystem. Instead, |
| run the build system on a partition with a modern Linux filesystem such as |
| ``ext4``, ``btrfs`` or ``xfs``. |
| |
| I see many 404 errors trying to download sources. Is anything wrong? |
| -------------------------------------------------------------------- |
| |
| Nothing is wrong. The OpenEmbedded build system checks any |
| configured source mirrors before downloading from the upstream sources. |
| The build system does this searching for both source archives and |
| pre-checked out versions of SCM-managed software. These checks help in |
| large installations because it can reduce load on the SCM servers |
| themselves. This can also allow builds to continue to work if an |
| upstream source disappears. |
| |
| Why do I get random build failures? |
| ----------------------------------- |
| |
| If the same build is failing in totally different and random |
| ways, the most likely explanation is: |
| |
| - The hardware you are running the build on has some problem. |
| |
| - You are running the build under virtualization, in which case the |
| virtualization probably has bugs. |
| |
| The OpenEmbedded build system processes a massive amount of data that |
| causes lots of network, disk and CPU activity and is sensitive to even |
| single-bit failures in any of these areas. True random failures have |
| always been traced back to hardware or virtualization issues. |
| |
| Why does the build fail with ``iconv.h`` problems? |
| -------------------------------------------------- |
| |
| When you try to build a native recipe, you may get an error message that |
| indicates that GNU ``libiconv`` is not in use but ``iconv.h`` has been |
| included from ``libiconv``:: |
| |
| #error GNU libiconv not in use but included iconv.h is from libiconv |
| |
| When this happens, you need to check whether you have a previously |
| installed version of the header file in ``/usr/local/include/``. |
| If that's the case, you should either uninstall it or temporarily rename |
| it and try the build again. |
| |
| This issue is just a single manifestation of "system leakage" issues |
| caused when the OpenEmbedded build system finds and uses previously |
| installed files during a native build. This type of issue might not be |
| limited to ``iconv.h``. Make sure that leakage cannot occur from |
| ``/usr/local/include`` and ``/opt`` locations. |
| |
| Why don't other recipes find the files provided by my ``*-native`` recipe? |
| -------------------------------------------------------------------------- |
| |
| Files provided by your native recipe could be missing from the native |
| sysroot, your recipe could also be installing to the wrong place, or you |
| could be getting permission errors during the :ref:`ref-tasks-install` |
| task in your recipe. |
| |
| This situation happens when the build system used by a package does not |
| recognize the environment variables supplied to it by :term:`BitBake`. The |
| incident that prompted this FAQ entry involved a Makefile that used an |
| environment variable named ``BINDIR`` instead of the more standard |
| variable ``bindir``. The makefile's hardcoded default value of |
| "/usr/bin" worked most of the time, but not for the recipe's ``-native`` |
| variant. For another example, permission errors might be caused by a |
| Makefile that ignores ``DESTDIR`` or uses a different name for that |
| environment variable. Check the build system of the package to see if |
| these kinds of issues exist. |
| |
| Can I get rid of build output so I can start over? |
| -------------------------------------------------- |
| |
| Yes --- you can easily do this. When you use BitBake to build an |
| image, all the build output goes into the directory created when you run |
| the build environment setup script (i.e. :ref:`structure-core-script`). |
| By default, this :term:`Build Directory` is named ``build`` but can be named |
| anything you want. |
| |
| Within the :term:`Build Directory`, is the ``tmp`` directory. To remove all the |
| build output yet preserve any source code or downloaded files from |
| previous builds, simply remove the ``tmp`` directory. |
| |
| Customizing generated images |
| ============================ |
| |
| What does the OpenEmbedded build system produce as output? |
| ---------------------------------------------------------- |
| |
| Because you can use the same set of recipes to create output of |
| various formats, the output of an OpenEmbedded build depends on how you |
| start it. Usually, the output is a flashable image ready for the target |
| device. |
| |
| How do I make the Yocto Project support my board? |
| ------------------------------------------------- |
| |
| Support for an additional board is added by creating a Board |
| Support Package (BSP) layer for it. For more information on how to |
| create a BSP layer, see the |
| ":ref:`dev-manual/common-tasks:understanding and creating layers`" |
| section in the Yocto Project Development Tasks Manual and the |
| :doc:`/bsp-guide/index`. |
| |
| Usually, if the board is not completely exotic, adding support in the |
| Yocto Project is fairly straightforward. |
| |
| How do I make the Yocto Project support my package? |
| --------------------------------------------------- |
| |
| To add a package, you need to create a BitBake recipe. For |
| information on how to create a BitBake recipe, see the |
| ":ref:`dev-manual/common-tasks:writing a new recipe`" |
| section in the Yocto Project Development Tasks Manual. |
| |
| What do I need to ship for license compliance? |
| ---------------------------------------------- |
| |
| This is a difficult question and you need to consult your lawyer |
| for the answer for your specific case. It is worth bearing in mind that |
| for GPL compliance, there needs to be enough information shipped to |
| allow someone else to rebuild and produce the same end result you are |
| shipping. This means sharing the source code, any patches applied to it, |
| and also any configuration information about how that package was |
| configured and built. |
| |
| You can find more information on licensing in the |
| ":ref:`overview-manual/development-environment:licensing`" |
| section in the Yocto Project Overview and Concepts Manual and also in the |
| ":ref:`dev-manual/common-tasks:maintaining open source license compliance during your product's lifecycle`" |
| section in the Yocto Project Development Tasks Manual. |
| |
| Do I have to make a full reflash after recompiling one package? |
| --------------------------------------------------------------- |
| |
| The OpenEmbedded build system can build packages in various |
| formats such as IPK for OPKG, Debian package (``.deb``), or RPM. You can |
| then upgrade only the modified packages using the package tools on the device, |
| much like on a desktop distribution such as Ubuntu or Fedora. However, |
| package management on the target is entirely optional. |
| |
| How to prevent my package from being marked as machine specific? |
| ---------------------------------------------------------------- |
| |
| If you have machine-specific data in a package for one machine only |
| but the package is being marked as machine-specific in all cases, |
| you can set :term:`SRC_URI_OVERRIDES_PACKAGE_ARCH` = "0" in the ``.bb`` file. |
| However, but make sure the package is manually marked as machine-specific for the |
| case that needs it. The code that handles :term:`SRC_URI_OVERRIDES_PACKAGE_ARCH` |
| is in the ``meta/classes-global/base.bbclass`` file. |
| |
| What's the difference between ``target`` and ``target-native``? |
| --------------------------------------------------------------- |
| |
| The ``*-native`` targets are designed to run on the system being |
| used for the build. These are usually tools that are needed to assist |
| the build in some way such as ``quilt-native``, which is used to apply |
| patches. The non-native version is the one that runs on the target |
| device. |
| |
| Why do ``${bindir}`` and ``${libdir}`` have strange values for ``-native`` recipes? |
| ----------------------------------------------------------------------------------- |
| |
| Executables and libraries might need to be used from a directory |
| other than the directory into which they were initially installed. |
| Complicating this situation is the fact that sometimes these executables |
| and libraries are compiled with the expectation of being run from that |
| initial installation target directory. If this is the case, moving them |
| causes problems. |
| |
| This scenario is a fundamental problem for package maintainers of |
| mainstream Linux distributions as well as for the OpenEmbedded build |
| system. As such, a well-established solution exists. Makefiles, |
| Autotools configuration scripts, and other build systems are expected to |
| respect environment variables such as ``bindir``, ``libdir``, and |
| ``sysconfdir`` that indicate where executables, libraries, and data |
| reside when a program is actually run. They are also expected to respect |
| a ``DESTDIR`` environment variable, which is prepended to all the other |
| variables when the build system actually installs the files. It is |
| understood that the program does not actually run from within |
| ``DESTDIR``. |
| |
| When the OpenEmbedded build system uses a recipe to build a |
| target-architecture program (i.e. one that is intended for inclusion on |
| the image being built), that program eventually runs from the root file |
| system of that image. Thus, the build system provides a value of |
| "/usr/bin" for ``bindir``, a value of "/usr/lib" for ``libdir``, and so |
| forth. |
| |
| Meanwhile, ``DESTDIR`` is a path within the :term:`Build Directory`. |
| However, when the recipe builds a native program (i.e. one that is |
| intended to run on the build machine), that program is never installed |
| directly to the build machine's root file system. Consequently, the build |
| system uses paths within the Build Directory for ``DESTDIR``, ``bindir`` |
| and related variables. To better understand this, consider the following |
| two paths (artificially broken across lines for readability) where the |
| first is relatively normal and the second is not:: |
| |
| /home/maxtothemax/poky-bootchart2/build/tmp/work/i586-poky-linux/zlib/ |
| 1.2.8-r0/sysroot-destdir/usr/bin |
| |
| /home/maxtothemax/poky-bootchart2/build/tmp/work/x86_64-linux/ |
| zlib-native/1.2.8-r0/sysroot-destdir/home/maxtothemax/poky-bootchart2/ |
| build/tmp/sysroots/x86_64-linux/usr/bin |
| |
| Even if the paths look unusual, they both are correct --- the first for |
| a target and the second for a native recipe. These paths are a consequence |
| of the ``DESTDIR`` mechanism and while they appear strange, they are correct |
| and in practice very effective. |
| |
| How do I create images with more free space? |
| -------------------------------------------- |
| |
| By default, the OpenEmbedded build system creates images that are |
| 1.3 times the size of the populated root filesystem. To affect the image |
| size, you need to set various configurations: |
| |
| - *Image Size:* The OpenEmbedded build system uses the |
| :term:`IMAGE_ROOTFS_SIZE` variable to define |
| the size of the image in Kbytes. The build system determines the size |
| by taking into account the initial root filesystem size before any |
| modifications such as requested size for the image and any requested |
| additional free disk space to be added to the image. |
| |
| - *Overhead:* Use the |
| :term:`IMAGE_OVERHEAD_FACTOR` variable |
| to define the multiplier that the build system applies to the initial |
| image size, which is 1.3 by default. |
| |
| - *Additional Free Space:* Use the |
| :term:`IMAGE_ROOTFS_EXTRA_SPACE` |
| variable to add additional free space to the image. The build system |
| adds this space to the image after it determines its |
| :term:`IMAGE_ROOTFS_SIZE`. |
| |
| Why aren't spaces in path names supported? |
| ------------------------------------------ |
| |
| The Yocto Project team has tried to do this before but too many |
| of the tools the OpenEmbedded build system depends on, such as |
| ``autoconf``, break when they find spaces in pathnames. Until that |
| situation changes, the team will not support spaces in pathnames. |
| |
| I'm adding a binary in a recipe. Why is it different in the image? |
| ------------------------------------------------------------------ |
| |
| The first most obvious change is the system stripping debug symbols from |
| it. Setting :term:`INHIBIT_PACKAGE_STRIP` to stop debug symbols being |
| stripped and/or :term:`INHIBIT_PACKAGE_DEBUG_SPLIT` to stop debug symbols |
| being split into a separate file will ensure the binary is unchanged. |
| |
| Issues on the running system |
| ============================ |
| |
| How do I disable the cursor on my touchscreen device? |
| ----------------------------------------------------- |
| |
| You need to create a form factor file as described in the |
| ":ref:`bsp-guide/bsp:miscellaneous bsp-specific recipe files`" section in |
| the Yocto Project Board Support Packages (BSP) Developer's Guide. Set |
| the ``HAVE_TOUCHSCREEN`` variable equal to one as follows:: |
| |
| HAVE_TOUCHSCREEN=1 |
| |
| How to always bring up connected network interfaces? |
| ---------------------------------------------------- |
| |
| The default interfaces file provided by the netbase recipe does |
| not automatically bring up network interfaces. Therefore, you will need |
| to add a BSP-specific netbase that includes an interfaces file. See the |
| ":ref:`bsp-guide/bsp:miscellaneous bsp-specific recipe files`" section in |
| the Yocto Project Board Support Packages (BSP) Developer's Guide for |
| information on creating these types of miscellaneous recipe files. |
| |
| For example, add the following files to your layer:: |
| |
| meta-MACHINE/recipes-bsp/netbase/netbase/MACHINE/interfaces |
| meta-MACHINE/recipes-bsp/netbase/netbase_5.0.bbappend |