diff options
Diffstat (limited to 'poky/documentation/ref-manual')
56 files changed, 23035 insertions, 18 deletions
diff --git a/poky/documentation/ref-manual/examples/hello-autotools/hello_2.10.bb b/poky/documentation/ref-manual/examples/hello-autotools/hello_2.10.bb new file mode 100644 index 000000000..aa2beb9a9 --- /dev/null +++ b/poky/documentation/ref-manual/examples/hello-autotools/hello_2.10.bb @@ -0,0 +1,9 @@ +DESCRIPTION = "GNU Helloworld application" +SECTION = "examples" +LICENSE = "GPLv3" +LIC_FILES_CHKSUM = "file://COPYING;md5=d32239bcb673463ab874e80d47fae504" + +SRC_URI = "${GNU_MIRROR}/hello/hello-${PV}.tar.gz" +SRC_URI[sha256sum] = "31e066137a962676e89f69d1b65382de95a7ef7d914b8cb956f41ea72e0f516b" + +inherit autotools-brokensep gettext diff --git a/poky/documentation/ref-manual/examples/hello-autotools/hello_2.3.bb b/poky/documentation/ref-manual/examples/hello-autotools/hello_2.3.bb deleted file mode 100644 index 5dfb0b30c..000000000 --- a/poky/documentation/ref-manual/examples/hello-autotools/hello_2.3.bb +++ /dev/null @@ -1,8 +0,0 @@ -DESCRIPTION = "GNU Helloworld application" -SECTION = "examples" -LICENSE = "GPLv3" -LIC_FILES_CHKSUM = "file://COPYING;md5=adefda309052235aa5d1e99ce7557010" - -SRC_URI = "${GNU_MIRROR}/hello/hello-${PV}.tar.bz2" - -inherit autotools diff --git a/poky/documentation/ref-manual/examples/libxpm/libxpm_3.5.6.bb b/poky/documentation/ref-manual/examples/libxpm/libxpm_3.5.6.bb index b58d4d7bd..c0c898640 100644 --- a/poky/documentation/ref-manual/examples/libxpm/libxpm_3.5.6.bb +++ b/poky/documentation/ref-manual/examples/libxpm/libxpm_3.5.6.bb @@ -1,4 +1,4 @@ -require xorg-lib-common.inc +require recipes-graphics/xorg-lib/xorg-lib-common.inc DESCRIPTION = "X11 Pixmap library" LICENSE = "X-BSD" diff --git a/poky/documentation/ref-manual/faq.rst b/poky/documentation/ref-manual/faq.rst new file mode 100644 index 000000000..2d2aaad0a --- /dev/null +++ b/poky/documentation/ref-manual/faq.rst @@ -0,0 +1,451 @@ +.. SPDX-License-Identifier: CC-BY-2.0-UK + +*** +FAQ +*** + +**Q:** How does Poky differ from `OpenEmbedded <http://www.openembedded.org/>`__? + +**A:** 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. + +**Q:** My development system does not meet the required Git, tar, and +Python versions. In particular, I do not have Python 3.5.0 or greater. +Can I still use the Yocto Project? + +**A:** You can get the required tools on your host development system a +couple different ways (i.e. building a tarball or downloading a +tarball). See the "`Required Git, tar, Python and gcc +Versions <#required-git-tar-python-and-gcc-versions>`__" section for +steps on how to update your build tools. + +**Q:** How can you claim Poky / OpenEmbedded-Core is stable? + +**A:** 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 autobuilder, which provides continuous + build and integration tests. + +**Q:** How do I get support for my board added to the Yocto Project? + +**A:** 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/dev-manual-common-tasks:understanding and creating layers`" +section in the Yocto Project Development Tasks Manual and the +:doc:`../bsp-guide/bsp-guide`. + +Usually, if the board is not completely exotic, adding support in the +Yocto Project is fairly straightforward. + +**Q:** Are there any products built using the OpenEmbedded build system? + +**A:** The software running on the `Vernier +LabQuest <http://vernier.com/labquest/>`__ is built using the +OpenEmbedded build system. See the `Vernier +LabQuest <http://www.vernier.com/products/interfaces/labq/>`__ website +for more information. There are a number of pre-production devices using +the OpenEmbedded build system and the Yocto Project team announces them +as soon as they are released. + +**Q:** What does the OpenEmbedded build system produce as output? + +**A:** 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. + +**Q:** How do I add my package to the Yocto Project? + +**A:** 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/dev-manual-common-tasks:writing a new recipe`" +section in the Yocto Project Development Tasks Manual. + +**Q:** Do I have to reflash my entire board with a new Yocto Project +image when recompiling a package? + +**A:** The OpenEmbedded build system can build packages in various +formats such as IPK for OPKG, Debian package (``.deb``), or RPM. You can +then upgrade the 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. + +**Q:** I see the error +'``chmod: XXXXX new permissions are r-xrwxrwx, not r-xr-xr-x``'. What is +wrong? + +**A:** You are probably running the build on an NTFS filesystem. Use +``ext2``, ``ext3``, or ``ext4`` instead. + +**Q:** I see lots of 404 responses for files when the OpenEmbedded build +system is trying to download sources. Is something wrong? + +**A:** 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. The address above is one of the default mirrors configured +into the build system. Consequently, if an upstream source disappears, +the team can place sources there so builds continue to work. + +**Q:** I have machine-specific data in a package for one machine only +but the package is being marked as machine-specific in all cases, how do +I prevent this? + +**A:** Set ``SRC_URI_OVERRIDES_PACKAGE_ARCH`` = "0" in the ``.bb`` file +but make sure the package is manually marked as machine-specific for the +case that needs it. The code that handles +``SRC_URI_OVERRIDES_PACKAGE_ARCH`` is in the +``meta/classes/base.bbclass`` file. + +**Q:** I'm behind a firewall and need to use a proxy server. How do I do +that? + +**A:** 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 Yocto Project also includes a +``meta-poky/conf/site.conf.sample`` file that shows how to configure CVS +and Git proxy servers if needed. For more information on setting up +various proxy types and configuring proxy servers, see the +":yocto_wiki:`Working Behind a Network Proxy </wiki/Working_Behind_a_Network_Proxy>`" +Wiki page. + +**Q:** What's the difference between target and target\ ``-native``? + +**A:** 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. + +**Q:** I'm seeing random build failures. Help?! + +**A:** 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. + +**Q:** When I try to build a native recipe, the build fails with +``iconv.h`` problems. + +**A:** If you get an error message that indicates GNU ``libiconv`` is +not in use but ``iconv.h`` has been included from ``libiconv``, you need +to check to see if you have a previously installed version of the header +file in ``/usr/local/include``. +:: + + #error GNU libiconv not in use but included iconv.h is from libiconv + +If you find a previously installed +file, 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``. Be sure that leakage cannot occur from +``/usr/local/include`` and ``/opt`` locations. + +**Q:** What do we need to ship for license compliance? + +**A:** 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/overview-manual-development-environment:licensing`" +section in the Yocto +Project Overview and Concepts Manual and also in the +":ref:`dev-manual/dev-manual-common-tasks:maintaining open source license compliance during your product's lifecycle`" +section in the Yocto Project Development Tasks Manual. + +**Q:** How do I disable the cursor on my touchscreen device? + +**A:** You need to create a form factor file as described in the +":ref:`bsp-filelayout-misc-recipes`" 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 + +**Q:** How do I make sure connected network interfaces are brought up by +default? + +**A:** 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-filelayout-misc-recipes`" 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 + +**Q:** How do I create images with more free space? + +**A:** 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 + ``IMAGE_ROOTFS_SIZE``. + +**Q:** Why don't you support directories with spaces in the pathnames? + +**A:** 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. + +**Q:** How do I use an external toolchain? + +**A:** The toolchain configuration is very flexible and customizable. It +is primarily controlled with the ``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 ``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 +http://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``. + +**Q:** How does the OpenEmbedded build system obtain source code and +will it work behind my firewall or proxy server? + +**A:** 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 ``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://.*/.* http://www.yoctoproject.org/sources/ \n \ + ftp://.*/.* http://www.yoctoproject.org/sources/ \n \ + http://.*/.* http://www.yoctoproject.org/sources/ \n \ + https://.*/.* http://www.yoctoproject.org/sources/ \n" + +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. + +Aside from the previous technique, these options also exist: +:: + + 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 ``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 ``PREMIRRORS`` server is current: :: + + PREMIRRORS_prepend = "\ + ftp://.*/.* http://www.yoctoproject.org/sources/ \n \ + http://.*/.* http://www.yoctoproject.org/sources/ \n \ + https://.*/.* http://www.yoctoproject.org/sources/ \n" + 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 +``PREMIRRORS`` would fail. + +The build system also honors the standard shell environment variables +``http_proxy``, ``ftp_proxy``, ``https_proxy``, and ``all_proxy`` to +redirect requests through proxy servers. + +.. note:: + + You can find more information on the + ":yocto_wiki:`Working Behind a Network Proxy </wiki/Working_Behind_a_Network_Proxy>`" + Wiki page. + +**Q:** Can I get rid of build output so I can start over? + +**A:** 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. +````` <#structure-core-script>`__). By default, this :term:`Build Directory` +is named ``build`` but can be named +anything you want. + +Within the 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. + +**Q:** Why do ``${bindir}`` and ``${libdir}`` have strange values for +``-native`` recipes? + +**A:** 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 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 + +.. note:: + + Due to these lengthy examples, the paths are artificially broken + across lines for readability. + +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. + +**Q:** The files provided by my ``*-native`` recipe do not appear to be +available to other recipes. Files are missing from the native sysroot, +my recipe is installing to the wrong place, or I am getting permissions +errors during the do_install task in my recipe! What is wrong? + +**A:** This situation results when a build system 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, permissions errors might be caused by a +Makefile that ignores ``DESTDIR`` or uses a different name for that +environment variable. Check the the build system to see if these kinds +of issues exist. diff --git a/poky/documentation/ref-manual/faq.xml b/poky/documentation/ref-manual/faq.xml index d94cb32a8..2f8fcf324 100644 --- a/poky/documentation/ref-manual/faq.xml +++ b/poky/documentation/ref-manual/faq.xml @@ -1,6 +1,7 @@ <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > +<!--SPDX-License-Identifier: CC-BY-2.0-UK--> <chapter id='faq'> <title>FAQ</title> @@ -322,7 +323,7 @@ <qandaentry> <question> <para> - What’s the difference between <replaceable>target</replaceable> and <replaceable>target</replaceable><filename>-native</filename>? + What's the difference between <replaceable>target</replaceable> and <replaceable>target</replaceable><filename>-native</filename>? </para> </question> <answer> diff --git a/poky/documentation/ref-manual/history.rst b/poky/documentation/ref-manual/history.rst new file mode 100644 index 000000000..e962d9297 --- /dev/null +++ b/poky/documentation/ref-manual/history.rst @@ -0,0 +1,74 @@ +.. SPDX-License-Identifier: CC-BY-2.0-UK + +*********************** +Manual Revision History +*********************** + +.. list-table:: + :widths: 10 15 40 + :header-rows: 1 + + * - Revision + - Date + - Note + * - 0.9 + - November 2010 + - The initial document released with the Yocto Project 0.9 Release + * - 1.0 + - April 2011 + - Released with the Yocto Project 1.0 Release. + * - 1.1 + - October 2011 + - Released with the Yocto Project 1.1 Release. + * - 1.2 + - April 2012 + - Released with the Yocto Project 1.2 Release. + * - 1.3 + - October 2012 + - Released with the Yocto Project 1.3 Release. + * - 1.4 + - April 2013 + - Released with the Yocto Project 1.4 Release. + * - 1.5 + - October 2013 + - Released with the Yocto Project 1.5 Release. + * - 1.6 + - April 2014 + - Released with the Yocto Project 1.6 Release. + * - 1.7 + - October 2014 + - Released with the Yocto Project 1.7 Release. + * - 1.8 + - April 2015 + - Released with the Yocto Project 1.8 Release. + * - 2.0 + - October 2015 + - Released with the Yocto Project 2.0 Release. + * - 2.1 + - April 2016 + - Released with the Yocto Project 2.1 Release. + * - 2.2 + - October 2016 + - Released with the Yocto Project 2.2 Release. + * - 2.3 + - May 2017 + - Released with the Yocto Project 2.3 Release. + * - 2.4 + - October 2017 + - Released with the Yocto Project 2.4 Release. + * - 2.5 + - May 2018 + - Released with the Yocto Project 2.5 Release. + * - 2.6 + - November 2018 + - Released with the Yocto Project 2.6 Release. + * - 2.7 + - May 2019 + - Released with the Yocto Project 2.7 Release. + * - 3.0 + - October 2019 + - Released with the Yocto Project 3.0 Release. + * - 3.1 + - April 2020 + - Released with the Yocto Project 3.1 Release. + diff --git a/poky/documentation/ref-manual/migration-1.3.rst b/poky/documentation/ref-manual/migration-1.3.rst new file mode 100644 index 000000000..ebbc23887 --- /dev/null +++ b/poky/documentation/ref-manual/migration-1.3.rst @@ -0,0 +1,195 @@ +.. SPDX-License-Identifier: CC-BY-2.0-UK + +Moving to the Yocto Project 1.3 Release +======================================= + +This section provides migration information for moving to the Yocto +Project 1.3 Release from the prior release. + +.. _1.3-local-configuration: + +Local Configuration +------------------- + +Differences include changes for +:term:`SSTATE_MIRRORS` and ``bblayers.conf``. + +.. _migration-1.3-sstate-mirrors: + +SSTATE_MIRRORS +~~~~~~~~~~~~~~ + +The shared state cache (sstate-cache), as pointed to by +:term:`SSTATE_DIR`, by default now has two-character +subdirectories to prevent issues arising from too many files in the same +directory. Also, native sstate-cache packages, which are built to run on +the host system, will go into a subdirectory named using the distro ID +string. If you copy the newly structured sstate-cache to a mirror +location (either local or remote) and then point to it in +:term:`SSTATE_MIRRORS`, you need to append "PATH" +to the end of the mirror URL so that the path used by BitBake before the +mirror substitution is appended to the path used to access the mirror. +Here is an example: :: + + SSTATE_MIRRORS = "file://.* http://someserver.tld/share/sstate/PATH" + +.. _migration-1.3-bblayers-conf: + +bblayers.conf +~~~~~~~~~~~~~ + +The ``meta-yocto`` layer consists of two parts that correspond to the +Poky reference distribution and the reference hardware Board Support +Packages (BSPs), respectively: ``meta-yocto`` and ``meta-yocto-bsp``. +When running BitBake for the first time after upgrading, your +``conf/bblayers.conf`` file will be updated to handle this change and +you will be asked to re-run or restart for the changes to take effect. + +.. _1.3-recipes: + +Recipes +------- + +Differences include changes for the following: + +.. _migration-1.3-python-function-whitespace: + +Python Function Whitespace +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +All Python functions must now use four spaces for indentation. +Previously, an inconsistent mix of spaces and tabs existed, which made +extending these functions using ``_append`` or ``_prepend`` complicated +given that Python treats whitespace as syntactically significant. If you +are defining or extending any Python functions (e.g. +``populate_packages``, ``do_unpack``, ``do_patch`` and so forth) in +custom recipes or classes, you need to ensure you are using consistent +four-space indentation. + +.. _migration-1.3-proto=-in-src-uri: + +proto= in SRC_URI +~~~~~~~~~~~~~~~~~ + +Any use of ``proto=`` in :term:`SRC_URI` needs to be +changed to ``protocol=``. In particular, this applies to the following +URIs: + +- ``svn://`` + +- ``bzr://`` + +- ``hg://`` + +- ``osc://`` + +Other URIs were already using ``protocol=``. This change improves +consistency. + +.. _migration-1.3-nativesdk: + +nativesdk +~~~~~~~~~ + +The suffix ``nativesdk`` is now implemented as a prefix, which +simplifies a lot of the packaging code for ``nativesdk`` recipes. All +custom ``nativesdk`` recipes, which are relocatable packages that are +native to :term:`SDK_ARCH`, and any references need to +be updated to use ``nativesdk-*`` instead of ``*-nativesdk``. + +.. _migration-1.3-task-recipes: + +Task Recipes +~~~~~~~~~~~~ + +"Task" recipes are now known as "Package groups" and have been renamed +from ``task-*.bb`` to ``packagegroup-*.bb``. Existing references to the +previous ``task-*`` names should work in most cases as there is an +automatic upgrade path for most packages. However, you should update +references in your own recipes and configurations as they could be +removed in future releases. You should also rename any custom ``task-*`` +recipes to ``packagegroup-*``, and change them to inherit +``packagegroup`` instead of ``task``, as well as taking the opportunity +to remove anything now handled by ``packagegroup.bbclass``, such as +providing ``-dev`` and ``-dbg`` packages, setting +:term:`LIC_FILES_CHKSUM`, and so forth. See the +":ref:`packagegroup.bbclass <ref-classes-packagegroup>`" section for +further details. + +.. _migration-1.3-image-features: + +IMAGE_FEATURES +~~~~~~~~~~~~~~ + +Image recipes that previously included "apps-console-core" in +:term:`IMAGE_FEATURES` should now include "splash" +instead to enable the boot-up splash screen. Retaining +"apps-console-core" will still include the splash screen but generates a +warning. The "apps-x11-core" and "apps-x11-games" ``IMAGE_FEATURES`` +features have been removed. + +.. _migration-1.3-removed-recipes: + +Removed Recipes +~~~~~~~~~~~~~~~ + +The following recipes have been removed. For most of them, it is +unlikely that you would have any references to them in your own +:term:`Metadata`. However, you should check your metadata +against this list to be sure: + +- ``libx11-trim``: Replaced by ``libx11``, which has a negligible + size difference with modern Xorg. + +- ``xserver-xorg-lite``: Use ``xserver-xorg``, which has a negligible + size difference when DRI and GLX modules are not installed. + +- ``xserver-kdrive``: Effectively unmaintained for many years. + +- ``mesa-xlib``: No longer serves any purpose. + +- ``galago``: Replaced by telepathy. + +- ``gail``: Functionality was integrated into GTK+ 2.13. + +- ``eggdbus``: No longer needed. + +- ``gcc-*-intermediate``: The build has been restructured to avoid + the need for this step. + +- ``libgsmd``: Unmaintained for many years. Functionality now + provided by ``ofono`` instead. + +- *contacts, dates, tasks, eds-tools*: Largely unmaintained PIM + application suite. It has been moved to ``meta-gnome`` in + ``meta-openembedded``. + +In addition to the previously listed changes, the ``meta-demoapps`` +directory has also been removed because the recipes in it were not being +maintained and many had become obsolete or broken. Additionally, these +recipes were not parsed in the default configuration. Many of these +recipes are already provided in an updated and maintained form within +the OpenEmbedded community layers such as ``meta-oe`` and +``meta-gnome``. For the remainder, you can now find them in the +``meta-extras`` repository, which is in the +:yocto_git:`Source Repositories <>` at +http://git.yoctoproject.org/cgit/cgit.cgi/meta-extras/. + +.. _1.3-linux-kernel-naming: + +Linux Kernel Naming +------------------- + +The naming scheme for kernel output binaries has been changed to now +include :term:`PE` as part of the filename: +:: + + KERNEL_IMAGE_BASE_NAME ?= "${KERNEL_IMAGETYPE}-${PE}-${PV}-${PR}-${MACHINE}-${DATETIME}" + +Because the ``PE`` variable is not set by default, these binary files +could result with names that include two dash characters. Here is an +example: :: + + bzImage--3.10.9+git0+cd502a8814_7144bcc4b8-r0-qemux86-64-20130830085431.bin + + diff --git a/poky/documentation/ref-manual/migration-1.4.rst b/poky/documentation/ref-manual/migration-1.4.rst new file mode 100644 index 000000000..a658bdff6 --- /dev/null +++ b/poky/documentation/ref-manual/migration-1.4.rst @@ -0,0 +1,237 @@ +Moving to the Yocto Project 1.4 Release +======================================= + +This section provides migration information for moving to the Yocto +Project 1.4 Release from the prior release. + +.. _migration-1.4-bitbake: + +BitBake +------- + +Differences include the following: + +- *Comment Continuation:* If a comment ends with a line continuation + (\) character, then the next line must also be a comment. Any + instance where this is not the case, now triggers a warning. You must + either remove the continuation character, or be sure the next line is + a comment. + +- *Package Name Overrides:* The runtime package specific variables + :term:`RDEPENDS`, + :term:`RRECOMMENDS`, + :term:`RSUGGESTS`, + :term:`RPROVIDES`, + :term:`RCONFLICTS`, + :term:`RREPLACES`, :term:`FILES`, + :term:`ALLOW_EMPTY`, and the pre, post, install, + and uninstall script functions ``pkg_preinst``, ``pkg_postinst``, + ``pkg_prerm``, and ``pkg_postrm`` should always have a package name + override. For example, use ``RDEPENDS_${PN}`` for the main package + instead of ``RDEPENDS``. BitBake uses more strict checks when it + parses recipes. + +.. _migration-1.4-build-behavior: + +Build Behavior +-------------- + +Differences include the following: + +- *Shared State Code:* The shared state code has been optimized to + avoid running unnecessary tasks. For example, the following no longer + populates the target sysroot since that is not necessary: + :: + + $ bitbake -c rootfs some-image + + Instead, the system just needs to extract the + output package contents, re-create the packages, and construct the + root filesystem. This change is unlikely to cause any problems unless + you have missing declared dependencies. + +- *Scanning Directory Names:* When scanning for files in + :term:`SRC_URI`, the build system now uses + :term:`FILESOVERRIDES` instead of + :term:`OVERRIDES` for the directory names. In + general, the values previously in ``OVERRIDES`` are now in + ``FILESOVERRIDES`` as well. However, if you relied upon an additional + value you previously added to ``OVERRIDES``, you might now need to + add it to ``FILESOVERRIDES`` unless you are already adding it through + the :term:`MACHINEOVERRIDES` or + :term:`DISTROOVERRIDES` variables, as + appropriate. For more related changes, see the + "`Variables <#migration-1.4-variables>`__" section. + +.. _migration-1.4-proxies-and-fetching-source: + +Proxies and Fetching Source +--------------------------- + +A new ``oe-git-proxy`` script has been added to replace previous methods +of handling proxies and fetching source from Git. See the +``meta-yocto/conf/site.conf.sample`` file for information on how to use +this script. + +.. _migration-1.4-custom-interfaces-file-netbase-change: + +Custom Interfaces File (netbase change) +--------------------------------------- + +If you have created your own custom ``etc/network/interfaces`` file by +creating an append file for the ``netbase`` recipe, you now need to +create an append file for the ``init-ifupdown`` recipe instead, which +you can find in the :term:`Source Directory` at +``meta/recipes-core/init-ifupdown``. For information on how to use +append files, see the +":ref:`dev-manual/dev-manual-common-tasks:using .bbappend files in your layer`" +section in the Yocto Project Development Tasks Manual. + +.. _migration-1.4-remote-debugging: + +Remote Debugging +---------------- + +Support for remote debugging with the Eclipse IDE is now separated into +an image feature (``eclipse-debug``) that corresponds to the +``packagegroup-core-eclipse-debug`` package group. Previously, the +debugging feature was included through the ``tools-debug`` image +feature, which corresponds to the ``packagegroup-core-tools-debug`` +package group. + +.. _migration-1.4-variables: + +Variables +--------- + +The following variables have changed: + +- ``SANITY_TESTED_DISTROS``: This variable now uses a distribution + ID, which is composed of the host distributor ID followed by the + release. Previously, + :term:`SANITY_TESTED_DISTROS` was + composed of the description field. For example, "Ubuntu 12.10" + becomes "Ubuntu-12.10". You do not need to worry about this change if + you are not specifically setting this variable, or if you are + specifically setting it to "". + +- ``SRC_URI``: The ``${``\ :term:`PN`\ ``}``, + ``${``\ :term:`PF`\ ``}``, + ``${``\ :term:`P`\ ``}``, and ``FILE_DIRNAME`` directories + have been dropped from the default value of the + :term:`FILESPATH` variable, which is used as the + search path for finding files referred to in + :term:`SRC_URI`. If you have a recipe that relied upon + these directories, which would be unusual, then you will need to add + the appropriate paths within the recipe or, alternatively, rearrange + the files. The most common locations are still covered by ``${BP}``, + ``${BPN}``, and "files", which all remain in the default value of + :term:`FILESPATH`. + +.. _migration-target-package-management-with-rpm: + +Target Package Management with RPM +---------------------------------- + +If runtime package management is enabled and the RPM backend is +selected, Smart is now installed for package download, dependency +resolution, and upgrades instead of Zypper. For more information on how +to use Smart, run the following command on the target: +:: + + smart --help + +.. _migration-1.4-recipes-moved: + +Recipes Moved +------------- + +The following recipes were moved from their previous locations because +they are no longer used by anything in the OpenEmbedded-Core: + +- ``clutter-box2d``: Now resides in the ``meta-oe`` layer. + +- ``evolution-data-server``: Now resides in the ``meta-gnome`` layer. + +- ``gthumb``: Now resides in the ``meta-gnome`` layer. + +- ``gtkhtml2``: Now resides in the ``meta-oe`` layer. + +- ``gupnp``: Now resides in the ``meta-multimedia`` layer. + +- ``gypsy``: Now resides in the ``meta-oe`` layer. + +- ``libcanberra``: Now resides in the ``meta-gnome`` layer. + +- ``libgdata``: Now resides in the ``meta-gnome`` layer. + +- ``libmusicbrainz``: Now resides in the ``meta-multimedia`` layer. + +- ``metacity``: Now resides in the ``meta-gnome`` layer. + +- ``polkit``: Now resides in the ``meta-oe`` layer. + +- ``zeroconf``: Now resides in the ``meta-networking`` layer. + +.. _migration-1.4-removals-and-renames: + +Removals and Renames +-------------------- + +The following list shows what has been removed or renamed: + +- ``evieext``: Removed because it has been removed from ``xserver`` + since 2008. + +- *Gtk+ DirectFB:* Removed support because upstream Gtk+ no longer + supports it as of version 2.18. + +- ``libxfontcache / xfontcacheproto``: Removed because they were + removed from the Xorg server in 2008. + +- ``libxp / libxprintapputil / libxprintutil / printproto``: Removed + because the XPrint server was removed from Xorg in 2008. + +- ``libxtrap / xtrapproto``: Removed because their functionality was + broken upstream. + +- *linux-yocto 3.0 kernel:* Removed with linux-yocto 3.8 kernel being + added. The linux-yocto 3.2 and linux-yocto 3.4 kernels remain as part + of the release. + +- ``lsbsetup``: Removed with functionality now provided by + ``lsbtest``. + +- ``matchbox-stroke``: Removed because it was never more than a + proof-of-concept. + +- ``matchbox-wm-2 / matchbox-theme-sato-2``: Removed because they are + not maintained. However, ``matchbox-wm`` and ``matchbox-theme-sato`` + are still provided. + +- ``mesa-dri``: Renamed to ``mesa``. + +- ``mesa-xlib``: Removed because it was no longer useful. + +- ``mutter``: Removed because nothing ever uses it and the recipe is + very old. + +- ``orinoco-conf``: Removed because it has become obsolete. + +- ``update-modules``: Removed because it is no longer used. The + kernel module ``postinstall`` and ``postrm`` scripts can now do the + same task without the use of this script. + +- ``web``: Removed because it is not maintained. Superseded by + ``web-webkit``. + +- ``xf86bigfontproto``: Removed because upstream it has been disabled + by default since 2007. Nothing uses ``xf86bigfontproto``. + +- ``xf86rushproto``: Removed because its dependency in ``xserver`` + was spurious and it was removed in 2005. + +- ``zypper / libzypp / sat-solver``: Removed and been functionally + replaced with Smart (``python-smartpm``) when RPM packaging is used + and package management is enabled on the target. + diff --git a/poky/documentation/ref-manual/migration-1.5.rst b/poky/documentation/ref-manual/migration-1.5.rst new file mode 100644 index 000000000..fa6ff92f1 --- /dev/null +++ b/poky/documentation/ref-manual/migration-1.5.rst @@ -0,0 +1,355 @@ +Moving to the Yocto Project 1.5 Release +======================================= + +This section provides migration information for moving to the Yocto +Project 1.5 Release from the prior release. + +.. _migration-1.5-host-dependency-changes: + +Host Dependency Changes +----------------------- + +The OpenEmbedded build system now has some additional requirements on +the host system: + +- Python 2.7.3+ + +- Tar 1.24+ + +- Git 1.7.8+ + +- Patched version of Make if you are using 3.82. Most distributions + that provide Make 3.82 use the patched version. + +If the Linux distribution you are using on your build host does not +provide packages for these, you can install and use the Buildtools +tarball, which provides an SDK-like environment containing them. + +For more information on this requirement, see the "`Required Git, tar, +Python and gcc Versions <#required-git-tar-python-and-gcc-versions>`__" +section. + +.. _migration-1.5-atom-pc-bsp: + +``atom-pc`` Board Support Package (BSP) +--------------------------------------- + +The ``atom-pc`` hardware reference BSP has been replaced by a +``genericx86`` BSP. This BSP is not necessarily guaranteed to work on +all x86 hardware, but it will run on a wider range of systems than the +``atom-pc`` did. + +.. note:: + + Additionally, a + genericx86-64 + BSP has been added for 64-bit Atom systems. + +.. _migration-1.5-bitbake: + +BitBake +------- + +The following changes have been made that relate to BitBake: + +- BitBake now supports a ``_remove`` operator. The addition of this + operator means you will have to rename any items in recipe space + (functions, variables) whose names currently contain ``_remove_`` or + end with ``_remove`` to avoid unexpected behavior. + +- BitBake's global method pool has been removed. This method is not + particularly useful and led to clashes between recipes containing + functions that had the same name. + +- The "none" server backend has been removed. The "process" server + backend has been serving well as the default for a long time now. + +- The ``bitbake-runtask`` script has been removed. + +- ``${``\ :term:`P`\ ``}`` and + ``${``\ :term:`PF`\ ``}`` are no longer added to + :term:`PROVIDES` by default in ``bitbake.conf``. + These version-specific ``PROVIDES`` items were seldom used. + Attempting to use them could result in two versions being built + simultaneously rather than just one version due to the way BitBake + resolves dependencies. + +.. _migration-1.5-qa-warnings: + +QA Warnings +----------- + +The following changes have been made to the package QA checks: + +- If you have customized :term:`ERROR_QA` or + :term:`WARN_QA` values in your configuration, check + that they contain all of the issues that you wish to be reported. + Previous Yocto Project versions contained a bug that meant that any + item not mentioned in ``ERROR_QA`` or ``WARN_QA`` would be treated as + a warning. Consequently, several important items were not already in + the default value of ``WARN_QA``. All of the possible QA checks are + now documented in the ":ref:`insane.bbclass <ref-classes-insane>`" + section. + +- An additional QA check has been added to check if + ``/usr/share/info/dir`` is being installed. Your recipe should delete + this file within :ref:`ref-tasks-install` if "make + install" is installing it. + +- If you are using the buildhistory class, the check for the package + version going backwards is now controlled using a standard QA check. + Thus, if you have customized your ``ERROR_QA`` or ``WARN_QA`` values + and still wish to have this check performed, you should add + "version-going-backwards" to your value for one or the other + variables depending on how you wish it to be handled. See the + documented QA checks in the + ":ref:`insane.bbclass <ref-classes-insane>`" section. + +.. _migration-1.5-directory-layout-changes: + +Directory Layout Changes +------------------------ + +The following directory changes exist: + +- Output SDK installer files are now named to include the image name + and tuning architecture through the :term:`SDK_NAME` + variable. + +- Images and related files are now installed into a directory that is + specific to the machine, instead of a parent directory containing + output files for multiple machines. The + :term:`DEPLOY_DIR_IMAGE` variable continues + to point to the directory containing images for the current + :term:`MACHINE` and should be used anywhere there is a + need to refer to this directory. The ``runqemu`` script now uses this + variable to find images and kernel binaries and will use BitBake to + determine the directory. Alternatively, you can set the + ``DEPLOY_DIR_IMAGE`` variable in the external environment. + +- When buildhistory is enabled, its output is now written under the + :term:`Build Directory` rather than + :term:`TMPDIR`. Doing so makes it easier to delete + ``TMPDIR`` and preserve the build history. Additionally, data for + produced SDKs is now split by :term:`IMAGE_NAME`. + +- The ``pkgdata`` directory produced as part of the packaging process + has been collapsed into a single machine-specific directory. This + directory is located under ``sysroots`` and uses a machine-specific + name (i.e. ``tmp/sysroots/machine/pkgdata``). + +.. _migration-1.5-shortened-git-srcrev-values: + +Shortened Git ``SRCREV`` Values +------------------------------- + +BitBake will now shorten revisions from Git repositories from the normal +40 characters down to 10 characters within :term:`SRCPV` +for improved usability in path and file names. This change should be +safe within contexts where these revisions are used because the chances +of spatially close collisions is very low. Distant collisions are not a +major issue in the way the values are used. + +.. _migration-1.5-image-features: + +``IMAGE_FEATURES`` +------------------ + +The following changes have been made that relate to +:term:`IMAGE_FEATURES`: + +- The value of ``IMAGE_FEATURES`` is now validated to ensure invalid + feature items are not added. Some users mistakenly add package names + to this variable instead of using + :term:`IMAGE_INSTALL` in order to have the + package added to the image, which does not work. This change is + intended to catch those kinds of situations. Valid ``IMAGE_FEATURES`` + are drawn from ``PACKAGE_GROUP`` definitions, + :term:`COMPLEMENTARY_GLOB` and a new + "validitems" varflag on ``IMAGE_FEATURES``. The "validitems" varflag + change allows additional features to be added if they are not + provided using the previous two mechanisms. + +- The previously deprecated "apps-console-core" ``IMAGE_FEATURES`` item + is no longer supported. Add "splash" to ``IMAGE_FEATURES`` if you + wish to have the splash screen enabled, since this is all that + apps-console-core was doing. + +.. _migration-1.5-run: + +``/run`` +-------- + +The ``/run`` directory from the Filesystem Hierarchy Standard 3.0 has +been introduced. You can find some of the implications for this change +`here <http://cgit.openembedded.org/openembedded-core/commit/?id=0e326280a15b0f2c4ef2ef4ec441f63f55b75873>`__. +The change also means that recipes that install files to ``/var/run`` +must be changed. You can find a guide on how to make these changes +`here <https://www.mail-archive.com/openembedded-devel@lists.openembedded.org/msg31649.html>`__. + +.. _migration-1.5-removal-of-package-manager-database-within-image-recipes: + +Removal of Package Manager Database Within Image Recipes +-------------------------------------------------------- + +The image ``core-image-minimal`` no longer adds +``remove_packaging_data_files`` to +:term:`ROOTFS_POSTPROCESS_COMMAND`. +This addition is now handled automatically when "package-management" is +not in :term:`IMAGE_FEATURES`. If you have custom +image recipes that make this addition, you should remove the lines, as +they are not needed and might interfere with correct operation of +postinstall scripts. + +.. _migration-1.5-images-now-rebuild-only-on-changes-instead-of-every-time: + +Images Now Rebuild Only on Changes Instead of Every Time +-------------------------------------------------------- + +The :ref:`ref-tasks-rootfs` and other related image +construction tasks are no longer marked as "nostamp". Consequently, they +will only be re-executed when their inputs have changed. Previous +versions of the OpenEmbedded build system always rebuilt the image when +requested rather when necessary. + +.. _migration-1.5-task-recipes: + +Task Recipes +------------ + +The previously deprecated ``task.bbclass`` has now been dropped. For +recipes that previously inherited from this class, you should rename +them from ``task-*`` to ``packagegroup-*`` and inherit packagegroup +instead. + +For more information, see the +":ref:`packagegroup.bbclass <ref-classes-packagegroup>`" section. + +.. _migration-1.5-busybox: + +BusyBox +------- + +By default, we now split BusyBox into two binaries: one that is suid +root for those components that need it, and another for the rest of the +components. Splitting BusyBox allows for optimization that eliminates +the ``tinylogin`` recipe as recommended by upstream. You can disable +this split by setting +:term:`BUSYBOX_SPLIT_SUID` to "0". + +.. _migration-1.5-automated-image-testing: + +Automated Image Testing +----------------------- + +A new automated image testing framework has been added through the +:ref:`testimage.bbclass <ref-classes-testimage*>` class. This +framework replaces the older ``imagetest-qemu`` framework. + +You can learn more about performing automated image tests in the +":ref:`dev-manual/dev-manual-common-tasks:performing automated runtime testing`" +section in the Yocto Project Development Tasks Manual. + +.. _migration-1.5-build-history: + +Build History +------------- + +Following are changes to Build History: + +- Installed package sizes: ``installed-package-sizes.txt`` for an image + now records the size of the files installed by each package instead + of the size of each compressed package archive file. + +- The dependency graphs (``depends*.dot``) now use the actual package + names instead of replacing dashes, dots and plus signs with + underscores. + +- The ``buildhistory-diff`` and ``buildhistory-collect-srcrevs`` + utilities have improved command-line handling. Use the ``--help`` + option for each utility for more information on the new syntax. + +For more information on Build History, see the +":ref:`dev-manual/dev-manual-common-tasks:maintaining build output quality`" +section in the Yocto Project Development Tasks Manual. + +.. _migration-1.5-udev: + +``udev`` +-------- + +Following are changes to ``udev``: + +- ``udev`` no longer brings in ``udev-extraconf`` automatically through + :term:`RRECOMMENDS`, since this was originally + intended to be optional. If you need the extra rules, then add + ``udev-extraconf`` to your image. + +- ``udev`` no longer brings in ``pciutils-ids`` or ``usbutils-ids`` + through ``RRECOMMENDS``. These are not needed by ``udev`` itself and + removing them saves around 350KB. + +.. _migration-1.5-removed-renamed-recipes: + +Removed and Renamed Recipes +--------------------------- + +- The ``linux-yocto`` 3.2 kernel has been removed. + +- ``libtool-nativesdk`` has been renamed to ``nativesdk-libtool``. + +- ``tinylogin`` has been removed. It has been replaced by a suid + portion of Busybox. See the "`BusyBox <#migration-1.5-busybox>`__" + section for more information. + +- ``external-python-tarball`` has been renamed to + ``buildtools-tarball``. + +- ``web-webkit`` has been removed. It has been functionally replaced by + ``midori``. + +- ``imake`` has been removed. It is no longer needed by any other + recipe. + +- ``transfig-native`` has been removed. It is no longer needed by any + other recipe. + +- ``anjuta-remote-run`` has been removed. Anjuta IDE integration has + not been officially supported for several releases. + +.. _migration-1.5-other-changes: + +Other Changes +------------- + +Following is a list of short entries describing other changes: + +- ``run-postinsts``: Make this generic. + +- ``base-files``: Remove the unnecessary ``media/``\ xxx directories. + +- ``alsa-state``: Provide an empty ``asound.conf`` by default. + +- ``classes/image``: Ensure + :term:`BAD_RECOMMENDATIONS` supports + pre-renamed package names. + +- ``classes/rootfs_rpm``: Implement ``BAD_RECOMMENDATIONS`` for RPM. + +- ``systemd``: Remove ``systemd_unitdir`` if ``systemd`` is not in + :term:`DISTRO_FEATURES`. + +- ``systemd``: Remove ``init.d`` dir if ``systemd`` unit file is + present and ``sysvinit`` is not a distro feature. + +- ``libpam``: Deny all services for the ``OTHER`` entries. + +- ``image.bbclass``: Move ``runtime_mapping_rename`` to avoid conflict + with ``multilib``. See + `YOCTO #4993 <https://bugzilla.yoctoproject.org/show_bug.cgi?id=4993>`_ + in Bugzilla for more information. + +- ``linux-dtb``: Use kernel build system to generate the ``dtb`` files. + +- ``kern-tools``: Switch from guilt to new ``kgit-s2q`` tool. + diff --git a/poky/documentation/ref-manual/migration-1.6.rst b/poky/documentation/ref-manual/migration-1.6.rst new file mode 100644 index 000000000..b55be46e5 --- /dev/null +++ b/poky/documentation/ref-manual/migration-1.6.rst @@ -0,0 +1,417 @@ +Moving to the Yocto Project 1.6 Release +======================================= + +This section provides migration information for moving to the Yocto +Project 1.6 Release from the prior release. + +.. _migration-1.6-archiver-class: + +``archiver`` Class +------------------ + +The :ref:`archiver <ref-classes-archiver>` class has been rewritten +and its configuration has been simplified. For more details on the +source archiver, see the +":ref:`dev-manual/dev-manual-common-tasks:maintaining open source license compliance during your product's lifecycle`" +section in the Yocto Project Development Tasks Manual. + +.. _migration-1.6-packaging-changes: + +Packaging Changes +----------------- + +The following packaging changes have been made: + +- The ``binutils`` recipe no longer produces a ``binutils-symlinks`` + package. ``update-alternatives`` is now used to handle the preferred + ``binutils`` variant on the target instead. + +- The tc (traffic control) utilities have been split out of the main + ``iproute2`` package and put into the ``iproute2-tc`` package. + +- The ``gtk-engines`` schemas have been moved to a dedicated + ``gtk-engines-schemas`` package. + +- The ``armv7a`` with thumb package architecture suffix has changed. + The suffix for these packages with the thumb optimization enabled is + "t2" as it should be. Use of this suffix was not the case in the 1.5 + release. Architecture names will change within package feeds as a + result. + +.. _migration-1.6-bitbake: + +BitBake +------- + +The following changes have been made to :term:`BitBake`. + +.. _migration-1.6-matching-branch-requirement-for-git-fetching: + +Matching Branch Requirement for Git Fetching +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When fetching source from a Git repository using +:term:`SRC_URI`, BitBake will now validate the +:term:`SRCREV` value against the branch. You can specify +the branch using the following form: SRC_URI = +"git://server.name/repository;branch=branchname" If you do not specify a +branch, BitBake looks in the default "master" branch. + +Alternatively, if you need to bypass this check (e.g. if you are +fetching a revision corresponding to a tag that is not on any branch), +you can add ";nobranch=1" to the end of the URL within ``SRC_URI``. + +.. _migration-1.6-bitbake-deps: + +Python Definition substitutions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +BitBake had some previously deprecated Python definitions within its +``bb`` module removed. You should use their sub-module counterparts +instead: + +- ``bb.MalformedUrl``: Use ``bb.fetch.MalformedUrl``. + +- ``bb.encodeurl``: Use ``bb.fetch.encodeurl``. + +- ``bb.decodeurl``: Use ``bb.fetch.decodeurl`` + +- ``bb.mkdirhier``: Use ``bb.utils.mkdirhier``. + +- ``bb.movefile``: Use ``bb.utils.movefile``. + +- ``bb.copyfile``: Use ``bb.utils.copyfile``. + +- ``bb.which``: Use ``bb.utils.which``. + +- ``bb.vercmp_string``: Use ``bb.utils.vercmp_string``. + +- ``bb.vercmp``: Use ``bb.utils.vercmp``. + +.. _migration-1.6-bitbake-fetcher: + +SVK Fetcher +~~~~~~~~~~~ + +The SVK fetcher has been removed from BitBake. + +.. _migration-1.6-bitbake-console-output: + +Console Output Error Redirection +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The BitBake console UI will now output errors to ``stderr`` instead of +``stdout``. Consequently, if you are piping or redirecting the output of +``bitbake`` to somewhere else, and you wish to retain the errors, you +will need to add ``2>&1`` (or something similar) to the end of your +``bitbake`` command line. + +.. _migration-1.6-task-taskname-overrides: + +``task-``\ taskname Overrides +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``task-``\ taskname overrides have been adjusted so that tasks whose +names contain underscores have the underscores replaced by hyphens for +the override so that they now function properly. For example, the task +override for :ref:`ref-tasks-populate_sdk` is +``task-populate-sdk``. + +.. _migration-1.6-variable-changes: + +Changes to Variables +-------------------- + +The following variables have changed. For information on the +OpenEmbedded build system variables, see the "`Variables +Glossary <#ref-variables-glos>`__" Chapter. + +.. _migration-1.6-variable-changes-TMPDIR: + +``TMPDIR`` +~~~~~~~~~~ + +:term:`TMPDIR` can no longer be on an NFS mount. NFS does +not offer full POSIX locking and inode consistency and can cause +unexpected issues if used to store ``TMPDIR``. + +The check for this occurs on startup. If ``TMPDIR`` is detected on an +NFS mount, an error occurs. + +.. _migration-1.6-variable-changes-PRINC: + +``PRINC`` +~~~~~~~~~ + +The ``PRINC`` variable has been deprecated and triggers a warning if +detected during a build. For :term:`PR` increments on changes, +use the PR service instead. You can find out more about this service in +the ":ref:`dev-manual/dev-manual-common-tasks:working with a pr service`" +section in the Yocto Project Development Tasks Manual. + +.. _migration-1.6-variable-changes-IMAGE_TYPES: + +``IMAGE_TYPES`` +~~~~~~~~~~~~~~~ + +The "sum.jffs2" option for :term:`IMAGE_TYPES` has +been replaced by the "jffs2.sum" option, which fits the processing +order. + +.. _migration-1.6-variable-changes-COPY_LIC_MANIFEST: + +``COPY_LIC_MANIFEST`` +~~~~~~~~~~~~~~~~~~~~~ + +The :term:`COPY_LIC_MANIFEST` variable must now +be set to "1" rather than any value in order to enable it. + +.. _migration-1.6-variable-changes-COPY_LIC_DIRS: + +``COPY_LIC_DIRS`` +~~~~~~~~~~~~~~~~~ + +The :term:`COPY_LIC_DIRS` variable must now be set +to "1" rather than any value in order to enable it. + +.. _migration-1.6-variable-changes-PACKAGE_GROUP: + +``PACKAGE_GROUP`` +~~~~~~~~~~~~~~~~~ + +The ``PACKAGE_GROUP`` variable has been renamed to +:term:`FEATURE_PACKAGES` to more accurately +reflect its purpose. You can still use ``PACKAGE_GROUP`` but the +OpenEmbedded build system produces a warning message when it encounters +the variable. + +.. _migration-1.6-variable-changes-variable-entry-behavior: + +Preprocess and Post Process Command Variable Behavior +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following variables now expect a semicolon separated list of +functions to call and not arbitrary shell commands: + + - :term:`ROOTFS_PREPROCESS_COMMAND` + - :term:`ROOTFS_POSTPROCESS_COMMAND` + - :term:`SDK_POSTPROCESS_COMMAND` + - :term:`POPULATE_SDK_POST_TARGET_COMMAND` + - :term:`POPULATE_SDK_POST_HOST_COMMAND` + - :term:`IMAGE_POSTPROCESS_COMMAND` + - :term:`IMAGE_PREPROCESS_COMMAND` + - :term:`ROOTFS_POSTUNINSTALL_COMMAND` + - :term:`ROOTFS_POSTINSTALL_COMMAND` + +For +migration purposes, you can simply wrap shell commands in a shell +function and then call the function. Here is an example: :: + + my_postprocess_function() { + echo "hello" > ${IMAGE_ROOTFS}/hello.txt + } + ROOTFS_POSTPROCESS_COMMAND += "my_postprocess_function; " + +.. _migration-1.6-package-test-ptest: + +Package Test (ptest) +-------------------- + +Package Tests (ptest) are built but not installed by default. For +information on using Package Tests, see the +":ref:`dev-manual/dev-manual-common-tasks:testing packages with ptest`" +section in the Yocto Project Development Tasks Manual. For information on the +``ptest`` class, see the ":ref:`ptest.bbclass <ref-classes-ptest>`" +section. + +.. _migration-1.6-build-changes: + +Build Changes +------------- + +Separate build and source directories have been enabled by default for +selected recipes where it is known to work (a whitelist) and for all +recipes that inherit the :ref:`cmake <ref-classes-cmake>` class. In +future releases the :ref:`autotools <ref-classes-autotools>` class +will enable a separate build directory by default as well. Recipes +building Autotools-based software that fails to build with a separate +build directory should be changed to inherit from the +:ref:`autotools-brokensep <ref-classes-autotools>` class instead of +the ``autotools`` or ``autotools_stage``\ classes. + +.. _migration-1.6-building-qemu-native: + +``qemu-native`` +--------------- + +``qemu-native`` now builds without SDL-based graphical output support by +default. The following additional lines are needed in your +``local.conf`` to enable it: +:: + + PACKAGECONFIG_pn-qemu-native = "sdl" + ASSUME_PROVIDED += "libsdl-native" + +.. note:: + + The default + local.conf + contains these statements. Consequently, if you are building a + headless system and using a default + local.conf + file, you will need comment these two lines out. + +.. _migration-1.6-core-image-basic: + +``core-image-basic`` +-------------------- + +``core-image-basic`` has been renamed to ``core-image-full-cmdline``. + +In addition to ``core-image-basic`` being renamed, +``packagegroup-core-basic`` has been renamed to +``packagegroup-core-full-cmdline`` to match. + +.. _migration-1.6-licensing: + +Licensing +--------- + +The top-level ``LICENSE`` file has been changed to better describe the +license of the various components of :term:`OpenEmbedded-Core (OE-Core)`. However, +the licensing itself remains unchanged. + +Normally, this change would not cause any side-effects. However, some +recipes point to this file within +:term:`LIC_FILES_CHKSUM` (as +``${COREBASE}/LICENSE``) and thus the accompanying checksum must be +changed from 3f40d7994397109285ec7b81fdeb3b58 to +4d92cd373abda3937c2bc47fbc49d690. A better alternative is to have +``LIC_FILES_CHKSUM`` point to a file describing the license that is +distributed with the source that the recipe is building, if possible, +rather than pointing to ``${COREBASE}/LICENSE``. + +.. _migration-1.6-cflags-options: + +``CFLAGS`` Options +------------------ + +The "-fpermissive" option has been removed from the default +:term:`CFLAGS` value. You need to take action on +individual recipes that fail when building with this option. You need to +either patch the recipes to fix the issues reported by the compiler, or +you need to add "-fpermissive" to ``CFLAGS`` in the recipes. + +.. _migration-1.6-custom-images: + +Custom Image Output Types +------------------------- + +Custom image output types, as selected using +:term:`IMAGE_FSTYPES`, must declare their +dependencies on other image types (if any) using a new +:term:`IMAGE_TYPEDEP` variable. + +.. _migration-1.6-do-package-write-task: + +Tasks +----- + +The ``do_package_write`` task has been removed. The task is no longer +needed. + +.. _migration-1.6-update-alternatives-provider: + +``update-alternative`` Provider +------------------------------- + +The default ``update-alternatives`` provider has been changed from +``opkg`` to ``opkg-utils``. This change resolves some troublesome +circular dependencies. The runtime package has also been renamed from +``update-alternatives-cworth`` to ``update-alternatives-opkg``. + +.. _migration-1.6-virtclass-overrides: + +``virtclass`` Overrides +----------------------- + +The ``virtclass`` overrides are now deprecated. Use the equivalent class +overrides instead (e.g. ``virtclass-native`` becomes ``class-native``.) + +.. _migration-1.6-removed-renamed-recipes: + +Removed and Renamed Recipes +--------------------------- + +The following recipes have been removed: + +- ``packagegroup-toolset-native`` - This recipe is largely unused. + +- ``linux-yocto-3.8`` - Support for the Linux yocto 3.8 kernel has been + dropped. Support for the 3.10 and 3.14 kernels have been added with + the ``linux-yocto-3.10`` and ``linux-yocto-3.14`` recipes. + +- ``ocf-linux`` - This recipe has been functionally replaced using + ``cryptodev-linux``. + +- ``genext2fs`` - ``genext2fs`` is no longer used by the build system + and is unmaintained upstream. + +- ``js`` - This provided an ancient version of Mozilla's javascript + engine that is no longer needed. + +- ``zaurusd`` - The recipe has been moved to the ``meta-handheld`` + layer. + +- ``eglibc 2.17`` - Replaced by the ``eglibc 2.19`` recipe. + +- ``gcc 4.7.2`` - Replaced by the now stable ``gcc 4.8.2``. + +- ``external-sourcery-toolchain`` - this recipe is now maintained in + the ``meta-sourcery`` layer. + +- ``linux-libc-headers-yocto 3.4+git`` - Now using version 3.10 of the + ``linux-libc-headers`` by default. + +- ``meta-toolchain-gmae`` - This recipe is obsolete. + +- ``packagegroup-core-sdk-gmae`` - This recipe is obsolete. + +- ``packagegroup-core-standalone-gmae-sdk-target`` - This recipe is + obsolete. + +.. _migration-1.6-removed-classes: + +Removed Classes +--------------- + +The following classes have become obsolete and have been removed: + +- ``module_strip`` + +- ``pkg_metainfo`` + +- ``pkg_distribute`` + +- ``image-empty`` + +.. _migration-1.6-reference-bsps: + +Reference Board Support Packages (BSPs) +--------------------------------------- + +The following reference BSPs changes occurred: + +- The BeagleBoard (``beagleboard``) ARM reference hardware has been + replaced by the BeagleBone (``beaglebone``) hardware. + +- The RouterStation Pro (``routerstationpro``) MIPS reference hardware + has been replaced by the EdgeRouter Lite (``edgerouter``) hardware. + +The previous reference BSPs for the ``beagleboard`` and +``routerstationpro`` machines are still available in a new +``meta-yocto-bsp-old`` layer in the +:yocto_git:`Source Repositories <>` at +http://git.yoctoproject.org/cgit/cgit.cgi/meta-yocto-bsp-old/. + + diff --git a/poky/documentation/ref-manual/migration-1.7.rst b/poky/documentation/ref-manual/migration-1.7.rst new file mode 100644 index 000000000..82fd37d3a --- /dev/null +++ b/poky/documentation/ref-manual/migration-1.7.rst @@ -0,0 +1,225 @@ +Moving to the Yocto Project 1.7 Release +======================================= + +This section provides migration information for moving to the Yocto +Project 1.7 Release from the prior release. + +.. _migration-1.7-changes-to-setting-qemu-packageconfig-options: + +Changes to Setting QEMU ``PACKAGECONFIG`` Options in ``local.conf`` +------------------------------------------------------------------- + +The QEMU recipe now uses a number of +:term:`PACKAGECONFIG` options to enable various +optional features. The method used to set defaults for these options +means that existing ``local.conf`` files will need to be be modified to +append to ``PACKAGECONFIG`` for ``qemu-native`` and ``nativesdk-qemu`` +instead of setting it. In other words, to enable graphical output for +QEMU, you should now have these lines in ``local.conf``: +:: + + PACKAGECONFIG_append_pn-qemu-native = " sdl" + PACKAGECONFIG_append_pn-nativesdk-qemu = " sdl" + +.. _migration-1.7-minimum-git-version: + +Minimum Git version +------------------- + +The minimum :ref:`overview-manual/overview-manual-development-environment:git` +version required on the +build host is now 1.7.8 because the ``--list`` option is now required by +BitBake's Git fetcher. As always, if your host distribution does not +provide a version of Git that meets this requirement, you can use the +``buildtools-tarball`` that does. See the "`Required Git, tar, Python +and gcc Versions <#required-git-tar-python-and-gcc-versions>`__" section +for more information. + +.. _migration-1.7-autotools-class-changes: + +Autotools Class Changes +----------------------- + +The following :ref:`autotools <ref-classes-autotools>` class changes +occurred: + +- *A separate build directory is now used by default:* The + ``autotools`` class has been changed to use a directory for building + (:term:`B`), which is separate from the source directory + (:term:`S`). This is commonly referred to as ``B != S``, or + an out-of-tree build. + + If the software being built is already capable of building in a + directory separate from the source, you do not need to do anything. + However, if the software is not capable of being built in this + manner, you will need to either patch the software so that it can + build separately, or you will need to change the recipe to inherit + the :ref:`autotools-brokensep <ref-classes-autotools>` class + instead of the ``autotools`` or ``autotools_stage`` classes. + +- The ``--foreign`` option is no longer passed to ``automake`` when + running ``autoconf``: This option tells ``automake`` that a + particular software package does not follow the GNU standards and + therefore should not be expected to distribute certain files such as + ``ChangeLog``, ``AUTHORS``, and so forth. Because the majority of + upstream software packages already tell ``automake`` to enable + foreign mode themselves, the option is mostly superfluous. However, + some recipes will need patches for this change. You can easily make + the change by patching ``configure.ac`` so that it passes "foreign" + to ``AM_INIT_AUTOMAKE()``. See `this + commit <http://cgit.openembedded.org/openembedded-core/commit/?id=01943188f85ce6411717fb5bf702d609f55813f2>`__ + for an example showing how to make the patch. + +.. _migration-1.7-binary-configuration-scripts-disabled: + +Binary Configuration Scripts Disabled +------------------------------------- + +Some of the core recipes that package binary configuration scripts now +disable the scripts due to the scripts previously requiring error-prone +path substitution. Software that links against these libraries using +these scripts should use the much more robust ``pkg-config`` instead. +The list of recipes changed in this version (and their configuration +scripts) is as follows: +:: + + directfb (directfb-config) + freetype (freetype-config) + gpgme (gpgme-config) + libassuan (libassuan-config) + libcroco (croco-6.0-config) + libgcrypt (libgcrypt-config) + libgpg-error (gpg-error-config) + libksba (ksba-config) + libpcap (pcap-config) + libpcre (pcre-config) + libpng (libpng-config, libpng16-config) + libsdl (sdl-config) + libusb-compat (libusb-config) + libxml2 (xml2-config) + libxslt (xslt-config) + ncurses (ncurses-config) + neon (neon-config) + npth (npth-config) + pth (pth-config) + taglib (taglib-config) + +Additionally, support for ``pkg-config`` has been added to some recipes in the +previous list in the rare cases where the upstream software package does +not already provide it. + +.. _migration-1.7-glibc-replaces-eglibc: + +``eglibc 2.19`` Replaced with ``glibc 2.20`` +-------------------------------------------- + +Because ``eglibc`` and ``glibc`` were already fairly close, this +replacement should not require any significant changes to other software +that links to ``eglibc``. However, there were a number of minor changes +in ``glibc 2.20`` upstream that could require patching some software +(e.g. the removal of the ``_BSD_SOURCE`` feature test macro). + +``glibc 2.20`` requires version 2.6.32 or greater of the Linux kernel. +Thus, older kernels will no longer be usable in conjunction with it. + +For full details on the changes in ``glibc 2.20``, see the upstream +release notes +`here <https://sourceware.org/ml/libc-alpha/2014-09/msg00088.html>`__. + +.. _migration-1.7-kernel-module-autoloading: + +Kernel Module Autoloading +------------------------- + +The :term:`module_autoload_* <module_autoload>` variable is now +deprecated and a new +:term:`KERNEL_MODULE_AUTOLOAD` variable +should be used instead. Also, :term:`module_conf_* <module_conf>` +must now be used in conjunction with a new +:term:`KERNEL_MODULE_PROBECONF` variable. +The new variables no longer require you to specify the module name as +part of the variable name. This change not only simplifies usage but +also allows the values of these variables to be appropriately +incorporated into task signatures and thus trigger the appropriate tasks +to re-execute when changed. You should replace any references to +``module_autoload_*`` with ``KERNEL_MODULE_AUTOLOAD``, and add any +modules for which ``module_conf_*`` is specified to +``KERNEL_MODULE_PROBECONF``. + +.. _migration-1.7-qa-check-changes: + +QA Check Changes +---------------- + +The following changes have occurred to the QA check process: + +- Additional QA checks ``file-rdeps`` and ``build-deps`` have been + added in order to verify that file dependencies are satisfied (e.g. + package contains a script requiring ``/bin/bash``) and build-time + dependencies are declared, respectively. For more information, please + see the "`QA Error and Warning Messages <#ref-qa-checks>`__" chapter. + +- Package QA checks are now performed during a new + :ref:`ref-tasks-package_qa` task rather than being + part of the :ref:`ref-tasks-package` task. This allows + more parallel execution. This change is unlikely to be an issue + except for highly customized recipes that disable packaging tasks + themselves by marking them as ``noexec``. For those packages, you + will need to disable the ``do_package_qa`` task as well. + +- Files being overwritten during the + :ref:`ref-tasks-populate_sysroot` task now + trigger an error instead of a warning. Recipes should not be + overwriting files written to the sysroot by other recipes. If you + have these types of recipes, you need to alter them so that they do + not overwrite these files. + + You might now receive this error after changes in configuration or + metadata resulting in orphaned files being left in the sysroot. If + you do receive this error, the way to resolve the issue is to delete + your :term:`TMPDIR` or to move it out of the way and + then re-start the build. Anything that has been fully built up to + that point and does not need rebuilding will be restored from the + shared state cache and the rest of the build will be able to proceed + as normal. + +.. _migration-1.7-removed-recipes: + +Removed Recipes +--------------- + +The following recipes have been removed: + +- ``x-load``: This recipe has been superseded by U-boot SPL for all + Cortex-based TI SoCs. For legacy boards, the ``meta-ti`` layer, which + contains a maintained recipe, should be used instead. + +- ``ubootchart``: This recipe is obsolete. A ``bootchart2`` recipe has + been added to functionally replace it. + +- ``linux-yocto 3.4``: Support for the linux-yocto 3.4 kernel has been + dropped. Support for the 3.10 and 3.14 kernels remains, while support + for version 3.17 has been added. + +- ``eglibc`` has been removed in favor of ``glibc``. See the + "```eglibc 2.19`` Replaced with + ``glibc 2.20`` <#migration-1.7-glibc-replaces-eglibc>`__" section for + more information. + +.. _migration-1.7-miscellaneous-changes: + +Miscellaneous Changes +--------------------- + +The following miscellaneous change occurred: + +- The build history feature now writes ``build-id.txt`` instead of + ``build-id``. Additionally, ``build-id.txt`` now contains the full + build header as printed by BitBake upon starting the build. You + should manually remove old "build-id" files from your existing build + history repositories to avoid confusion. For information on the build + history feature, see the + ":ref:`dev-manual/dev-manual-common-tasks:maintaining build output quality`" + section in the Yocto Project Development Tasks Manual. + + diff --git a/poky/documentation/ref-manual/migration-1.8.rst b/poky/documentation/ref-manual/migration-1.8.rst new file mode 100644 index 000000000..d601e6b63 --- /dev/null +++ b/poky/documentation/ref-manual/migration-1.8.rst @@ -0,0 +1,183 @@ +Moving to the Yocto Project 1.8 Release +======================================= + +This section provides migration information for moving to the Yocto +Project 1.8 Release from the prior release. + +.. _migration-1.8-removed-recipes: + +Removed Recipes +--------------- + +The following recipes have been removed: + +- ``owl-video``: Functionality replaced by ``gst-player``. + +- ``gaku``: Functionality replaced by ``gst-player``. + +- ``gnome-desktop``: This recipe is now available in ``meta-gnome`` and + is no longer needed. + +- ``gsettings-desktop-schemas``: This recipe is now available in + ``meta-gnome`` and is no longer needed. + +- ``python-argparse``: The ``argparse`` module is already provided in + the default Python distribution in a package named + ``python-argparse``. Consequently, the separate ``python-argparse`` + recipe is no longer needed. + +- ``telepathy-python, libtelepathy, telepathy-glib, telepathy-idle, telepathy-mission-control``: + All these recipes have moved to ``meta-oe`` and are consequently no + longer needed by any recipes in OpenEmbedded-Core. + +- ``linux-yocto_3.10`` and ``linux-yocto_3.17``: Support for the + linux-yocto 3.10 and 3.17 kernels has been dropped. Support for the + 3.14 kernel remains, while support for 3.19 kernel has been added. + +- ``poky-feed-config-opkg``: This recipe has become obsolete and is no + longer needed. Use ``distro-feed-config`` from ``meta-oe`` instead. + +- ``libav 0.8.x``: ``libav 9.x`` is now used. + +- ``sed-native``: No longer needed. A working version of ``sed`` is + expected to be provided by the host distribution. + +.. _migration-1.8-bluez: + +BlueZ 4.x / 5.x Selection +------------------------- + +Proper built-in support for selecting BlueZ 5.x in preference to the +default of 4.x now exists. To use BlueZ 5.x, simply add "bluez5" to your +:term:`DISTRO_FEATURES` value. If you had +previously added append files (``*.bbappend``) to make this selection, +you can now remove them. + +Additionally, a ``bluetooth`` class has been added to make selection of +the appropriate bluetooth support within a recipe a little easier. If +you wish to make use of this class in a recipe, add something such as +the following: :: + + inherit bluetooth + PACKAGECONFIG ??= "${@bb.utils.contains('DISTRO_FEATURES', 'bluetooth', '${BLUEZ}', '', d)}" + PACKAGECONFIG[bluez4] = "--enable-bluetooth,--disable-bluetooth,bluez4" + PACKAGECONFIG[bluez5] = "--enable-bluez5,--disable-bluez5,bluez5" + +.. _migration-1.8-kernel-build-changes: + +Kernel Build Changes +-------------------- + +The kernel build process was changed to place the source in a common +shared work area and to place build artifacts separately in the source +code tree. In theory, migration paths have been provided for most common +usages in kernel recipes but this might not work in all cases. In +particular, users need to ensure that ``${S}`` (source files) and +``${B}`` (build artifacts) are used correctly in functions such as +:ref:`ref-tasks-configure` and +:ref:`ref-tasks-install`. For kernel recipes that do not +inherit from ``kernel-yocto`` or include ``linux-yocto.inc``, you might +wish to refer to the ``linux.inc`` file in the ``meta-oe`` layer for the +kinds of changes you need to make. For reference, here is the +`commit <http://cgit.openembedded.org/meta-openembedded/commit/meta-oe/recipes-kernel/linux/linux.inc?id=fc7132ede27ac67669448d3d2845ce7d46c6a1ee>`__ +where the ``linux.inc`` file in ``meta-oe`` was updated. + +Recipes that rely on the kernel source code and do not inherit the +module classes might need to add explicit dependencies on the +``do_shared_workdir`` kernel task, for example: :: + + do_configure[depends] += "virtual/kernel:do_shared_workdir" + +.. _migration-1.8-ssl: + +SSL 3.0 is Now Disabled in OpenSSL +---------------------------------- + +SSL 3.0 is now disabled when building OpenSSL. Disabling SSL 3.0 avoids +any lingering instances of the POODLE vulnerability. If you feel you +must re-enable SSL 3.0, then you can add an append file (``*.bbappend``) +for the ``openssl`` recipe to remove "-no-ssl3" from +:term:`EXTRA_OECONF`. + +.. _migration-1.8-default-sysroot-poisoning: + +Default Sysroot Poisoning +------------------------- + +``gcc's`` default sysroot and include directories are now "poisoned". In +other words, the sysroot and include directories are being redirected to +a non-existent location in order to catch when host directories are +being used due to the correct options not being passed. This poisoning +applies both to the cross-compiler used within the build and to the +cross-compiler produced in the SDK. + +If this change causes something in the build to fail, it almost +certainly means the various compiler flags and commands are not being +passed correctly to the underlying piece of software. In such cases, you +need to take corrective steps. + +.. _migration-1.8-rebuild-improvements: + +Rebuild Improvements +-------------------- + +Changes have been made to the :ref:`base <ref-classes-base>`, +:ref:`autotools <ref-classes-autotools>`, and +:ref:`cmake <ref-classes-cmake>` classes to clean out generated files +when the :ref:`ref-tasks-configure` task needs to be +re-executed. + +One of the improvements is to attempt to run "make clean" during the +``do_configure`` task if a ``Makefile`` exists. Some software packages +do not provide a working clean target within their make files. If you +have such recipes, you need to set +:term:`CLEANBROKEN` to "1" within the recipe, for example: :: + + CLEANBROKEN = "1" + +.. _migration-1.8-qa-check-and-validation-changes: + +QA Check and Validation Changes +------------------------------- + +The following QA Check and Validation Changes have occurred: + +- Usage of ``PRINC`` previously triggered a warning. It now triggers an + error. You should remove any remaining usage of ``PRINC`` in any + recipe or append file. + +- An additional QA check has been added to detect usage of ``${D}`` in + :term:`FILES` values where :term:`D` values + should not be used at all. The same check ensures that ``$D`` is used + in ``pkg_preinst/pkg_postinst/pkg_prerm/pkg_postrm`` functions + instead of ``${D}``. + +- :term:`S` now needs to be set to a valid value within a + recipe. If ``S`` is not set in the recipe, the directory is not + automatically created. If ``S`` does not point to a directory that + exists at the time the :ref:`ref-tasks-unpack` task + finishes, a warning will be shown. + +- :term:`LICENSE` is now validated for correct + formatting of multiple licenses. If the format is invalid (e.g. + multiple licenses are specified with no operators to specify how the + multiple licenses interact), then a warning will be shown. + +.. _migration-1.8-miscellaneous-changes: + +Miscellaneous Changes +--------------------- + +The following miscellaneous changes have occurred: + +- The ``send-error-report`` script now expects a "-s" option to be + specified before the server address. This assumes a server address is + being specified. + +- The ``oe-pkgdata-util`` script now expects a "-p" option to be + specified before the ``pkgdata`` directory, which is now optional. If + the ``pkgdata`` directory is not specified, the script will run + BitBake to query :term:`PKGDATA_DIR` from the + build environment. + + diff --git a/poky/documentation/ref-manual/migration-2.0.rst b/poky/documentation/ref-manual/migration-2.0.rst new file mode 100644 index 000000000..570486ba0 --- /dev/null +++ b/poky/documentation/ref-manual/migration-2.0.rst @@ -0,0 +1,281 @@ +Moving to the Yocto Project 2.0 Release +======================================= + +This section provides migration information for moving to the Yocto +Project 2.0 Release from the prior release. + +.. _migration-2.0-gcc-5: + +GCC 5 +----- + +The default compiler is now GCC 5.2. This change has required fixes for +compilation errors in a number of other recipes. + +One important example is a fix for when the Linux kernel freezes at boot +time on ARM when built with GCC 5. If you are using your own kernel +recipe or source tree and building for ARM, you will likely need to +apply this +`patch <https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/commit?id=a077224fd35b2f7fbc93f14cf67074fc792fbac2>`__. +The standard ``linux-yocto`` kernel source tree already has a workaround +for the same issue. + +For further details, see https://gcc.gnu.org/gcc-5/changes.html +and the porting guide at +https://gcc.gnu.org/gcc-5/porting_to.html. + +Alternatively, you can switch back to GCC 4.9 or 4.8 by setting +``GCCVERSION`` in your configuration, as follows: +:: + + GCCVERSION = "4.9%" + +.. _migration-2.0-Gstreamer-0.10-removed: + +Gstreamer 0.10 Removed +---------------------- + +Gstreamer 0.10 has been removed in favor of Gstreamer 1.x. As part of +the change, recipes for Gstreamer 0.10 and related software are now +located in ``meta-multimedia``. This change results in Qt4 having Phonon +and Gstreamer support in QtWebkit disabled by default. + +.. _migration-2.0-removed-recipes: + +Removed Recipes +--------------- + +The following recipes have been moved or removed: + +- ``bluez4``: The recipe is obsolete and has been moved due to + ``bluez5`` becoming fully integrated. The ``bluez4`` recipe now + resides in ``meta-oe``. + +- ``gamin``: The recipe is obsolete and has been removed. + +- ``gnome-icon-theme``: The recipe's functionally has been replaced by + ``adwaita-icon-theme``. + +- Gstreamer 0.10 Recipes: Recipes for Gstreamer 0.10 have been removed + in favor of the recipes for Gstreamer 1.x. + +- ``insserv``: The recipe is obsolete and has been removed. + +- ``libunique``: The recipe is no longer used and has been moved to + ``meta-oe``. + +- ``midori``: The recipe's functionally has been replaced by + ``epiphany``. + +- ``python-gst``: The recipe is obsolete and has been removed since it + only contains bindings for Gstreamer 0.10. + +- ``qt-mobility``: The recipe is obsolete and has been removed since it + requires ``Gstreamer 0.10``, which has been replaced. + +- ``subversion``: All 1.6.x versions of this recipe have been removed. + +- ``webkit-gtk``: The older 1.8.3 version of this recipe has been + removed in favor of ``webkitgtk``. + +.. _migration-2.0-bitbake-datastore-improvements: + +BitBake datastore improvements +------------------------------ + +The method by which BitBake's datastore handles overrides has changed. +Overrides are now applied dynamically and ``bb.data.update_data()`` is +now a no-op. Thus, ``bb.data.update_data()`` is no longer required in +order to apply the correct overrides. In practice, this change is +unlikely to require any changes to Metadata. However, these minor +changes in behavior exist: + +- All potential overrides are now visible in the variable history as + seen when you run the following: + :: + + $ bitbake -e + +- ``d.delVar('``\ VARNAME\ ``')`` and + ``d.setVar('``\ VARNAME\ ``', None)`` result in the variable and all + of its overrides being cleared out. Before the change, only the + non-overridden values were cleared. + +.. _migration-2.0-shell-message-function-changes: + +Shell Message Function Changes +------------------------------ + +The shell versions of the BitBake message functions (i.e. ``bbdebug``, +``bbnote``, ``bbwarn``, ``bbplain``, ``bberror``, and ``bbfatal``) are +now connected through to their BitBake equivalents ``bb.debug()``, +``bb.note()``, ``bb.warn()``, ``bb.plain()``, ``bb.error()``, and +``bb.fatal()``, respectively. Thus, those message functions that you +would expect to be printed by the BitBake UI are now actually printed. +In practice, this change means two things: + +- If you now see messages on the console that you did not previously + see as a result of this change, you might need to clean up the calls + to ``bbwarn``, ``bberror``, and so forth. Or, you might want to + simply remove the calls. + +- The ``bbfatal`` message function now suppresses the full error log in + the UI, which means any calls to ``bbfatal`` where you still wish to + see the full error log should be replaced by ``die`` or + ``bbfatal_log``. + +.. _migration-2.0-extra-development-debug-package-cleanup: + +Extra Development/Debug Package Cleanup +--------------------------------------- + +The following recipes have had extra ``dev/dbg`` packages removed: + +- ``acl`` + +- ``apmd`` + +- ``aspell`` + +- ``attr`` + +- ``augeas`` + +- ``bzip2`` + +- ``cogl`` + +- ``curl`` + +- ``elfutils`` + +- ``gcc-target`` + +- ``libgcc`` + +- ``libtool`` + +- ``libxmu`` + +- ``opkg`` + +- ``pciutils`` + +- ``rpm`` + +- ``sysfsutils`` + +- ``tiff`` + +- ``xz`` + +All of the above recipes now conform to the standard packaging scheme +where a single ``-dev``, ``-dbg``, and ``-staticdev`` package exists per +recipe. + +.. _migration-2.0-recipe-maintenance-tracking-data-moved-to-oe-core: + +Recipe Maintenance Tracking Data Moved to OE-Core +------------------------------------------------- + +Maintenance tracking data for recipes that was previously part of +``meta-yocto`` has been moved to :term:`OpenEmbedded-Core (OE-Core)`. The change +includes ``package_regex.inc`` and ``distro_alias.inc``, which are +typically enabled when using the ``distrodata`` class. Additionally, the +contents of ``upstream_tracking.inc`` has now been split out to the +relevant recipes. + +.. _migration-2.0-automatic-stale-sysroot-file-cleanup: + +Automatic Stale Sysroot File Cleanup +------------------------------------ + +Stale files from recipes that no longer exist in the current +configuration are now automatically removed from sysroot as well as +removed from any other place managed by shared state. This automatic +cleanup means that the build system now properly handles situations such +as renaming the build system side of recipes, removal of layers from +``bblayers.conf``, and :term:`DISTRO_FEATURES` +changes. + +Additionally, work directories for old versions of recipes are now +pruned. If you wish to disable pruning old work directories, you can set +the following variable in your configuration: +:: + + SSTATE_PRUNE_OBSOLETEWORKDIR = "0" + +.. _migration-2.0-linux-yocto-kernel-metadata-repository-now-split-from-source: + +``linux-yocto`` Kernel Metadata Repository Now Split from Source +---------------------------------------------------------------- + +The ``linux-yocto`` tree has up to now been a combined set of kernel +changes and configuration (meta) data carried in a single tree. While +this format is effective at keeping kernel configuration and source +modifications synchronized, it is not always obvious to developers how +to manipulate the Metadata as compared to the source. + +Metadata processing has now been removed from the +:ref:`kernel-yocto <ref-classes-kernel-yocto>` class and the external +Metadata repository ``yocto-kernel-cache``, which has always been used +to seed the ``linux-yocto`` "meta" branch. This separate ``linux-yocto`` +cache repository is now the primary location for this data. Due to this +change, ``linux-yocto`` is no longer able to process combined trees. +Thus, if you need to have your own combined kernel repository, you must +do the split there as well and update your recipes accordingly. See the +``meta/recipes-kernel/linux/linux-yocto_4.1.bb`` recipe for an example. + +.. _migration-2.0-additional-qa-checks: + +Additional QA checks +-------------------- + +The following QA checks have been added: + +- Added a "host-user-contaminated" check for ownership issues for + packaged files outside of ``/home``. The check looks for files that + are incorrectly owned by the user that ran BitBake instead of owned + by a valid user in the target system. + +- Added an "invalid-chars" check for invalid (non-UTF8) characters in + recipe metadata variable values (i.e. + :term:`DESCRIPTION`, + :term:`SUMMARY`, :term:`LICENSE`, and + :term:`SECTION`). Some package managers do not support + these characters. + +- Added an "invalid-packageconfig" check for any options specified in + :term:`PACKAGECONFIG` that do not match any + ``PACKAGECONFIG`` option defined for the recipe. + +.. _migration-2.0-miscellaneous: + +Miscellaneous Changes +--------------------- + +These additional changes exist: + +- ``gtk-update-icon-cache`` has been renamed to ``gtk-icon-utils``. + +- The ``tools-profile`` :term:`IMAGE_FEATURES` + item as well as its corresponding packagegroup and + ``packagegroup-core-tools-profile`` no longer bring in ``oprofile``. + Bringing in ``oprofile`` was originally added to aid compilation on + resource-constrained targets. However, this aid has not been widely + used and is not likely to be used going forward due to the more + powerful target platforms and the existence of better + cross-compilation tools. + +- The :term:`IMAGE_FSTYPES` variable's default + value now specifies ``ext4`` instead of ``ext3``. + +- All support for the ``PRINC`` variable has been removed. + +- The ``packagegroup-core-full-cmdline`` packagegroup no longer brings + in ``lighttpd`` due to the fact that bringing in ``lighttpd`` is not + really in line with the packagegroup's purpose, which is to add full + versions of command-line tools that by default are provided by + ``busybox``. + + diff --git a/poky/documentation/ref-manual/migration-2.1.rst b/poky/documentation/ref-manual/migration-2.1.rst new file mode 100644 index 000000000..a1fd3ea81 --- /dev/null +++ b/poky/documentation/ref-manual/migration-2.1.rst @@ -0,0 +1,434 @@ +Moving to the Yocto Project 2.1 Release +======================================= + +This section provides migration information for moving to the Yocto +Project 2.1 Release from the prior release. + +.. _migration-2.1-variable-expansion-in-python-functions: + +Variable Expansion in Python Functions +-------------------------------------- + +Variable expressions, such as ``${``\ VARNAME\ ``}`` no longer expand +automatically within Python functions. Suppressing expansion was done to +allow Python functions to construct shell scripts or other code for +situations in which you do not want such expressions expanded. For any +existing code that relies on these expansions, you need to change the +expansions to expand the value of individual variables through +``d.getVar()``. To alternatively expand more complex expressions, use +``d.expand()``. + +.. _migration-2.1-overrides-must-now-be-lower-case: + +Overrides Must Now be Lower-Case +-------------------------------- + +The convention for overrides has always been for them to be lower-case +characters. This practice is now a requirement as BitBake's datastore +now assumes lower-case characters in order to give a slight performance +boost during parsing. In practical terms, this requirement means that +anything that ends up in :term:`OVERRIDES` must now +appear in lower-case characters (e.g. values for ``MACHINE``, +``TARGET_ARCH``, ``DISTRO``, and also recipe names if +``_pn-``\ recipename overrides are to be effective). + +.. _migration-2.1-expand-parameter-to-getvar-and-getvarflag-now-mandatory: + +Expand Parameter to ``getVar()`` and ``getVarFlag()`` is Now Mandatory +---------------------------------------------------------------------- + +The expand parameter to ``getVar()`` and ``getVarFlag()`` previously +defaulted to False if not specified. Now, however, no default exists so +one must be specified. You must change any ``getVar()`` calls that do +not specify the final expand parameter to calls that do specify the +parameter. You can run the following ``sed`` command at the base of a +layer to make this change: +:: + + sed -e 's:\(\.getVar([^,()]*\)):\1, False):g' -i `grep -ril getVar *` + sed -e 's:\(\.getVarFlag([^,()]*,[^,()]*\)):\1, False):g' -i `grep -ril getVarFlag *` + +.. note:: + + The reason for this change is that it prepares the way for changing + the default to True in a future Yocto Project release. This future + change is a much more sensible default than False. However, the + change needs to be made gradually as a sudden change of the default + would potentially cause side-effects that would be difficult to + detect. + +.. _migration-2.1-makefile-environment-changes: + +Makefile Environment Changes +---------------------------- + +:term:`EXTRA_OEMAKE` now defaults to "" instead of +"-e MAKEFLAGS=". Setting ``EXTRA_OEMAKE`` to "-e MAKEFLAGS=" by default +was a historical accident that has required many classes (e.g. +``autotools``, ``module``) and recipes to override this default in order +to work with sensible build systems. When upgrading to the release, you +must edit any recipe that relies upon this old default by either setting +``EXTRA_OEMAKE`` back to "-e MAKEFLAGS=" or by explicitly setting any +required variable value overrides using ``EXTRA_OEMAKE``, which is +typically only needed when a Makefile sets a default value for a +variable that is inappropriate for cross-compilation using the "=" +operator rather than the "?=" operator. + +.. _migration-2.1-libexecdir-reverted-to-prefix-libexec: + +``libexecdir`` Reverted to ``${prefix}/libexec`` +------------------------------------------------ + +The use of ``${libdir}/${BPN}`` as ``libexecdir`` is different as +compared to all other mainstream distributions, which either uses +``${prefix}/libexec`` or ``${libdir}``. The use is also contrary to the +GNU Coding Standards (i.e. +https://www.gnu.org/prep/standards/html_node/Directory-Variables.html) +that suggest ``${prefix}/libexec`` and also notes that any +package-specific nesting should be done by the package itself. Finally, +having ``libexecdir`` change between recipes makes it very difficult for +different recipes to invoke binaries that have been installed into +``libexecdir``. The Filesystem Hierarchy Standard (i.e. +http://refspecs.linuxfoundation.org/FHS_3.0/fhs/ch04s07.html) now +recognizes the use of ``${prefix}/libexec/``, giving distributions the +choice between ``${prefix}/lib`` or ``${prefix}/libexec`` without +breaking FHS. + +.. _migration-2.1-ac-cv-sizeof-off-t-no-longer-cached-in-site-files: + +``ac_cv_sizeof_off_t`` is No Longer Cached in Site Files +-------------------------------------------------------- + +For recipes inheriting the :ref:`autotools <ref-classes-autotools>` +class, ``ac_cv_sizeof_off_t`` is no longer cached in the site files for +``autoconf``. The reason for this change is because the +``ac_cv_sizeof_off_t`` value is not necessarily static per architecture +as was previously assumed. Rather, the value changes based on whether +large file support is enabled. For most software that uses ``autoconf``, +this change should not be a problem. However, if you have a recipe that +bypasses the standard :ref:`ref-tasks-configure` task +from the ``autotools`` class and the software the recipe is building +uses a very old version of ``autoconf``, the recipe might be incapable +of determining the correct size of ``off_t`` during ``do_configure``. + +The best course of action is to patch the software as necessary to allow +the default implementation from the ``autotools`` class to work such +that ``autoreconf`` succeeds and produces a working configure script, +and to remove the overridden ``do_configure`` task such that the default +implementation does get used. + +.. _migration-2.1-image-generation-split-out-from-filesystem-generation: + +Image Generation is Now Split Out from Filesystem Generation +------------------------------------------------------------ + +Previously, for image recipes the :ref:`ref-tasks-rootfs` +task assembled the filesystem and then from that filesystem generated +images. With this Yocto Project release, image generation is split into +separate ```do_image_*`` <#ref-tasks-image>`__ tasks for clarity both in +operation and in the code. + +For most cases, this change does not present any problems. However, if +you have made customizations that directly modify the ``do_rootfs`` task +or that mention ``do_rootfs``, you might need to update those changes. +In particular, if you had added any tasks after ``do_rootfs``, you +should make edits so that those tasks are after the +```do_image_complete`` <#ref-tasks-image-complete>`__ task rather than +after ``do_rootfs`` so that the your added tasks run at the correct +time. + +A minor part of this restructuring is that the post-processing +definitions and functions have been moved from the +:ref:`image <ref-classes-image>` class to the +:ref:`rootfs-postcommands <ref-classes-rootfs*>` class. Functionally, +however, they remain unchanged. + +.. _migration-2.1-removed-recipes: + +Removed Recipes +--------------- + +The following recipes have been removed in the 2.1 release: + +- ``gcc`` version 4.8: Versions 4.9 and 5.3 remain. + +- ``qt4``: All support for Qt 4.x has been moved out to a separate + ``meta-qt4`` layer because Qt 4 is no longer supported upstream. + +- ``x11vnc``: Moved to the ``meta-oe`` layer. + +- ``linux-yocto-3.14``: No longer supported. + +- ``linux-yocto-3.19``: No longer supported. + +- ``libjpeg``: Replaced by the ``libjpeg-turbo`` recipe. + +- ``pth``: Became obsolete. + +- ``liboil``: Recipe is no longer needed and has been moved to the + ``meta-multimedia`` layer. + +- ``gtk-theme-torturer``: Recipe is no longer needed and has been moved + to the ``meta-gnome`` layer. + +- ``gnome-mime-data``: Recipe is no longer needed and has been moved to + the ``meta-gnome`` layer. + +- ``udev``: Replaced by the ``eudev`` recipe for compatibility when + using ``sysvinit`` with newer kernels. + +- ``python-pygtk``: Recipe became obsolete. + +- ``adt-installer``: Recipe became obsolete. See the "`ADT + Removed <#migration-2.1-adt-removed>`__" section for more + information. + +.. _migration-2.1-class-changes: + +Class Changes +------------- + +The following classes have changed: + +- ``autotools_stage``: Removed because the + :ref:`autotools <ref-classes-autotools>` class now provides its + functionality. Recipes that inherited from ``autotools_stage`` should + now inherit from ``autotools`` instead. + +- ``boot-directdisk``: Merged into the ``image-vm`` class. The + ``boot-directdisk`` class was rarely directly used. Consequently, + this change should not cause any issues. + +- ``bootimg``: Merged into the + :ref:`image-live <ref-classes-image-live>` class. The ``bootimg`` + class was rarely directly used. Consequently, this change should not + cause any issues. + +- ``packageinfo``: Removed due to its limited use by the Hob UI, which + has itself been removed. + +.. _migration-2.1-build-system-ui-changes: + +Build System User Interface Changes +----------------------------------- + +The following changes have been made to the build system user interface: + +- *Hob GTK+-based UI*: Removed because it is unmaintained and based on + the outdated GTK+ 2 library. The Toaster web-based UI is much more + capable and is actively maintained. See the + ":ref:`toaster-manual/toaster-manual-setup-and-use:using the toaster web interface`" + section in the Toaster User Manual for more information on this + interface. + +- *"puccho" BitBake UI*: Removed because is unmaintained and no longer + useful. + +.. _migration-2.1-adt-removed: + +ADT Removed +----------- + +The Application Development Toolkit (ADT) has been removed because its +functionality almost completely overlapped with the :ref:`standard +SDK <sdk-manual/sdk-using:using the standard sdk>` and the +:ref:`extensible SDK <sdk-manual/sdk-extensible:using the extensible sdk>`. For +information on these SDKs and how to build and use them, see the +:doc:`../sdk-manual/sdk-manual` manual. + +.. note:: + + The Yocto Project Eclipse IDE Plug-in is still supported and is not + affected by this change. + +.. _migration-2.1-poky-reference-distribution-changes: + +Poky Reference Distribution Changes +----------------------------------- + +The following changes have been made for the Poky distribution: + +- The ``meta-yocto`` layer has been renamed to ``meta-poky`` to better + match its purpose, which is to provide the Poky reference + distribution. The ``meta-yocto-bsp`` layer retains its original name + since it provides reference machines for the Yocto Project and it is + otherwise unrelated to Poky. References to ``meta-yocto`` in your + ``conf/bblayers.conf`` should automatically be updated, so you should + not need to change anything unless you are relying on this naming + elsewhere. + +- The :ref:`uninative <ref-classes-uninative>` class is now enabled + by default in Poky. This class attempts to isolate the build system + from the host distribution's C library and makes re-use of native + shared state artifacts across different host distributions practical. + With this class enabled, a tarball containing a pre-built C library + is downloaded at the start of the build. + + The ``uninative`` class is enabled through the + ``meta/conf/distro/include/yocto-uninative.inc`` file, which for + those not using the Poky distribution, can include to easily enable + the same functionality. + + Alternatively, if you wish to build your own ``uninative`` tarball, + you can do so by building the ``uninative-tarball`` recipe, making it + available to your build machines (e.g. over HTTP/HTTPS) and setting a + similar configuration as the one set by ``yocto-uninative.inc``. + +- Static library generation, for most cases, is now disabled by default + in the Poky distribution. Disabling this generation saves some build + time as well as the size used for build output artifacts. + + Disabling this library generation is accomplished through a + ``meta/conf/distro/include/no-static-libs.inc``, which for those not + using the Poky distribution can easily include to enable the same + functionality. + + Any recipe that needs to opt-out of having the "--disable-static" + option specified on the configure command line either because it is + not a supported option for the configure script or because static + libraries are needed should set the following variable: + DISABLE_STATIC = "" + +- The separate ``poky-tiny`` distribution now uses the musl C library + instead of a heavily pared down ``glibc``. Using musl results in a + smaller distribution and facilitates much greater maintainability + because musl is designed to have a small footprint. + + If you have used ``poky-tiny`` and have customized the ``glibc`` + configuration you will need to redo those customizations with musl + when upgrading to the new release. + +.. _migration-2.1-packaging-changes: + +Packaging Changes +----------------- + +The following changes have been made to packaging: + +- The ``runuser`` and ``mountpoint`` binaries, which were previously in + the main ``util-linux`` package, have been split out into the + ``util-linux-runuser`` and ``util-linux-mountpoint`` packages, + respectively. + +- The ``python-elementtree`` package has been merged into the + ``python-xml`` package. + +.. _migration-2.1-tuning-file-changes: + +Tuning File Changes +------------------- + +The following changes have been made to the tuning files: + +- The "no-thumb-interwork" tuning feature has been dropped from the ARM + tune include files. Because interworking is required for ARM EABI, + attempting to disable it through a tuning feature no longer makes + sense. + + .. note:: + + Support for ARM OABI was deprecated in gcc 4.7. + +- The ``tune-cortexm*.inc`` and ``tune-cortexr4.inc`` files have been + removed because they are poorly tested. Until the OpenEmbedded build + system officially gains support for CPUs without an MMU, these tuning + files would probably be better maintained in a separate layer if + needed. + +.. _migration-2.1-supporting-gobject-introspection: + +Supporting GObject Introspection +-------------------------------- + +This release supports generation of GLib Introspective Repository (GIR) +files through GObject introspection, which is the standard mechanism for +accessing GObject-based software from runtime environments. You can +enable, disable, and test the generation of this data. See the +":ref:`dev-manual/dev-manual-common-tasks:enabling gobject introspection support`" +section in the Yocto Project Development Tasks Manual for more +information. + +.. _migration-2.1-miscellaneous-changes: + +Miscellaneous Changes +--------------------- + +These additional changes exist: + +- The minimum Git version has been increased to 1.8.3.1. If your host + distribution does not provide a sufficiently recent version, you can + install the buildtools, which will provide it. See the "`Required + Git, tar, Python and gcc + Versions <#required-git-tar-python-and-gcc-versions>`__" section for + more information on the buildtools tarball. + +- The buggy and incomplete support for the RPM version 4 package + manager has been removed. The well-tested and maintained support for + RPM version 5 remains. + +- Previously, the following list of packages were removed if + package-management was not in + :term:`IMAGE_FEATURES`, regardless of any + dependencies: + :: + + update-rc.d + base-passwd + shadow + update-alternatives + + run-postinsts With the Yocto Project 2.1 release, these packages are + only removed if "read-only-rootfs" is in ``IMAGE_FEATURES``, since + they might still be needed for a read-write image even in the absence + of a package manager (e.g. if users need to be added, modified, or + removed at runtime). + +- The + :ref:`devtool modify <sdk-manual/sdk-extensible:use \`\`devtool modify\`\` to modify the source of an existing component>` + command now defaults to extracting the source since that is most + commonly expected. The "-x" or "--extract" options are now no-ops. If + you wish to provide your own existing source tree, you will now need + to specify either the "-n" or "--no-extract" options when running + ``devtool modify``. + +- If the formfactor for a machine is either not supplied or does not + specify whether a keyboard is attached, then the default is to assume + a keyboard is attached rather than assume no keyboard. This change + primarily affects the Sato UI. + +- The ``.debug`` directory packaging is now automatic. If your recipe + builds software that installs binaries into directories other than + the standard ones, you no longer need to take care of setting + ``FILES_${PN}-dbg`` to pick up the resulting ``.debug`` directories + as these directories are automatically found and added. + +- Inaccurate disk and CPU percentage data has been dropped from + ``buildstats`` output. This data has been replaced with + ``getrusage()`` data and corrected IO statistics. You will probably + need to update any custom code that reads the ``buildstats`` data. + +- The ``meta/conf/distro/include/package_regex.inc`` is now deprecated. + The contents of this file have been moved to individual recipes. + + .. note:: + + Because this file will likely be removed in a future Yocto Project + release, it is suggested that you remove any references to the + file that might be in your configuration. + +- The ``v86d/uvesafb`` has been removed from the ``genericx86`` and + ``genericx86-64`` reference machines, which are provided by the + ``meta-yocto-bsp`` layer. Most modern x86 boards do not rely on this + file and it only adds kernel error messages during startup. If you do + still need to support ``uvesafb``, you can simply add ``v86d`` to + your image. + +- Build sysroot paths are now removed from debug symbol files. Removing + these paths means that remote GDB using an unstripped build system + sysroot will no longer work (although this was never documented to + work). The supported method to accomplish something similar is to set + ``IMAGE_GEN_DEBUGFS`` to "1", which will generate a companion debug + image containing unstripped binaries and associated debug sources + alongside the image. + + diff --git a/poky/documentation/ref-manual/migration-2.2.rst b/poky/documentation/ref-manual/migration-2.2.rst new file mode 100644 index 000000000..59d0eeeb9 --- /dev/null +++ b/poky/documentation/ref-manual/migration-2.2.rst @@ -0,0 +1,451 @@ +Moving to the Yocto Project 2.2 Release +======================================= + +This section provides migration information for moving to the Yocto +Project 2.2 Release from the prior release. + +.. _migration-2.2-minimum-kernel-version: + +Minimum Kernel Version +---------------------- + +The minimum kernel version for the target system and for SDK is now +3.2.0, due to the upgrade to ``glibc 2.24``. Specifically, for +AArch64-based targets the version is 3.14. For Nios II-based targets, +the minimum kernel version is 3.19. + +.. note:: + + For x86 and x86_64, you can reset + OLDEST_KERNEL + to anything down to 2.6.32 if desired. + +.. _migration-2.2-staging-directories-in-sysroot-simplified: + +Staging Directories in Sysroot Has Been Simplified +-------------------------------------------------- + +The way directories are staged in sysroot has been simplified and +introduces the new :term:`SYSROOT_DIRS`, +:term:`SYSROOT_DIRS_NATIVE`, and +:term:`SYSROOT_DIRS_BLACKLIST`. See the +`v2 patch series on the OE-Core Mailing +List <http://lists.openembedded.org/pipermail/openembedded-core/2016-May/121365.html>`__ +for additional information. + +.. _migration-2.2-removal-of-old-images-from-tmp-deploy-now-enabled: + +Removal of Old Images and Other Files in ``tmp/deploy`` Now Enabled +------------------------------------------------------------------- + +Removal of old images and other files in ``tmp/deploy/`` is now enabled +by default due to a new staging method used for those files. As a result +of this change, the ``RM_OLD_IMAGE`` variable is now redundant. + +.. _migration-2.2-python-changes: + +Python Changes +-------------- + +The following changes for Python occurred: + +.. _migration-2.2-bitbake-now-requires-python-3.4: + +BitBake Now Requires Python 3.4+ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +BitBake requires Python 3.4 or greater. + +.. _migration-2.2-utf-8-locale-required-on-build-host: + +UTF-8 Locale Required on Build Host +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A UTF-8 locale is required on the build host due to Python 3. Since +C.UTF-8 is not a standard, the default is en_US.UTF-8. + +.. _migration-2.2-metadata-now-must-use-python-3-syntax: + +Metadata Must Now Use Python 3 Syntax +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The metadata is now required to use Python 3 syntax. For help preparing +metadata, see any of the many Python 3 porting guides available. +Alternatively, you can reference the conversion commits for Bitbake and +you can use :term:`OpenEmbedded-Core (OE-Core)` as a guide for changes. Following are +particular areas of interest: + + - subprocess command-line pipes needing locale decoding + + - the syntax for octal values changed + + - the ``iter*()`` functions changed name \* iterators now return views, not lists + + - changed names for Python modules + +.. _migration-2.2-target-python-recipes-switched-to-python-3: + +Target Python Recipes Switched to Python 3 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Most target Python recipes have now been switched to Python 3. +Unfortunately, systems using RPM as a package manager and providing +online package-manager support through SMART still require Python 2. + +.. note:: + + Python 2 and recipes that use it can still be built for the target as + with previous versions. + +.. _migration-2.2-buildtools-tarball-includes-python-3: + +``buildtools-tarball`` Includes Python 3 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``buildtools-tarball`` now includes Python 3. + +.. _migration-2.2-uclibc-replaced-by-musl: + +uClibc Replaced by musl +----------------------- + +uClibc has been removed in favor of musl. Musl has matured, is better +maintained, and is compatible with a wider range of applications as +compared to uClibc. + +.. _migration-2.2-B-no-longer-default-working-directory-for-tasks: + +``${B}`` No Longer Default Working Directory for Tasks +------------------------------------------------------ + +``${``\ :term:`B`\ ``}`` is no longer the default working +directory for tasks. Consequently, any custom tasks you define now need +to either have the +``[``\ :ref:`dirs <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:variable flags>`\ ``]`` flag +set, or the task needs to change into the appropriate working directory +manually (e.g using ``cd`` for a shell task). + +.. note:: + + The preferred method is to use the + [dirs] + flag. + +.. _migration-2.2-runqemu-ported-to-python: + +``runqemu`` Ported to Python +---------------------------- + +``runqemu`` has been ported to Python and has changed behavior in some +cases. Previous usage patterns continue to be supported. + +The new ``runqemu`` is a Python script. Machine knowledge is no longer +hardcoded into ``runqemu``. You can choose to use the ``qemuboot`` +configuration file to define the BSP's own arguments and to make it +bootable with ``runqemu``. If you use a configuration file, use the +following form: +:: + + image-name-machine.qemuboot.conf + +The configuration file +enables fine-grained tuning of options passed to QEMU without the +``runqemu`` script hard-coding any knowledge about different machines. +Using a configuration file is particularly convenient when trying to use +QEMU with machines other than the ``qemu*`` machines in +:term:`OpenEmbedded-Core (OE-Core)`. The ``qemuboot.conf`` file is generated by the +``qemuboot`` class when the root filesystem is being build (i.e. build +rootfs). QEMU boot arguments can be set in BSP's configuration file and +the ``qemuboot`` class will save them to ``qemuboot.conf``. + +If you want to use ``runqemu`` without a configuration file, use the +following command form: +:: + + $ runqemu machine rootfs kernel [options] + +Supported machines are as follows: + + - qemuarm + - qemuarm64 + - qemux86 + - qemux86-64 + - qemuppc + - qemumips + - qemumips64 + - qemumipsel + - qemumips64el + +Consider the +following example, which uses the ``qemux86-64`` machine, provides a +root filesystem, provides an image, and uses the ``nographic`` option: :: + + $ runqemu qemux86-64 tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64.ext4 tmp/deploy/images/qemux86-64/bzImage nographic + +Following is a list of variables that can be set in configuration files +such as ``bsp.conf`` to enable the BSP to be booted by ``runqemu``: + +.. note:: + + "QB" means "QEMU Boot". + +:: + + QB_SYSTEM_NAME: QEMU name (e.g. "qemu-system-i386") + QB_OPT_APPEND: Options to append to QEMU (e.g. "-show-cursor") + QB_DEFAULT_KERNEL: Default kernel to boot (e.g. "bzImage") + QB_DEFAULT_FSTYPE: Default FSTYPE to boot (e.g. "ext4") + QB_MEM: Memory (e.g. "-m 512") + QB_MACHINE: QEMU machine (e.g. "-machine virt") + QB_CPU: QEMU cpu (e.g. "-cpu qemu32") + QB_CPU_KVM: Similar to QB_CPU except used for kvm support (e.g. "-cpu kvm64") + QB_KERNEL_CMDLINE_APPEND: Options to append to the kernel's -append + option (e.g. "console=ttyS0 console=tty") + QB_DTB: QEMU dtb name + QB_AUDIO_DRV: QEMU audio driver (e.g. "alsa", set it when support audio) + QB_AUDIO_OPT: QEMU audio option (e.g. "-soundhw ac97,es1370"), which is used + when QB_AUDIO_DRV is set. + QB_KERNEL_ROOT: Kernel's root (e.g. /dev/vda) + QB_TAP_OPT: Network option for 'tap' mode (e.g. + "-netdev tap,id=net0,ifname=@TAP@,script=no,downscript=no -device virtio-net-device,netdev=net0"). + runqemu will replace "@TAP@" with the one that is used, such as tap0, tap1 ... + QB_SLIRP_OPT: Network option for SLIRP mode (e.g. "-netdev user,id=net0 -device virtio-net-device,netdev=net0") + QB_ROOTFS_OPT: Used as rootfs (e.g. + "-drive id=disk0,file=@ROOTFS@,if=none,format=raw -device virtio-blk-device,drive=disk0"). + runqemu will replace "@ROOTFS@" with the one which is used, such as + core-image-minimal-qemuarm64.ext4. + QB_SERIAL_OPT: Serial port (e.g. "-serial mon:stdio") + QB_TCPSERIAL_OPT: tcp serial port option (e.g. + " -device virtio-serial-device -chardev socket,id=virtcon,port=@PORT@,host=127.0.0.1 -device virtconsole,chardev=virtcon" + runqemu will replace "@PORT@" with the port number which is used. + +To use ``runqemu``, set :term:`IMAGE_CLASSES` as +follows and run ``runqemu``: + +.. note:: + + For command-line syntax, use + runqemu help + . + +:: + + IMAGE_CLASSES += "qemuboot" + +.. _migration-2.2-default-linker-hash-style-changed: + +Default Linker Hash Style Changed +--------------------------------- + +The default linker hash style for ``gcc-cross`` is now "sysv" in order +to catch recipes that are building software without using the +OpenEmbedded :term:`LDFLAGS`. This change could result in +seeing some "No GNU_HASH in the elf binary" QA issues when building such +recipes. You need to fix these recipes so that they use the expected +``LDFLAGS``. Depending on how the software is built, the build system +used by the software (e.g. a Makefile) might need to be patched. +However, sometimes making this fix is as simple as adding the following +to the recipe: +:: + + TARGET_CC_ARCH += "${LDFLAGS}" + +.. _migration-2.2-kernel-image-base-name-no-longer-uses-kernel-imagetype: + +``KERNEL_IMAGE_BASE_NAME`` no Longer Uses ``KERNEL_IMAGETYPE`` +-------------------------------------------------------------- + +The ``KERNEL_IMAGE_BASE_NAME`` variable no longer uses the +:term:`KERNEL_IMAGETYPE` variable to create the +image's base name. Because the OpenEmbedded build system can now build +multiple kernel image types, this part of the kernel image base name as +been removed leaving only the following: +:: + + KERNEL_IMAGE_BASE_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}-${DATETIME}" + +If you have recipes or +classes that use ``KERNEL_IMAGE_BASE_NAME`` directly, you might need to +update the references to ensure they continue to work. + +.. _migration-2.2-bitbake-changes: + +BitBake Changes +--------------- + +The following changes took place for BitBake: + +- The "goggle" UI and standalone image-writer tool have been removed as + they both require GTK+ 2.0 and were not being maintained. + +- The Perforce fetcher now supports :term:`SRCREV` for + specifying the source revision to use, be it + ``${``\ :term:`AUTOREV`\ ``}``, changelist number, + p4date, or label, in preference to separate + :term:`SRC_URI` parameters to specify these. This + change is more in-line with how the other fetchers work for source + control systems. Recipes that fetch from Perforce will need to be + updated to use ``SRCREV`` in place of specifying the source revision + within ``SRC_URI``. + +- Some of BitBake's internal code structures for accessing the recipe + cache needed to be changed to support the new multi-configuration + functionality. These changes will affect external tools that use + BitBake's tinfoil module. For information on these changes, see the + changes made to the scripts supplied with OpenEmbedded-Core: + `1 <http://git.yoctoproject.org/cgit/cgit.cgi/poky/commit/?id=189371f8393971d00bca0fceffd67cc07784f6ee>`__ + and + `2 <http://git.yoctoproject.org/cgit/cgit.cgi/poky/commit/?id=4a5aa7ea4d07c2c90a1654b174873abb018acc67>`__. + +- The task management code has been rewritten to avoid using ID + indirection in order to improve performance. This change is unlikely + to cause any problems for most users. However, the setscene + verification function as pointed to by + ``BB_SETSCENE_VERIFY_FUNCTION`` needed to change signature. + Consequently, a new variable named ``BB_SETSCENE_VERIFY_FUNCTION2`` + has been added allowing multiple versions of BitBake to work with + suitably written metadata, which includes OpenEmbedded-Core and Poky. + Anyone with custom BitBake task scheduler code might also need to + update the code to handle the new structure. + +.. _migration-2.2-swabber-has-been-removed: + +Swabber has Been Removed +------------------------ + +Swabber, a tool that was intended to detect host contamination in the +build process, has been removed, as it has been unmaintained and unused +for some time and was never particularly effective. The OpenEmbedded +build system has since incorporated a number of mechanisms including +enhanced QA checks that mean that there is less of a need for such a +tool. + +.. _migration-2.2-removed-recipes: + +Removed Recipes +--------------- + +The following recipes have been removed: + +- ``augeas``: No longer needed and has been moved to ``meta-oe``. + +- ``directfb``: Unmaintained and has been moved to ``meta-oe``. + +- ``gcc``: Removed 4.9 version. Versions 5.4 and 6.2 are still present. + +- ``gnome-doc-utils``: No longer needed. + +- ``gtk-doc-stub``: Replaced by ``gtk-doc``. + +- ``gtk-engines``: No longer needed and has been moved to + ``meta-gnome``. + +- ``gtk-sato-engine``: Became obsolete. + +- ``libglade``: No longer needed and has been moved to ``meta-oe``. + +- ``libmad``: Unmaintained and functionally replaced by ``libmpg123``. + ``libmad`` has been moved to ``meta-oe``. + +- ``libowl``: Became obsolete. + +- ``libxsettings-client``: No longer needed. + +- ``oh-puzzles``: Functionally replaced by ``puzzles``. + +- ``oprofileui``: Became obsolete. OProfile has been largely supplanted + by perf. + +- ``packagegroup-core-directfb.bb``: Removed. + +- ``core-image-directfb.bb``: Removed. + +- ``pointercal``: No longer needed and has been moved to ``meta-oe``. + +- ``python-imaging``: No longer needed and moved to ``meta-python`` + +- ``python-pyrex``: No longer needed and moved to ``meta-python``. + +- ``sato-icon-theme``: Became obsolete. + +- ``swabber-native``: Swabber has been removed. See the `entry on + Swabber <#migration-2.2-swabber-has-been-removed>`__. + +- ``tslib``: No longer needed and has been moved to ``meta-oe``. + +- ``uclibc``: Removed in favor of musl. + +- ``xtscal``: No longer needed and moved to ``meta-oe`` + +.. _migration-2.2-removed-classes: + +Removed Classes +--------------- + +The following classes have been removed: + +- ``distutils-native-base``: No longer needed. + +- ``distutils3-native-base``: No longer needed. + +- ``sdl``: Only set :term:`DEPENDS` and + :term:`SECTION`, which are better set within the + recipe instead. + +- ``sip``: Mostly unused. + +- ``swabber``: See the `entry on + Swabber <#migration-2.2-swabber-has-been-removed>`__. + +.. _migration-2.2-minor-packaging-changes: + +Minor Packaging Changes +----------------------- + +The following minor packaging changes have occurred: + +- ``grub``: Split ``grub-editenv`` into its own package. + +- ``systemd``: Split container and vm related units into a new package, + systemd-container. + +- ``util-linux``: Moved ``prlimit`` to a separate + ``util-linux-prlimit`` package. + +.. _migration-2.2-miscellaneous-changes: + +Miscellaneous Changes +--------------------- + +The following miscellaneous changes have occurred: + +- ``package_regex.inc``: Removed because the definitions + ``package_regex.inc`` previously contained have been moved to their + respective recipes. + +- Both ``devtool add`` and ``recipetool create`` now use a fixed + :term:`SRCREV` by default when fetching from a Git + repository. You can override this in either case to use + ``${``\ :term:`AUTOREV`\ ``}`` instead by using the + ``-a`` or ``DASHDASHautorev`` command-line option + +- ``distcc``: GTK+ UI is now disabled by default. + +- ``packagegroup-core-tools-testapps``: Removed Piglit. + +- ``image.bbclass``: Renamed COMPRESS(ION) to CONVERSION. This change + means that ``COMPRESSIONTYPES``, ``COMPRESS_DEPENDS`` and + ``COMPRESS_CMD`` are deprecated in favor of ``CONVERSIONTYPES``, + ``CONVERSION_DEPENDS`` and ``CONVERSION_CMD``. The ``COMPRESS*`` + variable names will still work in the 2.2 release but metadata that + does not need to be backwards-compatible should be changed to use the + new names as the ``COMPRESS*`` ones will be removed in a future + release. + +- ``gtk-doc``: A full version of ``gtk-doc`` is now made available. + However, some old software might not be capable of using the current + version of ``gtk-doc`` to build documentation. You need to change + recipes that build such software so that they explicitly disable + building documentation with ``gtk-doc``. + + diff --git a/poky/documentation/ref-manual/migration-2.3.rst b/poky/documentation/ref-manual/migration-2.3.rst new file mode 100644 index 000000000..7f34f0cd7 --- /dev/null +++ b/poky/documentation/ref-manual/migration-2.3.rst @@ -0,0 +1,530 @@ +Moving to the Yocto Project 2.3 Release +======================================= + +This section provides migration information for moving to the Yocto +Project 2.3 Release from the prior release. + +.. _migration-2.3-recipe-specific-sysroots: + +Recipe-specific Sysroots +------------------------ + +The OpenEmbedded build system now uses one sysroot per recipe to resolve +long-standing issues with configuration script auto-detection of +undeclared dependencies. Consequently, you might find that some of your +previously written custom recipes are missing declared dependencies, +particularly those dependencies that are incidentally built earlier in a +typical build process and thus are already likely to be present in the +shared sysroot in previous releases. + +Consider the following: + +- *Declare Build-Time Dependencies:* Because of this new feature, you + must explicitly declare all build-time dependencies for your recipe. + If you do not declare these dependencies, they are not populated into + the sysroot for the recipe. + +- *Specify Pre-Installation and Post-Installation Native Tool + Dependencies:* You must specifically specify any special native tool + dependencies of ``pkg_preinst`` and ``pkg_postinst`` scripts by using + the :term:`PACKAGE_WRITE_DEPS` variable. + Specifying these dependencies ensures that these tools are available + if these scripts need to be run on the build host during the + :ref:`ref-tasks-rootfs` task. + + As an example, see the ``dbus`` recipe. You will see that this recipe + has a ``pkg_postinst`` that calls ``systemctl`` if "systemd" is in + :term:`DISTRO_FEATURES`. In the example, + ``systemd-systemctl-native`` is added to ``PACKAGE_WRITE_DEPS``, + which is also conditional on "systemd" being in ``DISTRO_FEATURES``. + +- Examine Recipes that Use ``SSTATEPOSTINSTFUNCS``: You need to + examine any recipe that uses ``SSTATEPOSTINSTFUNCS`` and determine + steps to take. + + Functions added to ``SSTATEPOSTINSTFUNCS`` are still called as they + were in previous Yocto Project releases. However, since a separate + sysroot is now being populated for every recipe and if existing + functions being called through ``SSTATEPOSTINSTFUNCS`` are doing + relocation, then you will need to change these to use a + post-installation script that is installed by a function added to + :term:`SYSROOT_PREPROCESS_FUNCS`. + + For an example, see the ``pixbufcache`` class in ``meta/classes/`` in + the :ref:`overview-manual/overview-manual-development-environment:yocto project source repositories`. + + .. note:: + + The + SSTATEPOSTINSTFUNCS + variable itself is now deprecated in favor of the + do_populate_sysroot[postfuncs] + task. Consequently, if you do still have any function or functions + that need to be called after the sysroot component is created for + a recipe, then you would be well advised to take steps to use a + post installation script as described previously. Taking these + steps prepares your code for when + SSTATEPOSTINSTFUNCS + is removed in a future Yocto Project release. + +- *Specify the Sysroot when Using Certain External Scripts:* Because + the shared sysroot is now gone, the scripts + ``oe-find-native-sysroot`` and ``oe-run-native`` have been changed + such that you need to specify which recipe's + :term:`STAGING_DIR_NATIVE` is used. + +.. note:: + + You can find more information on how recipe-specific sysroots work in + the " + staging.bbclass + " section. + +.. _migration-2.3-path-variable: + +``PATH`` Variable +----------------- + +Within the environment used to run build tasks, the environment variable +``PATH`` is now sanitized such that the normal native binary paths +(``/bin``, ``/sbin``, ``/usr/bin`` and so forth) are removed and a +directory containing symbolic links linking only to the binaries from +the host mentioned in the :term:`HOSTTOOLS` and +:term:`HOSTTOOLS_NONFATAL` variables is added +to ``PATH``. + +Consequently, any native binaries provided by the host that you need to +call needs to be in one of these two variables at the configuration +level. + +Alternatively, you can add a native recipe (i.e. ``-native``) that +provides the binary to the recipe's :term:`DEPENDS` +value. + +.. note:: + + PATH + is not sanitized in the same way within + devshell + . If it were, you would have difficulty running host tools for + development and debugging within the shell. + +.. _migration-2.3-scripts: + +Changes to Scripts +------------------ + +The following changes to scripts took place: + +- ``oe-find-native-sysroot``: The usage for the + ``oe-find-native-sysroot`` script has changed to the following: + :: + + $ . oe-find-native-sysroot recipe + + You must now supply a recipe for recipe + as part of the command. Prior to the Yocto Project &DISTRO; release, it + was not necessary to provide the script with the command. + +- ``oe-run-native``: The usage for the ``oe-run-native`` script has + changed to the following: + :: + + $ oe-run-native native_recipe tool + + You must + supply the name of the native recipe and the tool you want to run as + part of the command. Prior to the Yocto Project DISTRO release, it + was not necessary to provide the native recipe with the command. + +- ``cleanup-workdir``: The ``cleanup-workdir`` script has been + removed because the script was found to be deleting files it should + not have, which lead to broken build trees. Rather than trying to + delete portions of :term:`TMPDIR` and getting it wrong, + it is recommended that you delete ``TMPDIR`` and have it restored + from shared state (sstate) on subsequent builds. + +- ``wipe-sysroot``: The ``wipe-sysroot`` script has been removed as + it is no longer needed with recipe-specific sysroots. + +.. _migration-2.3-functions: + +Changes to Functions +-------------------- + +The previously deprecated ``bb.data.getVar()``, ``bb.data.setVar()``, +and related functions have been removed in favor of ``d.getVar()``, +``d.setVar()``, and so forth. + +You need to fix any references to these old functions. + +.. _migration-2.3-bitbake-changes: + +BitBake Changes +--------------- + +The following changes took place for BitBake: + +- *BitBake's Graphical Dependency Explorer UI Replaced:* BitBake's + graphical dependency explorer UI ``depexp`` was replaced by + ``taskexp`` ("Task Explorer"), which provides a graphical way of + exploring the ``task-depends.dot`` file. The data presented by Task + Explorer is much more accurate than the data that was presented by + ``depexp``. Being able to visualize the data is an often requested + feature as standard ``*.dot`` file viewers cannot usual cope with the + size of the ``task-depends.dot`` file. + +- *BitBake "-g" Output Changes:* The ``package-depends.dot`` and + ``pn-depends.dot`` files as previously generated using the + ``bitbake -g`` command have been removed. A ``recipe-depends.dot`` + file is now generated as a collapsed version of ``task-depends.dot`` + instead. + + The reason for this change is because ``package-depends.dot`` and + ``pn-depends.dot`` largely date back to a time before task-based + execution and do not take into account task-level dependencies + between recipes, which could be misleading. + +- *Mirror Variable Splitting Changes:* Mirror variables including + :term:`MIRRORS`, :term:`PREMIRRORS`, + and :term:`SSTATE_MIRRORS` can now separate + values entirely with spaces. Consequently, you no longer need "\\n". + BitBake looks for pairs of values, which simplifies usage. There + should be no change required to existing mirror variable values + themselves. + +- *The Subversion (SVN) Fetcher Uses an "ssh" Parameter and Not an + "rsh" Parameter:* The SVN fetcher now takes an "ssh" parameter + instead of an "rsh" parameter. This new optional parameter is used + when the "protocol" parameter is set to "svn+ssh". You can only use + the new parameter to specify the ``ssh`` program used by SVN. The SVN + fetcher passes the new parameter through the ``SVN_SSH`` environment + variable during the :ref:`ref-tasks-fetch` task. + + See the ":ref:`bitbake:svn-fetcher`" + section in the BitBake + User Manual for additional information. + +- ``BB_SETSCENE_VERIFY_FUNCTION`` and ``BB_SETSCENE_VERIFY_FUNCTION2`` + Removed: Because the mechanism they were part of is no longer + necessary with recipe-specific sysroots, the + ``BB_SETSCENE_VERIFY_FUNCTION`` and ``BB_SETSCENE_VERIFY_FUNCTION2`` + variables have been removed. + +.. _migration-2.3-absolute-symlinks: + +Absolute Symbolic Links +----------------------- + +Absolute symbolic links (symlinks) within staged files are no longer +permitted and now trigger an error. Any explicit creation of symlinks +can use the ``lnr`` script, which is a replacement for ``ln -r``. + +If the build scripts in the software that the recipe is building are +creating a number of absolute symlinks that need to be corrected, you +can inherit ``relative_symlinks`` within the recipe to turn those +absolute symlinks into relative symlinks. + +.. _migration-2.3-gplv2-and-gplv3-moves: + +GPLv2 Versions of GPLv3 Recipes Moved +------------------------------------- + +Older GPLv2 versions of GPLv3 recipes have moved to a separate +``meta-gplv2`` layer. + +If you use :term:`INCOMPATIBLE_LICENSE` to +exclude GPLv3 or set :term:`PREFERRED_VERSION` +to substitute a GPLv2 version of a GPLv3 recipe, then you must add the +``meta-gplv2`` layer to your configuration. + +.. note:: + + You can find + meta-gplv2 + layer in the OpenEmbedded layer index at + . + +These relocated GPLv2 recipes do not receive the same level of +maintenance as other core recipes. The recipes do not get security fixes +and upstream no longer maintains them. In fact, the upstream community +is actively hostile towards people that use the old versions of the +recipes. Moving these recipes into a separate layer both makes the +different needs of the recipes clearer and clearly identifies the number +of these recipes. + +.. note:: + + The long-term solution might be to move to BSD-licensed replacements + of the GPLv3 components for those that need to exclude GPLv3-licensed + components from the target system. This solution will be investigated + for future Yocto Project releases. + +.. _migration-2.3-package-management-changes: + +Package Management Changes +-------------------------- + +The following package management changes took place: + +- Smart package manager is replaced by DNF package manager. Smart has + become unmaintained upstream, is not ported to Python 3.x. + Consequently, Smart needed to be replaced. DNF is the only feasible + candidate. + + The change in functionality is that the on-target runtime package + management from remote package feeds is now done with a different + tool that has a different set of command-line options. If you have + scripts that call the tool directly, or use its API, they need to be + fixed. + + For more information, see the `DNF + Documentation <http://dnf.readthedocs.io/en/latest/>`__. + +- Rpm 5.x is replaced with Rpm 4.x. This is done for two major reasons: + + - DNF is API-incompatible with Rpm 5.x and porting it and + maintaining the port is non-trivial. + + - Rpm 5.x itself has limited maintenance upstream, and the Yocto + Project is one of the very few remaining users. + +- Berkeley DB 6.x is removed and Berkeley DB 5.x becomes the default: + + - Version 6.x of Berkeley DB has largely been rejected by the open + source community due to its AGPLv3 license. As a result, most + mainstream open source projects that require DB are still + developed and tested with DB 5.x. + + - In OE-core, the only thing that was requiring DB 6.x was Rpm 5.x. + Thus, no reason exists to continue carrying DB 6.x in OE-core. + +- ``createrepo`` is replaced with ``createrepo_c``. + + ``createrepo_c`` is the current incarnation of the tool that + generates remote repository metadata. It is written in C as compared + to ``createrepo``, which is written in Python. ``createrepo_c`` is + faster and is maintained. + +- Architecture-independent RPM packages are "noarch" instead of "all". + + This change was made because too many places in DNF/RPM4 stack + already make that assumption. Only the filenames and the architecture + tag has changed. Nothing else has changed in OE-core system, + particularly in the :ref:`allarch.bbclass <ref-classes-allarch>` + class. + +- Signing of remote package feeds using ``PACKAGE_FEED_SIGN`` is not + currently supported. This issue will be fully addressed in a future + Yocto Project release. See `defect + 11209 <https://bugzilla.yoctoproject.org/show_bug.cgi?id=11209>`__ + for more information on a solution to package feed signing with RPM + in the Yocto Project 2.3 release. + +- OPKG now uses the libsolv backend for resolving package dependencies + by default. This is vastly superior to OPKG's internal ad-hoc solver + that was previously used. This change does have a small impact on + disk (around 500 KB) and memory footprint. + + .. note:: + + For further details on this change, see the + commit message + . + +.. _migration-2.3-removed-recipes: + +Removed Recipes +--------------- + +The following recipes have been removed: + +- ``linux-yocto 4.8``: Version 4.8 has been removed. Versions 4.1 + (LTSI), 4.4 (LTS), 4.9 (LTS/LTSI) and 4.10 are now present. + +- ``python-smartpm``: Functionally replaced by ``dnf``. + +- ``createrepo``: Replaced by the ``createrepo-c`` recipe. + +- ``rpmresolve``: No longer needed with the move to RPM 4 as RPM + itself is used instead. + +- ``gstreamer``: Removed the GStreamer Git version recipes as they + have been stale. ``1.10.``\ x recipes are still present. + +- ``alsa-conf-base``: Merged into ``alsa-conf`` since ``libasound`` + depended on both. Essentially, no way existed to install only one of + these. + +- ``tremor``: Moved to ``meta-multimedia``. Fixed-integer Vorbis + decoding is not needed by current hardware. Thus, GStreamer's ivorbis + plugin has been disabled by default eliminating the need for the + ``tremor`` recipe in :term:`OpenEmbedded-Core (OE-Core)`. + +- ``gummiboot``: Replaced by ``systemd-boot``. + +.. _migration-2.3-wic-changes: + +Wic Changes +----------- + +The following changes have been made to Wic: + +.. note:: + + For more information on Wic, see the " + Creating Partitioned Images Using Wic + " section in the Yocto Project Development Tasks Manual. + +- *Default Output Directory Changed:* Wic's default output directory is + now the current directory by default instead of the unusual + ``/var/tmp/wic``. + + The "-o" and "--outdir" options remain unchanged and are used to + specify your preferred output directory if you do not want to use the + default directory. + +- *fsimage Plug-in Removed:* The Wic fsimage plugin has been removed as + it duplicates functionality of the rawcopy plugin. + +.. _migration-2.3-qa-changes: + +QA Changes +---------- + +The following QA checks have changed: + +- ``unsafe-references-in-binaries``: The + ``unsafe-references-in-binaries`` QA check, which was disabled by + default, has now been removed. This check was intended to detect + binaries in ``/bin`` that link to libraries in ``/usr/lib`` and have + the case where the user has ``/usr`` on a separate filesystem to + ``/``. + + The removed QA check was buggy. Additionally, ``/usr`` residing on a + separate partition from ``/`` is now a rare configuration. + Consequently, ``unsafe-references-in-binaries`` was removed. + +- ``file-rdeps``: The ``file-rdeps`` QA check is now an error by + default instead of a warning. Because it is an error instead of a + warning, you need to address missing runtime dependencies. + + For additional information, see the + :ref:`insane <ref-classes-insane>` class and the "`Errors and + Warnings <#qa-errors-and-warnings>`__" section. + +.. _migration-2.3-miscellaneous-changes: + +Miscellaneous Changes +--------------------- + +The following miscellaneous changes have occurred: + +- In this release, a number of recipes have been changed to ignore the + ``largefile`` :term:`DISTRO_FEATURES` item, + enabling large file support unconditionally. This feature has always + been enabled by default. Disabling the feature has not been widely + tested. + + .. note:: + + Future releases of the Yocto Project will remove entirely the + ability to disable the + largefile + feature, which would make it unconditionally enabled everywhere. + +- If the :term:`DISTRO_VERSION` value contains + the value of the :term:`DATE` variable, which is the + default between Poky releases, the ``DATE`` value is explicitly + excluded from ``/etc/issue`` and ``/etc/issue.net``, which is + displayed at the login prompt, in order to avoid conflicts with + Multilib enabled. Regardless, the ``DATE`` value is inaccurate if the + ``base-files`` recipe is restored from shared state (sstate) rather + than rebuilt. + + If you need the build date recorded in ``/etc/issue*`` or anywhere + else in your image, a better method is to define a post-processing + function to do it and have the function called from + :term:`ROOTFS_POSTPROCESS_COMMAND`. + Doing so ensures the value is always up-to-date with the created + image. + +- Dropbear's ``init`` script now disables DSA host keys by default. + This change is in line with the systemd service file, which supports + RSA keys only, and with recent versions of OpenSSH, which deprecates + DSA host keys. + +- The :ref:`buildhistory <ref-classes-buildhistory>` class now + correctly uses tabs as separators between all columns in + ``installed-package-sizes.txt`` in order to aid import into other + tools. + +- The ``USE_LDCONFIG`` variable has been replaced with the "ldconfig" + ``DISTRO_FEATURES`` feature. Distributions that previously set: + :: + + USE_LDCONFIG = "0" + + should now instead use the following: + + :: + + DISTRO_FEATURES_BACKFILL_CONSIDERED_append = " ldconfig" + +- The default value of + :term:`COPYLEFT_LICENSE_INCLUDE` now + includes all versions of AGPL licenses in addition to GPL and LGPL. + + .. note:: + + The default list is not intended to be guaranteed as a complete + safe list. You should seek legal advice based on what you are + distributing if you are unsure. + +- Kernel module packages are now suffixed with the kernel version in + order to allow module packages from multiple kernel versions to + co-exist on a target system. If you wish to return to the previous + naming scheme that does not include the version suffix, use the + following: + :: + + KERNEL_MODULE_PACKAGE_SUFFIX to "" + +- Removal of ``libtool`` ``*.la`` files is now enabled by default. The + ``*.la`` files are not actually needed on Linux and relocating them + is an unnecessary burden. + + If you need to preserve these ``.la`` files (e.g. in a custom + distribution), you must change + :term:`INHERIT_DISTRO` such that + "remove-libtool" is not included in the value. + +- Extensible SDKs built for GCC 5+ now refuse to install on a + distribution where the host GCC version is 4.8 or 4.9. This change + resulted from the fact that the installation is known to fail due to + the way the ``uninative`` shared state (sstate) package is built. See + the :ref:`uninative <ref-classes-uninative>` class for additional + information. + +- All native and nativesdk recipes now use a separate + ``DISTRO_FEATURES`` value instead of sharing the value used by + recipes for the target, in order to avoid unnecessary rebuilds. + + The ``DISTRO_FEATURES`` for ``native`` recipes is + :term:`DISTRO_FEATURES_NATIVE` added to + an intersection of ``DISTRO_FEATURES`` and + :term:`DISTRO_FEATURES_FILTER_NATIVE`. + + For nativesdk recipes, the corresponding variables are + :term:`DISTRO_FEATURES_NATIVESDK` + and + :term:`DISTRO_FEATURES_FILTER_NATIVESDK`. + +- The ``FILESDIR`` variable, which was previously deprecated and rarely + used, has now been removed. You should change any recipes that set + ``FILESDIR`` to set :term:`FILESPATH` instead. + +- The ``MULTIMACH_HOST_SYS`` variable has been removed as it is no + longer needed with recipe-specific sysroots. + + diff --git a/poky/documentation/ref-manual/migration-2.4.rst b/poky/documentation/ref-manual/migration-2.4.rst new file mode 100644 index 000000000..260b3204b --- /dev/null +++ b/poky/documentation/ref-manual/migration-2.4.rst @@ -0,0 +1,327 @@ +Moving to the Yocto Project 2.4 Release +======================================= + +This section provides migration information for moving to the Yocto +Project 2.4 Release from the prior release. + +.. _migration-2.4-memory-resident-mode: + +Memory Resident Mode +-------------------- + +A persistent mode is now available in BitBake's default operation, +replacing its previous "memory resident mode" (i.e. +``oe-init-build-env-memres``). Now you only need to set +:term:`BB_SERVER_TIMEOUT` to a timeout (in +seconds) and BitBake's server stays resident for that amount of time +between invocations. The ``oe-init-build-env-memres`` script has been +removed since a separate environment setup script is no longer needed. + +.. _migration-2.4-packaging-changes: + +Packaging Changes +----------------- + +This section provides information about packaging changes that have +occurred: + +- ``python3`` Changes: + + - The main "python3" package now brings in all of the standard + Python 3 distribution rather than a subset. This behavior matches + what is expected based on traditional Linux distributions. If you + wish to install a subset of Python 3, specify ``python-core`` plus + one or more of the individual packages that are still produced. + + - ``python3``: The ``bz2.py``, ``lzma.py``, and + ``_compression.py`` scripts have been moved from the + ``python3-misc`` package to the ``python3-compression`` package. + +- ``binutils``: The ``libbfd`` library is now packaged in a separate + "libbfd" package. This packaging saves space when certain tools (e.g. + ``perf``) are installed. In such cases, the tools only need + ``libbfd`` rather than all the packages in ``binutils``. + +- ``util-linux`` Changes: + + - The ``su`` program is now packaged in a separate "util-linux-su" + package, which is only built when "pam" is listed in the + :term:`DISTRO_FEATURES` variable. + ``util-linux`` should not be installed unless it is needed because + ``su`` is normally provided through the shadow file format. The + main ``util-linux`` package has runtime dependencies (i.e. + :term:`RDEPENDS`) on the ``util-linux-su`` package + when "pam" is in ``DISTRO_FEATURES``. + + - The ``switch_root`` program is now packaged in a separate + "util-linux-switch-root" package for small initramfs images that + do not need the whole ``util-linux`` package or the busybox + binary, which are both much larger than ``switch_root``. The main + ``util-linux`` package has a recommended runtime dependency (i.e. + :term:`RRECOMMENDS`) on the + ``util-linux-switch-root`` package. + + - The ``ionice`` program is now packaged in a separate + "util-linux-ionice" package. The main ``util-linux`` package has a + recommended runtime dependency (i.e. ``RRECOMMENDS``) on the + ``util-linux-ionice`` package. + +- ``initscripts``: The ``sushell`` program is now packaged in a + separate "initscripts-sushell" package. This packaging change allows + systems to pull ``sushell`` in when ``selinux`` is enabled. The + change also eliminates needing to pull in the entire ``initscripts`` + package. The main ``initscripts`` package has a runtime dependency + (i.e. ``RDEPENDS``) on the ``sushell`` package when "selinux" is in + ``DISTRO_FEATURES``. + +- ``glib-2.0``: The ``glib-2.0`` package now has a recommended + runtime dependency (i.e. ``RRECOMMENDS``) on the ``shared-mime-info`` + package, since large portions of GIO are not useful without the MIME + database. You can remove the dependency by using the + :term:`BAD_RECOMMENDATIONS` variable if + ``shared-mime-info`` is too large and is not required. + +- *Go Standard Runtime:* The Go standard runtime has been split out + from the main ``go`` recipe into a separate ``go-runtime`` recipe. + +.. _migration-2.4-removed-recipes: + +Removed Recipes +--------------- + +The following recipes have been removed: + +- ``acpitests``: This recipe is not maintained. + +- ``autogen-native``: No longer required by Grub, oe-core, or + meta-oe. + +- ``bdwgc``: Nothing in OpenEmbedded-Core requires this recipe. It + has moved to meta-oe. + +- ``byacc``: This recipe was only needed by rpm 5.x and has moved to + meta-oe. + +- ``gcc (5.4)``: The 5.4 series dropped the recipe in favor of 6.3 / + 7.2. + +- ``gnome-common``: Deprecated upstream and no longer needed. + +- ``go-bootstrap-native``: Go 1.9 does its own bootstrapping so this + recipe has been removed. + +- ``guile``: This recipe was only needed by ``autogen-native`` and + ``remake``. The recipe is no longer needed by either of these + programs. + +- ``libclass-isa-perl``: This recipe was previously needed for LSB 4, + no longer needed. + +- ``libdumpvalue-perl``: This recipe was previously needed for LSB 4, + no longer needed. + +- ``libenv-perl``: This recipe was previously needed for LSB 4, no + longer needed. + +- ``libfile-checktree-perl``: This recipe was previously needed for + LSB 4, no longer needed. + +- ``libi18n-collate-perl``: This recipe was previously needed for LSB + 4, no longer needed. + +- ``libiconv``: This recipe was only needed for ``uclibc``, which was + removed in the previous release. ``glibc`` and ``musl`` have their + own implementations. ``meta-mingw`` still needs ``libiconv``, so it + has been moved to ``meta-mingw``. + +- ``libpng12``: This recipe was previously needed for LSB. The + current ``libpng`` is 1.6.x. + +- ``libpod-plainer-perl``: This recipe was previously needed for LSB + 4, no longer needed. + +- ``linux-yocto (4.1)``: This recipe was removed in favor of 4.4, + 4.9, 4.10 and 4.12. + +- ``mailx``: This recipe was previously only needed for LSB + compatibility, and upstream is defunct. + +- ``mesa (git version only)``: The git version recipe was stale with + respect to the release version. + +- ``ofono (git version only)``: The git version recipe was stale with + respect to the release version. + +- ``portmap``: This recipe is obsolete and is superseded by + ``rpcbind``. + +- ``python3-pygpgme``: This recipe is old and unmaintained. It was + previously required by ``dnf``, which has switched to official + ``gpgme`` Python bindings. + +- ``python-async``: This recipe has been removed in favor of the + Python 3 version. + +- ``python-gitdb``: This recipe has been removed in favor of the + Python 3 version. + +- ``python-git``: This recipe was removed in favor of the Python 3 + version. + +- ``python-mako``: This recipe was removed in favor of the Python 3 + version. + +- ``python-pexpect``: This recipe was removed in favor of the Python + 3 version. + +- ``python-ptyprocess``: This recipe was removed in favor of Python + the 3 version. + +- ``python-pycurl``: Nothing is using this recipe in + OpenEmbedded-Core (i.e. ``meta-oe``). + +- ``python-six``: This recipe was removed in favor of the Python 3 + version. + +- ``python-smmap``: This recipe was removed in favor of the Python 3 + version. + +- ``remake``: Using ``remake`` as the provider of ``virtual/make`` is + broken. Consequently, this recipe is not needed in OpenEmbedded-Core. + +.. _migration-2.4-kernel-device-tree-move: + +Kernel Device Tree Move +----------------------- + +Kernel Device Tree support is now easier to enable in a kernel recipe. +The Device Tree code has moved to a +:ref:`kernel-devicetree <ref-classes-kernel-devicetree>` class. +Functionality is automatically enabled for any recipe that inherits the +:ref:`kernel <ref-classes-kernel>` class and sets the +:term:`KERNEL_DEVICETREE` variable. The +previous mechanism for doing this, +``meta/recipes-kernel/linux/linux-dtb.inc``, is still available to avoid +breakage, but triggers a deprecation warning. Future releases of the +Yocto Project will remove ``meta/recipes-kernel/linux/linux-dtb.inc``. +It is advisable to remove any ``require`` statements that request +``meta/recipes-kernel/linux/linux-dtb.inc`` from any custom kernel +recipes you might have. This will avoid breakage in post 2.4 releases. + +.. _migration-2.4-package-qa-changes: + +Package QA Changes +------------------ + +The following package QA changes took place: + +- The "unsafe-references-in-scripts" QA check has been removed. + +- If you refer to ``${COREBASE}/LICENSE`` within + :term:`LIC_FILES_CHKSUM` you receive a + warning because this file is a description of the license for + OE-Core. Use ``${COMMON_LICENSE_DIR}/MIT`` if your recipe is + MIT-licensed and you cannot use the preferred method of referring to + a file within the source tree. + +.. _migration-2.4-readme-changes: + +``README`` File Changes +----------------------- + +The following are changes to ``README`` files: + +- The main Poky ``README`` file has been moved to the ``meta-poky`` + layer and has been renamed ``README.poky``. A symlink has been + created so that references to the old location work. + +- The ``README.hardware`` file has been moved to ``meta-yocto-bsp``. A + symlink has been created so that references to the old location work. + +- A ``README.qemu`` file has been created with coverage of the + ``qemu*`` machines. + +.. _migration-2.4-miscellaneous-changes: + +Miscellaneous Changes +--------------------- + +The following are additional changes: + +- The ``ROOTFS_PKGMANAGE_BOOTSTRAP`` variable and any references to it + have been removed. You should remove this variable from any custom + recipes. + +- The ``meta-yocto`` directory has been removed. + + .. note:: + + In the Yocto Project 2.1 release + meta-yocto + was renamed to + meta-poky + and the + meta-yocto + subdirectory remained to avoid breaking existing configurations. + +- The ``maintainers.inc`` file, which tracks maintainers by listing a + primary person responsible for each recipe in OE-Core, has been moved + from ``meta-poky`` to OE-Core (i.e. from + ``meta-poky/conf/distro/include`` to ``meta/conf/distro/include``). + +- The :ref:`buildhistory <ref-classes-buildhistory>` class now makes + a single commit per build rather than one commit per subdirectory in + the repository. This behavior assumes the commits are enabled with + :term:`BUILDHISTORY_COMMIT` = "1", which + is typical. Previously, the ``buildhistory`` class made one commit + per subdirectory in the repository in order to make it easier to see + the changes for a particular subdirectory. To view a particular + change, specify that subdirectory as the last parameter on the + ``git show`` or ``git diff`` commands. + +- The ``x86-base.inc`` file, which is included by all x86-based machine + configurations, now sets :term:`IMAGE_FSTYPES` + using ``?=`` to "live" rather than appending with ``+=``. This change + makes the default easier to override. + +- BitBake fires multiple "BuildStarted" events when multiconfig is + enabled (one per configuration). For more information, see the + ":ref:`Events <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:events>`" section in the BitBake User + Manual. + +- By default, the ``security_flags.inc`` file sets a + :term:`GCCPIE` variable with an option to enable + Position Independent Executables (PIE) within ``gcc``. Enabling PIE + in the GNU C Compiler (GCC), makes Return Oriented Programming (ROP) + attacks much more difficult to execute. + +- OE-Core now provides a ``bitbake-layers`` plugin that implements a + "create-layer" subcommand. The implementation of this subcommand has + resulted in the ``yocto-layer`` script being deprecated and will + likely be removed in the next Yocto Project release. + +- The ``vmdk``, ``vdi``, and ``qcow2`` image file types are now used in + conjunction with the "wic" image type through ``CONVERSION_CMD``. + Consequently, the equivalent image types are now ``wic.vmdk``, + ``wic.vdi``, and ``wic.qcow2``, respectively. + +- ``do_image_<type>[depends]`` has replaced ``IMAGE_DEPENDS_<type>``. + If you have your own classes that implement custom image types, then + you need to update them. + +- OpenSSL 1.1 has been introduced. However, the default is still 1.0.x + through the :term:`PREFERRED_VERSION` + variable. This preference is set is due to the remaining + compatibility issues with other software. The + :term:`PROVIDES` variable in the openssl 1.0 recipe + now includes "openssl10" as a marker that can be used in + :term:`DEPENDS` within recipes that build software + that still depend on OpenSSL 1.0. + +- To ensure consistent behavior, BitBake's "-r" and "-R" options (i.e. + prefile and postfile), which are used to read or post-read additional + configuration files from the command line, now only affect the + current BitBake command. Before these BitBake changes, these options + would "stick" for future executions. + + diff --git a/poky/documentation/ref-manual/migration-2.5.rst b/poky/documentation/ref-manual/migration-2.5.rst new file mode 100644 index 000000000..a2adc1775 --- /dev/null +++ b/poky/documentation/ref-manual/migration-2.5.rst @@ -0,0 +1,310 @@ +Moving to the Yocto Project 2.5 Release +======================================= + +This section provides migration information for moving to the Yocto +Project 2.5 Release from the prior release. + +.. _migration-2.5-packaging-changes: + +Packaging Changes +----------------- + +This section provides information about packaging changes that have +occurred: + +- ``bind-libs``: The libraries packaged by the bind recipe are in a + separate ``bind-libs`` package. + +- ``libfm-gtk``: The ``libfm`` GTK+ bindings are split into a + separate ``libfm-gtk`` package. + +- ``flex-libfl``: The flex recipe splits out libfl into a separate + ``flex-libfl`` package to avoid too many dependencies being pulled in + where only the library is needed. + +- ``grub-efi``: The ``grub-efi`` configuration is split into a + separate ``grub-bootconf`` recipe. However, the dependency + relationship from ``grub-efi`` is through a virtual/grub-bootconf + provider making it possible to have your own recipe provide the + dependency. Alternatively, you can use a BitBake append file to bring + the configuration back into the ``grub-efi`` recipe. + +- *armv7a Legacy Package Feed Support:* Legacy support is removed for + transitioning from ``armv7a`` to ``armv7a-vfp-neon`` in package + feeds, which was previously enabled by setting + ``PKGARCHCOMPAT_ARMV7A``. This transition occurred in 2011 and active + package feeds should by now be updated to the new naming. + +.. _migration-2.5-removed-recipes: + +Removed Recipes +--------------- + +The following recipes have been removed: + +- ``gcc``: The version 6.4 recipes are replaced by 7.x. + +- ``gst-player``: Renamed to ``gst-examples`` as per upstream. + +- ``hostap-utils``: This software package is obsolete. + +- ``latencytop``: This recipe is no longer maintained upstream. The + last release was in 2009. + +- ``libpfm4``: The only file that requires this recipe is + ``oprofile``, which has been removed. + +- ``linux-yocto``: The version 4.4, 4.9, and 4.10 recipes have been + removed. Versions 4.12, 4.14, and 4.15 remain. + +- ``man``: This recipe has been replaced by modern ``man-db`` + +- ``mkelfimage``: This tool has been removed in the upstream coreboot + project, and is no longer needed with the removal of the ELF image + type. + +- ``nativesdk-postinst-intercept``: This recipe is not maintained. + +- ``neon``: This software package is no longer maintained upstream + and is no longer needed by anything in OpenEmbedded-Core. + +- ``oprofile``: The functionality of this recipe is replaced by + ``perf`` and keeping compatibility on an ongoing basis with ``musl`` + is difficult. + +- ``pax``: This software package is obsolete. + +- ``stat``: This software package is not maintained upstream. + ``coreutils`` provides a modern stat binary. + +- ``zisofs-tools-native``: This recipe is no longer needed because + the compressed ISO image feature has been removed. + +.. _migration-2.5-scripts-and-tools-changes: + +Scripts and Tools Changes +------------------------- + +The following are changes to scripts and tools: + +- ``yocto-bsp``, ``yocto-kernel``, and ``yocto-layer``: The + ``yocto-bsp``, ``yocto-kernel``, and ``yocto-layer`` scripts + previously shipped with poky but not in OpenEmbedded-Core have been + removed. These scripts are not maintained and are outdated. In many + cases, they are also limited in scope. The + ``bitbake-layers create-layer`` command is a direct replacement for + ``yocto-layer``. See the documentation to create a BSP or kernel + recipe in the ":ref:`bsp-guide/bsp:bsp kernel recipe example`" section. + +- ``devtool finish``: ``devtool finish`` now exits with an error if + there are uncommitted changes or a rebase/am in progress in the + recipe's source repository. If this error occurs, there might be + uncommitted changes that will not be included in updates to the + patches applied by the recipe. A -f/--force option is provided for + situations that the uncommitted changes are inconsequential and you + want to proceed regardless. + +- ``scripts/oe-setup-rpmrepo`` script: The functionality of + ``scripts/oe-setup-rpmrepo`` is replaced by + ``bitbake package-index``. + +- ``scripts/test-dependencies.sh`` script: The script is largely made + obsolete by the recipe-specific sysroots functionality introduced in + the previous release. + +.. _migration-2.5-bitbake-changes: + +BitBake Changes +--------------- + +The following are BitBake changes: + +- The ``--runall`` option has changed. There are two different + behaviors people might want: + + - *Behavior A:* For a given target (or set of targets) look through + the task graph and run task X only if it is present and will be + built. + + - *Behavior B:* For a given target (or set of targets) look through + the task graph and run task X if any recipe in the taskgraph has + such a target, even if it is not in the original task graph. + + The ``--runall`` option now performs "Behavior B". Previously + ``--runall`` behaved like "Behavior A". A ``--runonly`` option has + been added to retain the ability to perform "Behavior A". + +- Several explicit "run this task for all recipes in the dependency + tree" tasks have been removed (e.g. ``fetchall``, ``checkuriall``, + and the ``*all`` tasks provided by the ``distrodata`` and + ``archiver`` classes). There is a BitBake option to complete this for + any arbitrary task. For example: + :: + + bitbake <target> -c fetchall + + should now be replaced with: + :: + + bitbake <target> --runall=fetch + +.. _migration-2.5-python-and-python3-changes: + +Python and Python 3 Changes +--------------------------- + +The following are auto-packaging changes to Python and Python 3: + +The script-managed ``python-*-manifest.inc`` files that were previously +used to generate Python and Python 3 packages have been replaced with a +JSON-based file that is easier to read and maintain. A new task is +available for maintainers of the Python recipes to update the JSON file +when upgrading to new Python versions. You can now edit the file +directly instead of having to edit a script and run it to update the +file. + +One particular change to note is that the Python recipes no longer have +build-time provides for their packages. This assumes ``python-foo`` is +one of the packages provided by the Python recipe. You can no longer run +``bitbake python-foo`` or have a +:term:`DEPENDS` on ``python-foo``, +but doing either of the following causes the package to work as +expected: :: + + IMAGE_INSTALL_append = " python-foo" + +or :: + + RDEPENDS_${PN} = "python-foo" + +The earlier build-time provides behavior was a quirk of the +way the Python manifest file was created. For more information on this +change please see `this +commit <http://git.yoctoproject.org/cgit/cgit.cgi/poky/commit/?id=8d94b9db221d1def42f091b991903faa2d1651ce>`__. + +.. _migration-2.5-miscellaneous-changes: + +Miscellaneous Changes +--------------------- + +The following are additional changes: + +- The ``kernel`` class supports building packages for multiple kernels. + If your kernel recipe or ``.bbappend`` file mentions packaging at + all, you should replace references to the kernel in package names + with ``${KERNEL_PACKAGE_NAME}``. For example, if you disable + automatic installation of the kernel image using + ``RDEPENDS_kernel-base = ""`` you can avoid warnings using + ``RDEPENDS_${KERNEL_PACKAGE_NAME}-base = ""`` instead. + +- The ``buildhistory`` class commits changes to the repository by + default so you no longer need to set ``BUILDHISTORY_COMMIT = "1"``. + If you want to disable commits you need to set + ``BUILDHISTORY_COMMIT = "0"`` in your configuration. + +- The ``beaglebone`` reference machine has been renamed to + ``beaglebone-yocto``. The ``beaglebone-yocto`` BSP is a reference + implementation using only mainline components available in + OpenEmbedded-Core and ``meta-yocto-bsp``, whereas Texas Instruments + maintains a full-featured BSP in the ``meta-ti`` layer. This rename + avoids the previous name clash that existed between the two BSPs. + +- The ``update-alternatives`` class no longer works with SysV ``init`` + scripts because this usage has been problematic. Also, the + ``sysklogd`` recipe no longer uses ``update-alternatives`` because it + is incompatible with other implementations. + +- By default, the :ref:`cmake <ref-classes-cmake>` class uses + ``ninja`` instead of ``make`` for building. This improves build + performance. If a recipe is broken with ``ninja``, then the recipe + can set ``OECMAKE_GENERATOR = "Unix Makefiles"`` to change back to + ``make``. + +- The previously deprecated ``base_*`` functions have been removed in + favor of their replacements in ``meta/lib/oe`` and + ``bitbake/lib/bb``. These are typically used from recipes and + classes. Any references to the old functions must be updated. The + following table shows the removed functions and their replacements: + + +------------------------------+----------------------------------------------------------+ + | *Removed* | *Replacement* | + +==============================+==========================================================+ + | base_path_join() | oe.path.join() | + +------------------------------+----------------------------------------------------------+ + | base_path_relative() | oe.path.relative() | + +------------------------------+----------------------------------------------------------+ + | base_path_out() | oe.path.format_display() | + +------------------------------+----------------------------------------------------------+ + | base_read_file() | oe.utils.read_file() | + +------------------------------+----------------------------------------------------------+ + | base_ifelse() | oe.utils.ifelse() | + +------------------------------+----------------------------------------------------------+ + | base_conditional() | oe.utils.conditional() | + +------------------------------+----------------------------------------------------------+ + | base_less_or_equal() | oe.utils.less_or_equal() | + +------------------------------+----------------------------------------------------------+ + | base_version_less_or_equal() | oe.utils.version_less_or_equal() | + +------------------------------+----------------------------------------------------------+ + | base_contains() | bb.utils.contains() | + +------------------------------+----------------------------------------------------------+ + | base_both_contain() | oe.utils.both_contain() | + +------------------------------+----------------------------------------------------------+ + | base_prune_suffix() | oe.utils.prune_suffix() | + +------------------------------+----------------------------------------------------------+ + | oe_filter() | oe.utils.str_filter() | + +------------------------------+----------------------------------------------------------+ + | oe_filter_out() | oe.utils.str_filter_out() (or use the \_remove operator) | + +------------------------------+----------------------------------------------------------+ + +- Using ``exit 1`` to explicitly defer a postinstall script until first + boot is now deprecated since it is not an obvious mechanism and can + mask actual errors. If you want to explicitly defer a postinstall to + first boot on the target rather than at ``rootfs`` creation time, use + ``pkg_postinst_ontarget()`` or call + ``postinst_intercept delay_to_first_boot`` from ``pkg_postinst()``. + Any failure of a ``pkg_postinst()`` script (including ``exit 1``) + will trigger a warning during ``do_rootfs``. + + For more information, see the + ":ref:`dev-manual/dev-manual-common-tasks:post-installation scripts`" + section in the Yocto Project Development Tasks Manual. + +- The ``elf`` image type has been removed. This image type was removed + because the ``mkelfimage`` tool that was required to create it is no + longer provided by coreboot upstream and required updating every time + ``binutils`` updated. + +- Support for .iso image compression (previously enabled through + ``COMPRESSISO = "1"``) has been removed. The userspace tools + (``zisofs-tools``) are unmaintained and ``squashfs`` provides better + performance and compression. In order to build a live image with + squashfs+lz4 compression enabled you should now set + ``LIVE_ROOTFS_TYPE = "squashfs-lz4"`` and ensure that ``live`` is in + ``IMAGE_FSTYPES``. + +- Recipes with an unconditional dependency on ``libpam`` are only + buildable with ``pam`` in ``DISTRO_FEATURES``. If the dependency is + truly optional then it is recommended that the dependency be + conditional upon ``pam`` being in ``DISTRO_FEATURES``. + +- For EFI-based machines, the bootloader (``grub-efi`` by default) is + installed into the image at /boot. Wic can be used to split the + bootloader into separate boot and rootfs partitions if necessary. + +- Patches whose context does not match exactly (i.e. where patch + reports "fuzz" when applying) will generate a warning. For an example + of this see `this + commit <http://git.yoctoproject.org/cgit/cgit.cgi/poky/commit/?id=cc97bc08125b63821ce3f616771830f77c456f57>`__. + +- Layers are expected to set ``LAYERSERIES_COMPAT_layername`` to match + the version(s) of OpenEmbedded-Core they are compatible with. This is + specified as codenames using spaces to separate multiple values (e.g. + "rocko sumo"). If a layer does not set + ``LAYERSERIES_COMPAT_layername``, a warning will is shown. If a layer + sets a value that does not include the current version ("sumo" for + the 2.5 release), then an error will be produced. + +- The ``TZ`` environment variable is set to "UTC" within the build + environment in order to fix reproducibility problems in some recipes. + + diff --git a/poky/documentation/ref-manual/migration-2.6.rst b/poky/documentation/ref-manual/migration-2.6.rst new file mode 100644 index 000000000..f16aaaa97 --- /dev/null +++ b/poky/documentation/ref-manual/migration-2.6.rst @@ -0,0 +1,476 @@ +Moving to the Yocto Project 2.6 Release +======================================= + +This section provides migration information for moving to the Yocto +Project 2.6 Release from the prior release. + +.. _migration-2.6-gcc-changes: + +GCC 8.2 is Now Used by Default +------------------------------ + +The GNU Compiler Collection version 8.2 is now used by default for +compilation. For more information on what has changed in the GCC 8.x +release, see https://gcc.gnu.org/gcc-8/changes.html. + +If you still need to compile with version 7.x, GCC 7.3 is also provided. +You can select this version by setting the and can be selected by +setting the :term:`GCCVERSION` variable to "7.%" in +your configuration. + +.. _migration-2.6-removed-recipes: + +Removed Recipes +--------------- + +The following recipes have been removed: + +- *beecrypt*: No longer needed since moving to RPM 4. +- *bigreqsproto*: Replaced by ``xorgproto``. +- *calibrateproto*: Removed in favor of ``xinput``. +- *compositeproto*: Replaced by ``xorgproto``. +- *damageproto*: Replaced by ``xorgproto``. +- *dmxproto*: Replaced by ``xorgproto``. +- *dri2proto*: Replaced by ``xorgproto``. +- *dri3proto*: Replaced by ``xorgproto``. +- *eee-acpi-scripts*: Became obsolete. +- *fixesproto*: Replaced by ``xorgproto``. +- *fontsproto*: Replaced by ``xorgproto``. +- *fstests*: Became obsolete. +- *gccmakedep*: No longer used. +- *glproto*: Replaced by ``xorgproto``. +- *gnome-desktop3*: No longer needed. This recipe has moved to ``meta-oe``. +- *icon-naming-utils*: No longer used since the Sato theme was removed in 2016. +- *inputproto*: Replaced by ``xorgproto``. +- *kbproto*: Replaced by ``xorgproto``. +- *libusb-compat*: Became obsolete. +- *libuser*: Became obsolete. +- *libnfsidmap*: No longer an external requirement since ``nfs-utils`` 2.2.1. ``libnfsidmap`` is now integrated. +- *libxcalibrate*: No longer needed with ``xinput`` +- *mktemp*: Became obsolete. The ``mktemp`` command is provided by both ``busybox`` and ``coreutils``. +- *ossp-uuid*: Is not being maintained and has mostly been replaced by ``uuid.h`` in ``util-linux``. +- *pax-utils*: No longer needed. Previous QA tests that did use this recipe are now done at build time. +- *pcmciautils*: Became obsolete. +- *pixz*: No longer needed. ``xz`` now supports multi-threaded compression. +- *presentproto*: Replaced by ``xorgproto``. +- *randrproto*: Replaced by ``xorgproto``. +- *recordproto*: Replaced by ``xorgproto``. +- *renderproto*: Replaced by ``xorgproto``. +- *resourceproto*: Replaced by ``xorgproto``. +- *scrnsaverproto*: Replaced by ``xorgproto``. +- *trace-cmd*: Became obsolete. ``perf`` replaced this recipe's functionally. +- *videoproto*: Replaced by ``xorgproto``. +- *wireless-tools*: Became obsolete. Superseded by ``iw``. +- *xcmiscproto*: Replaced by ``xorgproto``. +- *xextproto*: Replaced by ``xorgproto``. +- *xf86dgaproto*: Replaced by ``xorgproto``. +- *xf86driproto*: Replaced by ``xorgproto``. +- *xf86miscproto*: Replaced by ``xorgproto``. +- *xf86-video-omapfb*: Became obsolete. Use kernel modesetting driver instead. +- *xf86-video-omap*: Became obsolete. Use kernel modesetting driver instead. +- *xf86vidmodeproto*: Replaced by ``xorgproto``. +- *xineramaproto*: Replaced by ``xorgproto``. +- *xproto*: Replaced by ``xorgproto``. +- *yasm*: No longer needed since previous usages are now satisfied by ``nasm``. + +.. _migration-2.6-packaging-changes: + +Packaging Changes +----------------- + +The following packaging changes have been made: + +- *cmake*: ``cmake.m4`` and ``toolchain`` files have been moved to + the main package. + +- *iptables*: The ``iptables`` modules have been split into + separate packages. + +- *alsa-lib*: ``libasound`` is now in the main ``alsa-lib`` package + instead of ``libasound``. + +- *glibc*: ``libnss-db`` is now in its own package along with a + ``/var/db/makedbs.sh`` script to update databases. + +- *python and python3*: The main package has been removed from + the recipe. You must install specific packages or ``python-modules`` + / ``python3-modules`` for everything. + +- *systemtap*: Moved ``systemtap-exporter`` into its own package. + +.. _migration-2.6-xorg-protocol-dependencies: + +XOrg Protocol dependencies +-------------------------- + +The ``*proto`` upstream repositories have been combined into one +"xorgproto" repository. Thus, the corresponding recipes have also been +combined into a single ``xorgproto`` recipe. Any recipes that depend +upon the older ``*proto`` recipes need to be changed to depend on the +newer ``xorgproto`` recipe instead. + +For names of recipes removed because of this repository change, see the +`Removed Recipes <#migration-2.6-removed-recipes>`__ section. + +.. _migration-2.6-distutils-distutils3-fetching-dependencies: + +``distutils`` and ``distutils3`` Now Prevent Fetching Dependencies During the ``do_configure`` Task +--------------------------------------------------------------------------------------------------- + +Previously, it was possible for Python recipes that inherited the +:ref:`distutils <ref-classes-distutils>` and +:ref:`distutils3 <ref-classes-distutils3>` classes to fetch code +during the :ref:`ref-tasks-configure` task to satisfy +dependencies mentioned in ``setup.py`` if those dependencies were not +provided in the sysroot (i.e. recipes providing the dependencies were +missing from :term:`DEPENDS`). + +.. note:: + + This change affects classes beyond just the two mentioned (i.e. + distutils + and + distutils3 + ). Any recipe that inherits + distutils\* + classes are affected. For example, the + setuptools + and + setuptools3 + recipes are affected since they inherit the + distutils\* + classes. + +Fetching these types of dependencies that are not provided in the +sysroot negatively affects the ability to reproduce builds. This type of +fetching is now explicitly disabled. Consequently, any missing +dependencies in Python recipes that use these classes now result in an +error during the ``do_configure`` task. + +.. _migration-2.6-linux-yocto-configuration-audit-issues-now-correctly-reported: + +``linux-yocto`` Configuration Audit Issues Now Correctly Reported +----------------------------------------------------------------- + +Due to a bug, the kernel configuration audit functionality was not +writing out any resulting warnings during the build. This issue is now +corrected. You might notice these warnings now if you have a custom +kernel configuration with a ``linux-yocto`` style kernel recipe. + +.. _migration-2.6-image-kernel-artifact-naming-changes: + +Image/Kernel Artifact Naming Changes +------------------------------------ + +The following changes have been made: + +- Name variables (e.g. :term:`IMAGE_NAME`) use a new + ``IMAGE_VERSION_SUFFIX`` variable instead of + :term:`DATETIME`. Using ``IMAGE_VERSION_SUFFIX`` + allows easier and more direct changes. + + The ``IMAGE_VERSION_SUFFIX`` variable is set in the ``bitbake.conf`` + configuration file as follows: + :: + + IMAGE_VERSION_SUFFIX = "-${DATETIME}" + +- Several variables have changed names for consistency: + :: + + Old Variable Name New Variable Name + ======================================================== + KERNEL_IMAGE_BASE_NAME :term:`KERNEL_IMAGE_NAME` + KERNEL_IMAGE_SYMLINK_NAME :term:`KERNEL_IMAGE_LINK_NAME` + MODULE_TARBALL_BASE_NAME :term:`MODULE_TARBALL_NAME` + MODULE_TARBALL_SYMLINK_NAME :term:`MODULE_TARBALL_LINK_NAME` + INITRAMFS_BASE_NAME :term:`INITRAMFS_NAME` + +- The ``MODULE_IMAGE_BASE_NAME`` variable has been removed. The module + tarball name is now controlled directly with the + :term:`MODULE_TARBALL_NAME` variable. + +- The :term:`KERNEL_DTB_NAME` and + :term:`KERNEL_DTB_LINK_NAME` variables + have been introduced to control kernel Device Tree Binary (DTB) + artifact names instead of mangling ``KERNEL_IMAGE_*`` variables. + +- The :term:`KERNEL_FIT_NAME` and + :term:`KERNEL_FIT_LINK_NAME` variables + have been introduced to specify the name of flattened image tree + (FIT) kernel images similar to other deployed artifacts. + +- The :term:`MODULE_TARBALL_NAME` and + :term:`MODULE_TARBALL_LINK_NAME` + variable values no longer include the "module-" prefix or ".tgz" + suffix. These parts are now hardcoded so that the values are + consistent with other artifact naming variables. + +- Added the :term:`INITRAMFS_LINK_NAME` + variable so that the symlink can be controlled similarly to other + artifact types. + +- :term:`INITRAMFS_NAME` now uses + "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}" instead + of "${PV}-${PR}-${MACHINE}-${DATETIME}", which makes it consistent + with other variables. + +.. _migration-2.6-serial-console-deprecated: + +``SERIAL_CONSOLE`` Deprecated +----------------------------- + +The :term:`SERIAL_CONSOLE` variable has been +functionally replaced by the +:term:`SERIAL_CONSOLES` variable for some time. +With the Yocto Project 2.6 release, ``SERIAL_CONSOLE`` has been +officially deprecated. + +``SERIAL_CONSOLE`` will continue to work as before for the 2.6 release. +However, for the sake of future compatibility, it is recommended that +you replace all instances of ``SERIAL_CONSOLE`` with +``SERIAL_CONSOLES``. + +.. note:: + + The only difference in usage is that + SERIAL_CONSOLES + expects entries to be separated using semicolons as compared to + SERIAL_CONSOLE + , which expects spaces. + +.. _migration-2.6-poky-sets-unknown-configure-option-to-qa-error: + +Configure Script Reports Unknown Options as Errors +-------------------------------------------------- + +If the configure script reports an unknown option, this now triggers a +QA error instead of a warning. Any recipes that previously got away with +specifying such unknown options now need to be fixed. + +.. _migration-2.6-override-changes: + +Override Changes +---------------- + +The following changes have occurred: + +- The ``virtclass-native`` and ``virtclass-nativesdk`` Overrides Have + Been Removed: The ``virtclass-native`` and ``virtclass-nativesdk`` + overrides have been deprecated since 2012 in favor of + ``class-native`` and ``class-nativesdk``, respectively. Both + ``virtclass-native`` and ``virtclass-nativesdk`` are now dropped. + + .. note:: + + The + virtclass-multilib- + overrides for multilib are still valid. + +- The ``forcevariable`` Override Now Has a Higher Priority Than + ``libc`` Overrides: The ``forcevariable`` override is documented to + be the highest priority override. However, due to a long-standing + quirk of how :term:`OVERRIDES` is set, the ``libc`` + overrides (e.g. ``libc-glibc``, ``libc-musl``, and so forth) + erroneously had a higher priority. This issue is now corrected. + + It is likely this change will not cause any problems. However, it is + possible with some unusual configurations that you might see a change + in behavior if you were relying on the previous behavior. Be sure to + check how you use ``forcevariable`` and ``libc-*`` overrides in your + custom layers and configuration files to ensure they make sense. + +- The ``build-${BUILD_OS}`` Override Has Been Removed: The + ``build-${BUILD_OS}``, which is typically ``build-linux``, override + has been removed because building on a host operating system other + than a recent version of Linux is neither supported nor recommended. + Dropping the override avoids giving the impression that other host + operating systems might be supported. + +- The "_remove" operator now preserves whitespace. Consequently, when + specifying list items to remove, be aware that leading and trailing + whitespace resulting from the removal is retained. + + See the ":ref:`bitbake:removing-override-style-syntax`" + section in the BitBake User Manual for a detailed example. + +.. _migration-2.6-systemd-configuration-now-split-out-to-system-conf: + +``systemd`` Configuration is Now Split Into ``systemd-conf`` +------------------------------------------------------------ + +The configuration for the ``systemd`` recipe has been moved into a +``system-conf`` recipe. Moving this configuration to a separate recipe +avoids the ``systemd`` recipe from becoming machine-specific for cases +where machine-specific configurations need to be applied (e.g. for +``qemu*`` machines). + +Currently, the new recipe packages the following files: +:: + + ${sysconfdir}/machine-id + ${sysconfdir}/systemd/coredump.conf + ${sysconfdir}/systemd/journald.conf + ${sysconfdir}/systemd/logind.conf + ${sysconfdir}/systemd/system.conf + ${sysconfdir}/systemd/user.conf + +If you previously used bbappend files to append the ``systemd`` recipe to +change any of the listed files, you must do so for the ``systemd-conf`` +recipe instead. + +.. _migration-2.6-automatic-testing-changes: + +Automatic Testing Changes +------------------------- + +This section provides information about automatic testing changes: + +- ``TEST_IMAGE`` Variable Removed: Prior to this release, you set the + ``TEST_IMAGE`` variable to "1" to enable automatic testing for + successfully built images. The ``TEST_IMAGE`` variable no longer + exists and has been replaced by the + :term:`TESTIMAGE_AUTO` variable. + +- Inheriting the ``testimage`` and ``testsdk`` Classes: Best + practices now dictate that you use the + :term:`IMAGE_CLASSES` variable rather than the + :term:`INHERIT` variable when you inherit the + :ref:`testimage <ref-classes-testimage*>` and + :ref:`testsdk <ref-classes-testsdk>` classes used for automatic + testing. + +.. _migration-2.6-openssl-changes: + +OpenSSL Changes +--------------- + +`OpenSSL <https://www.openssl.org/>`__ has been upgraded from 1.0 to +1.1. By default, this upgrade could cause problems for recipes that have +both versions in their dependency chains. The problem is that both +versions cannot be installed together at build time. + +.. note:: + + It is possible to have both versions of the library at runtime. + +.. _migration-2.6-bitbake-changes: + +BitBake Changes +--------------- + +The server logfile ``bitbake-cookerdaemon.log`` is now always placed in +the :term:`Build Directory` instead of the current +directory. + +.. _migration-2.6-security-changes: + +Security Changes +---------------- + +The Poky distribution now uses security compiler flags by default. +Inclusion of these flags could cause new failures due to stricter +checking for various potential security issues in code. + +.. _migration-2.6-post-installation-changes: + +Post Installation Changes +------------------------- + +You must explicitly mark post installs to defer to the target. If you +want to explicitly defer a postinstall to first boot on the target +rather than at rootfs creation time, use ``pkg_postinst_ontarget()`` or +call ``postinst_intercept delay_to_first_boot`` from ``pkg_postinst()``. +Any failure of a ``pkg_postinst()`` script (including exit 1) triggers +an error during the :ref:`ref-tasks-rootfs` task. + +For more information on post-installation behavior, see the +":ref:`dev-manual/dev-manual-common-tasks:post-installation scripts`" +section in the Yocto Project Development Tasks Manual. + +.. _migration-2.6-python-3-profile-guided-optimizations: + +Python 3 Profile-Guided Optimization +------------------------------------ + +The ``python3`` recipe now enables profile-guided optimization. Using +this optimization requires a little extra build time in exchange for +improved performance on the target at runtime. Additionally, the +optimization is only enabled if the current +:term:`MACHINE` has support for user-mode emulation in +QEMU (i.e. "qemu-usermode" is in +:term:`MACHINE_FEATURES`, which it is by +default). + +If you wish to disable Python profile-guided optimization regardless of +the value of ``MACHINE_FEATURES``, then ensure that +:term:`PACKAGECONFIG` for the ``python3`` recipe +does not contain "pgo". You could accomplish the latter using the +following at the configuration level: +:: + + PACKAGECONFIG_remove_pn-python3 = "pgo" + +Alternatively, you can set ``PACKAGECONFIG`` using an append file +for the ``python3`` recipe. + +.. _migration-2.6-miscellaneous-changes: + +Miscellaneous Changes +--------------------- + +The following miscellaneous changes occurred: + +- Default to using the Thumb-2 instruction set for armv7a and above. If + you have any custom recipes that build software that needs to be + built with the ARM instruction set, change the recipe to set the + instruction set as follows: + :: + + ARM_INSTRUCTION_SET = "arm" + +- ``run-postinsts`` no longer uses ``/etc/*-postinsts`` for + ``dpkg/opkg`` in favor of built-in postinst support. RPM behavior + remains unchanged. + +- The ``NOISO`` and ``NOHDD`` variables are no longer used. You now + control building ``*.iso`` and ``*.hddimg`` image types directly by + using the :term:`IMAGE_FSTYPES` variable. + +- The ``scripts/contrib/mkefidisk.sh`` has been removed in favor of + Wic. + +- ``kernel-modules`` has been removed from + :term:`RRECOMMENDS` for ``qemumips`` and + ``qemumips64`` machines. Removal also impacts the ``x86-base.inc`` + file. + + .. note:: + + genericx86 + and + genericx86-64 + retain + kernel-modules + as part of the + RRECOMMENDS + variable setting. + +- The ``LGPLv2_WHITELIST_GPL-3.0`` variable has been removed. If you + are setting this variable in your configuration, set or append it to + the ``WHITELIST_GPL-3.0`` variable instead. + +- ``${ASNEEDED}`` is now included in the + :term:`TARGET_LDFLAGS` variable directly. The + remaining definitions from ``meta/conf/distro/include/as-needed.inc`` + have been moved to corresponding recipes. + +- Support for DSA host keys has been dropped from the OpenSSH recipes. + If you are still using DSA keys, you must switch over to a more + secure algorithm as recommended by OpenSSH upstream. + +- The ``dhcp`` recipe now uses the ``dhcpd6.conf`` configuration file + in ``dhcpd6.service`` for IPv6 DHCP rather than re-using + ``dhcpd.conf``, which is now reserved for IPv4. + + diff --git a/poky/documentation/ref-manual/migration-2.7.rst b/poky/documentation/ref-manual/migration-2.7.rst new file mode 100644 index 000000000..7e628fc3e --- /dev/null +++ b/poky/documentation/ref-manual/migration-2.7.rst @@ -0,0 +1,180 @@ +Moving to the Yocto Project 2.7 Release +======================================= + +This section provides migration information for moving to the Yocto +Project 2.7 Release from the prior release. + +.. _migration-2.7-bitbake-changes: + +BitBake Changes +--------------- + +The following changes have been made to BitBake: + +- BitBake now checks anonymous Python functions and pure Python + functions (e.g. ``def funcname:``) in the metadata for tab + indentation. If found, BitBake produces a warning. + +- Bitbake now checks + :term:`BBFILE_COLLECTIONS` for duplicate + entries and triggers an error if any are found. + +.. _migration-2.7-eclipse-support-dropped: + +Eclipse Support Removed +----------------------- + +Support for the Eclipse IDE has been removed. Support continues for +those releases prior to 2.7 that did include support. The 2.7 release +does not include the Eclipse Yocto plugin. + +.. _migration-2.7-qemu-native-splits-system-and-user-mode-parts: + +``qemu-native`` Splits the System and User-Mode Parts +----------------------------------------------------- + +The system and user-mode parts of ``qemu-native`` are now split. +``qemu-native`` provides the user-mode components and +``qemu-system-native`` provides the system components. If you have +recipes that depend on QEMU's system emulation functionality at build +time, they should now depend upon ``qemu-system-native`` instead of +``qemu-native``. + +.. _migration-2.7-upstream-tracking.inc-removed: + +The ``upstream-tracking.inc`` File Has Been Removed +--------------------------------------------------- + +The previously deprecated ``upstream-tracking.inc`` file is now removed. +Any ``UPSTREAM_TRACKING*`` variables are now set in the corresponding +recipes instead. + +Remove any references you have to the ``upstream-tracking.inc`` file in +your configuration. + +.. _migration-2.7-distro-features-libc-removed: + +The ``DISTRO_FEATURES_LIBC`` Variable Has Been Removed +------------------------------------------------------ + +The ``DISTRO_FEATURES_LIBC`` variable is no longer used. The ability to +configure glibc using kconfig has been removed for quite some time +making the ``libc-*`` features set no longer effective. + +Remove any references you have to ``DISTRO_FEATURES_LIBC`` in your own +layers. + +.. _migration-2.7-license-values: + +License Value Corrections +------------------------- + +The following corrections have been made to the +:term:`LICENSE` values set by recipes: + +- *socat*: Corrected ``LICENSE`` to be "GPLv2" rather than "GPLv2+". +- *libgfortran*: Set license to "GPL-3.0-with-GCC-exception". +- *elfutils*: Removed "Elfutils-Exception" and set to "GPLv2" for shared libraries + +.. _migration-2.7-packaging-changes: + +Packaging Changes +----------------- + +This section provides information about packaging changes. + +- ``bind``: The ``nsupdate`` binary has been moved to the + ``bind-utils`` package. + +- Debug split: The default debug split has been changed to create + separate source packages (i.e. package_name\ ``-dbg`` and + package_name\ ``-src``). If you are currently using ``dbg-pkgs`` in + :term:`IMAGE_FEATURES` to bring in debug + symbols and you still need the sources, you must now also add + ``src-pkgs`` to ``IMAGE_FEATURES``. Source packages remain in the + target portion of the SDK by default, unless you have set your own + value for :term:`SDKIMAGE_FEATURES` that + does not include ``src-pkgs``. + +- Mount all using ``util-linux``: ``/etc/default/mountall`` has moved + into the -mount sub-package. + +- Splitting binaries using ``util-linux``: ``util-linux`` now splits + each binary into its own package for fine-grained control. The main + ``util-linux`` package pulls in the individual binary packages using + the :term:`RRECOMMENDS` and + :term:`RDEPENDS` variables. As a result, existing + images should not see any changes assuming + :term:`NO_RECOMMENDATIONS` is not set. + +- ``netbase/base-files``: ``/etc/hosts`` has moved from ``netbase`` to + ``base-files``. + +- ``tzdata``: The main package has been converted to an empty meta + package that pulls in all ``tzdata`` packages by default. + +- ``lrzsz``: This package has been removed from + ``packagegroup-self-hosted`` and + ``packagegroup-core-tools-testapps``. The X/Y/ZModem support is less + likely to be needed on modern systems. If you are relying on these + packagegroups to include the ``lrzsz`` package in your image, you now + need to explicitly add the package. + +.. _migration-2.7-removed-recipes: + +Removed Recipes +--------------- + +The following recipes have been removed: + +- *gcc*: Drop version 7.3 recipes. Version 8.3 now remains. +- *linux-yocto*: Drop versions 4.14 and 4.18 recipes. Versions 4.19 and 5.0 remain. +- *go*: Drop version 1.9 recipes. Versions 1.11 and 1.12 remain. +- *xvideo-tests*: Became obsolete. +- *libart-lgpl*: Became obsolete. +- *gtk-icon-utils-native*: These tools are now provided by gtk+3-native +- *gcc-cross-initial*: No longer needed. gcc-cross/gcc-crosssdk is now used instead. +- *gcc-crosssdk-initial*: No longer needed. gcc-cross/gcc-crosssdk is now used instead. +- *glibc-initial*: Removed because the benefits of having it for site_config are currently outweighed by the cost of building the recipe. + +.. _migration-2.7-removed-classes: + +Removed Classes +--------------- + +The following classes have been removed: + +- *distutils-tools*: This class was never used. +- *bugzilla.bbclass*: Became obsolete. +- *distrodata*: This functionally has been replaced by a more modern tinfoil-based implementation. + +.. _migration-2.7-miscellaneous-changes: + +Miscellaneous Changes +--------------------- + +The following miscellaneous changes occurred: + +- The ``distro`` subdirectory of the Poky repository has been removed + from the top-level ``scripts`` directory. + +- Perl now builds for the target using + `perl-cross <http://arsv.github.io/perl-cross/>`_ for better + maintainability and improved build performance. This change should + not present any problems unless you have heavily customized your Perl + recipe. + +- ``arm-tunes``: Removed the "-march" option if mcpu is already added. + +- ``update-alternatives``: Convert file renames to + :term:`PACKAGE_PREPROCESS_FUNCS` + +- ``base/pixbufcache``: Obsolete ``sstatecompletions`` code has been + removed. + +- :ref:`native <ref-classes-native>` class: + :term:`RDEPENDS` handling has been enabled. + +- ``inetutils``: This recipe has rsh disabled. + + diff --git a/poky/documentation/ref-manual/migration-3.0.rst b/poky/documentation/ref-manual/migration-3.0.rst new file mode 100644 index 000000000..e1305dfcc --- /dev/null +++ b/poky/documentation/ref-manual/migration-3.0.rst @@ -0,0 +1,321 @@ +Moving to the Yocto Project 3.0 Release +======================================= + +This section provides migration information for moving to the Yocto +Project 3.0 Release from the prior release. + +.. _migration-3.0-init-system-selection: + +Init System Selection +--------------------- + +Changing the init system manager previously required setting a number of +different variables. You can now change the manager by setting the +``INIT_MANAGER`` variable and the corresponding include files (i.e. +``conf/distro/include/init-manager-*.conf``). Include files are provided +for four values: "none", "sysvinit", "systemd", and "mdev-busybox". The +default value, "none", for ``INIT_MANAGER`` should allow your current +settings to continue working. However, it is advisable to explicitly set +``INIT_MANAGER``. + +.. _migration-3.0-lsb-support-removed: + +LSB Support Removed +------------------- + +Linux Standard Base (LSB) as a standard is not current, and is not well +suited for embedded applications. Support can be continued in a separate +layer if needed. However, presently LSB support has been removed from +the core. + +As a result of this change, the ``poky-lsb`` derivative distribution +configuration that was also used for testing alternative configurations +has been replaced with a ``poky-altcfg`` distribution that has LSB parts +removed. + +.. _migration-3.0-removed-recipes: + +Removed Recipes +--------------- + +The following recipes have been removed. + +- ``core-image-lsb-dev``: Part of removed LSB support. + +- ``core-image-lsb``: Part of removed LSB support. + +- ``core-image-lsb-sdk``: Part of removed LSB support. + +- ``cve-check-tool``: Functionally replaced by the ``cve-update-db`` + recipe and ``cve-check`` class. + +- ``eglinfo``: No longer maintained. ``eglinfo`` from ``mesa-demos`` is + an adequate and maintained alternative. + +- ``gcc-8.3``: Version 8.3 removed. Replaced by 9.2. + +- ``gnome-themes-standard``: Only needed by gtk+ 2.x, which has been + removed. + +- ``gtk+``: GTK+ 2 is obsolete and has been replaced by gtk+3. + +- ``irda-utils``: Has become obsolete. IrDA support has been removed + from the Linux kernel in version 4.17 and later. + +- ``libnewt-python``: ``libnewt`` Python support merged into main + ``libnewt`` recipe. + +- ``libsdl``: Replaced by newer ``libsdl2``. + +- ``libx11-diet``: Became obsolete. + +- ``libxx86dga``: Removed obsolete client library. + +- ``libxx86misc``: Removed. Library is redundant. + +- ``linux-yocto``: Version 5.0 removed, which is now redundant (5.2 / + 4.19 present). + +- ``lsbinitscripts``: Part of removed LSB support. + +- ``lsb``: Part of removed LSB support. + +- ``lsbtest``: Part of removed LSB support. + +- ``openssl10``: Replaced by newer ``openssl`` version 1.1. + +- ``packagegroup-core-lsb``: Part of removed LSB support. + +- ``python-nose``: Removed the Python 2.x version of the recipe. + +- ``python-numpy``: Removed the Python 2.x version of the recipe. + +- ``python-scons``: Removed the Python 2.x version of the recipe. + +- ``source-highlight``: No longer needed. + +- ``stress``: Replaced by ``stress-ng``. + +- ``vulkan``: Split into ``vulkan-loader``, ``vulkan-headers``, and + ``vulkan-tools``. + +- ``weston-conf``: Functionality moved to ``weston-init``. + +.. _migration-3.0-packaging-changes: + +Packaging Changes +----------------- + +The following packaging changes have occurred. + +- The `Epiphany <https://en.wikipedia.org/wiki/GNOME_Web>`__ browser + has been dropped from ``packagegroup-self-hosted`` as it has not been + needed inside ``build-appliance-image`` for quite some time and was + causing resource problems. + +- ``libcap-ng`` Python support has been moved to a separate + ``libcap-ng-python`` recipe to streamline the build process when the + Python bindings are not needed. + +- ``libdrm`` now packages the file ``amdgpu.ids`` into a separate + ``libdrm-amdgpu`` package. + +- ``python3``: The ``runpy`` module is now in the ``python3-core`` + package as it is required to support the common "python3 -m" command + usage. + +- ``distcc`` now provides separate ``distcc-client`` and + ``distcc-server`` packages as typically one or the other are needed, + rather than both. + +- ``python*-setuptools`` recipes now separately package the + ``pkg_resources`` module in a ``python-pkg-resources`` / + ``python3-pkg-resources`` package as the module is useful independent + of the rest of the setuptools package. The main ``python-setuptools`` + / ``python3-setuptools`` package depends on this new package so you + should only need to update dependencies unless you want to take + advantage of the increased granularity. + +.. _migration-3.0-cve-checking: + +CVE Checking +------------ + +``cve-check-tool`` has been functionally replaced by a new +``cve-update-db`` recipe and functionality built into the ``cve-check`` +class. The result uses NVD JSON data feeds rather than the deprecated +XML feeds that ``cve-check-tool`` was using, supports CVSSv3 scoring, +and makes other improvements. + +Additionally, the ``CVE_CHECK_CVE_WHITELIST`` variable has been replaced +by ``CVE_CHECK_WHITELIST``. + +.. _migration-3.0-bitbake-changes: + +Bitbake Changes +--------------- + +The following BitBake changes have occurred. + +- ``addtask`` statements now properly validate dependent tasks. + Previously, an invalid task was silently ignored. With this change, + the invalid task generates a warning. + +- Other invalid ``addtask`` and ``deltask`` usages now trigger these + warnings: "multiple target tasks arguments with addtask / deltask", + and "multiple before/after clauses". + +- The "multiconfig" prefix is now shortened to "mc". "multiconfig" will + continue to work, however it may be removed in a future release. + +- The ``bitbake -g`` command no longer generates a + ``recipe-depends.dot`` file as the contents (i.e. a reprocessed + version of ``task-depends.dot``) were confusing. + +- The ``bb.build.FuncFailed`` exception, previously raised by + ``bb.build.exec_func()`` when certain other exceptions have occurred, + has been removed. The real underlying exceptions will be raised + instead. If you have calls to ``bb.build.exec_func()`` in custom + classes or ``tinfoil-using`` scripts, any references to + ``bb.build.FuncFailed`` should be cleaned up. + +- Additionally, the ``bb.build.exec_func()`` no longer accepts the + "pythonexception" parameter. The function now always raises + exceptions. Remove this argument in any calls to + ``bb.build.exec_func()`` in custom classes or scripts. + +- The + :term:`bitbake:BB_SETSCENE_VERIFY_FUNCTION2` + is no longer used. In the unlikely event that you have any references + to it, they should be removed. + +- The ``RunQueueExecuteScenequeue`` and ``RunQueueExecuteTasks`` events + have been removed since setscene tasks are now executed as part of + the normal runqueue. Any event handling code in custom classes or + scripts that handles these two events need to be updated. + +- The arguments passed to functions used with + :term:`bitbake:BB_HASHCHECK_FUNCTION` + have changed. If you are using your own custom hash check function, + see + http://git.yoctoproject.org/cgit/cgit.cgi/poky/commit/?id=40a5e193c4ba45c928fccd899415ea56b5417725 + for details. + +- Task specifications in ``BB_TASKDEPDATA`` and class implementations + used in signature generator classes now use "<fn>:<task>" everywhere + rather than the "." delimiter that was being used in some places. + This change makes it consistent with all areas in the code. Custom + signature generator classes and code that reads ``BB_TASKDEPDATA`` + need to be updated to use ':' as a separator rather than '.'. + +.. _migration-3.0-sanity-checks: + +Sanity Checks +------------- + +The following sanity check changes occurred. + +- :term:`SRC_URI` is now checked for usage of two + problematic items: + + - "${PN}" prefix/suffix use - Warnings always appear if ${PN} is + used. You must fix the issue regardless of whether multiconfig or + anything else that would cause prefixing/suffixing to happen. + + - Github archive tarballs - these are not guaranteed to be stable. + Consequently, it is likely that the tarballs will be refreshed and + thus the SRC_URI checksums will fail to apply. It is recommended + that you fetch either an official release tarball or a specific + revision from the actual Git repository instead. + + Either one of these items now trigger a warning by default. If you + wish to disable this check, remove ``src-uri-bad`` from + :term:`WARN_QA`. + +- The ``file-rdeps`` runtime dependency check no longer expands + :term:`RDEPENDS` recursively as there is no mechanism + to ensure they can be fully computed, and thus races sometimes result + in errors either showing up or not. Thus, you might now see errors + for missing runtime dependencies that were previously satisfied + recursively. Here is an example: package A contains a shell script + starting with ``#!/bin/bash`` but has no dependency on bash. However, + package A depends on package B, which does depend on bash. You need + to add the missing dependency or dependencies to resolve the warning. + +- Setting ``DEPENDS_${PN}`` anywhere (i.e. typically in a recipe) now + triggers an error. The error is triggered because + :term:`DEPENDS` is not a package-specific variable + unlike RDEPENDS. You should set ``DEPENDS`` instead. + +- systemd currently does not work well with the musl C library because + only upstream officially supports linking the library with glibc. + Thus, a warning is shown when building systemd in conjunction with + musl. + +.. _migration-3.0-miscellaneous-changes: + +Miscellaneous Changes +--------------------- + +The following miscellaneous changes have occurred. + +- The ``gnome`` class has been removed because it now does very little. + You should update recipes that previously inherited this class to do + the following: inherit gnomebase gtk-icon-cache gconf mime + +- The ``meta/recipes-kernel/linux/linux-dtb.inc`` file has been + removed. This file was previously deprecated in favor of setting + :term:`KERNEL_DEVICETREE` in any kernel + recipe and only produced a warning. Remove any ``include`` or + ``require`` statements pointing to this file. + +- :term:`TARGET_CFLAGS`, + :term:`TARGET_CPPFLAGS`, + :term:`TARGET_CXXFLAGS`, and + :term:`TARGET_LDFLAGS` are no longer exported + to the external environment. This change did not require any changes + to core recipes, which is a good indicator that no changes will be + required. However, if for some reason the software being built by one + of your recipes is expecting these variables to be set, then building + the recipe will fail. In such cases, you must either export the + variable or variables in the recipe or change the scripts so that + exporting is not necessary. + +- You must change the host distro identifier used in + :term:`NATIVELSBSTRING` to use all lowercase + characters even if it does not contain a version number. This change + is necessary only if you are not using ``uninative`` and + :term:`SANITY_TESTED_DISTROS`. + +- In the ``base-files`` recipe, writing the hostname into + ``/etc/hosts`` and ``/etc/hostname`` is now done within the main + :ref:`ref-tasks-install` function rather than in the + ``do_install_basefilesissue`` function. The reason for the change is + because ``do_install_basefilesissue`` is more easily overridden + without having to duplicate the hostname functionality. If you have + done the latter (e.g. in a ``base-files`` bbappend), then you should + remove it from your customized ``do_install_basefilesissue`` + function. + +- The ``wic --expand`` command now uses commas to separate "key:value" + pairs rather than hyphens. + + .. note:: + + The wic command-line help is not updated. + + You must update any scripts or commands where you use + ``wic --expand`` with multiple "key:value" pairs. + +- UEFI image variable settings have been moved from various places to a + central ``conf/image-uefi.conf``. This change should not influence + any existing configuration as the ``meta/conf/image-uefi.conf`` in + the core metadata sets defaults that can be overridden in the same + manner as before. + +- ``conf/distro/include/world-broken.inc`` has been removed. For cases + where certain recipes need to be disabled when using the musl C + library, these recipes now have ``COMPATIBLE_HOST_libc-musl`` set + with a comment that explains why. + + diff --git a/poky/documentation/ref-manual/migration-3.1.rst b/poky/documentation/ref-manual/migration-3.1.rst new file mode 100644 index 000000000..92c8c7761 --- /dev/null +++ b/poky/documentation/ref-manual/migration-3.1.rst @@ -0,0 +1,276 @@ +Moving to the Yocto Project 3.1 Release +======================================= + +This section provides migration information for moving to the Yocto +Project 3.1 Release from the prior release. + +.. _migration-3.1-minimum-system-requirements: + +Minimum system requirements +--------------------------- + +The following versions / requirements of build host components have been +updated: + +- gcc 5.0 + +- python 3.5 + +- tar 1.28 + +- ``rpcgen`` is now required on the host (part of the ``libc-dev-bin`` + package on Ubuntu, Debian and related distributions, and the + ``glibc`` package on RPM-based distributions). + +Additionally, the ``makeinfo`` and ``pod2man`` tools are *no longer* +required on the host. + +.. _migration-3.1-mpc8315e-rdb-removed: + +mpc8315e-rdb machine removed +---------------------------- + +The MPC8315E-RDB machine is old/obsolete and unobtainable, thus given +the maintenance burden the ``mpc8315e-rdb`` machine configuration that +supported it has been removed in this release. The removal does leave a +gap in official PowerPC reference hardware support; this may change in +future if a suitable machine with accompanying support resources is +found. + +.. _migration-3.1-python-2-removed: + +Python 2 removed +---------------- + +Due to the expiration of upstream support in January 2020, support for +Python 2 has now been removed; it is recommended that you use Python 3 +instead. If absolutely needed there is a meta-python2 community layer +containing Python 2, related classes and various Python 2-based modules, +however it should not be considered as supported. + +.. _migration-3.1-reproducible-builds: + +Reproducible builds now enabled by default +------------------------------------------ + +In order to avoid unnecessary differences in output files (aiding binary +reproducibility), the Poky distribution configuration +(``DISTRO = "poky"``) now inherits the ``reproducible_build`` class by +default. + +.. _migration-3.1-ptest-feature-impact: + +Impact of ptest feature is now more significant +----------------------------------------------- + +The Poky distribution configuration (``DISTRO = "poky"``) enables ptests +by default to enable runtime testing of various components. In this +release, a dependency needed to be added that has resulted in a +significant increase in the number of components that will be built just +when building a simple image such as core-image-minimal. If you do not +need runtime tests enabled for core components, then it is recommended +that you remove "ptest" from +:term:`DISTRO_FEATURES` to save a significant +amount of build time e.g. by adding the following in your configuration: +:: + + DISTRO_FEATURES_remove = "ptest" + +.. _migration-3.1-removed-recipes: + +Removed recipes +--------------- + +The following recipes have been removed: + +- ``chkconfig``: obsolete + +- ``console-tools``: obsolete + +- ``enchant``: replaced by ``enchant2`` + +- ``foomatic-filters``: obsolete + +- ``libidn``: no longer needed, moved to meta-oe + +- ``libmodulemd``: replaced by ``libmodulemd-v1`` + +- ``linux-yocto``: drop 4.19, 5.2 version recipes (5.4 now provided) + +- ``nspr``: no longer needed, moved to meta-oe + +- ``nss``: no longer needed, moved to meta-oe + +- ``python``: Python 2 removed (Python 3 preferred) + +- ``python-setuptools``: Python 2 version removed (python3-setuptools + preferred) + +- ``sysprof``: no longer needed, moved to meta-oe + +- ``texi2html``: obsolete + +- ``u-boot-fw-utils``: functionally replaced by ``libubootenv`` + +.. _migration-3.1-features-check: + +features_check class replaces distro_features_check +--------------------------------------------------- + +The ``distro_features_check`` class has had its functionality expanded, +now supporting ``ANY_OF_MACHINE_FEATURES``, +``REQUIRED_MACHINE_FEATURES``, ``CONFLICT_MACHINE_FEATURES``, +``ANY_OF_COMBINED_FEATURES``, ``REQUIRED_COMBINED_FEATURES``, +``CONFLICT_COMBINED_FEATURES``. As a result the class has now been +renamed to ``features_check``; the ``distro_features_check`` class still +exists but generates a warning and redirects to the new class. In +preparation for a future removal of the old class it is recommended that +you update recipes currently inheriting ``distro_features_check`` to +inherit ``features_check`` instead. + +.. _migration-3.1-removed-classes: + +Removed classes +--------------- + +The following classes have been removed: + +- ``distutils-base``: moved to meta-python2 + +- ``distutils``: moved to meta-python2 + +- ``libc-common``: merged into the glibc recipe as nothing else used + it. + +- ``python-dir``: moved to meta-python2 + +- ``pythonnative``: moved to meta-python2 + +- ``setuptools``: moved to meta-python2 + +- ``tinderclient``: dropped as it was obsolete. + +.. _migration-3.1-src-uri-checksums: + +SRC_URI checksum behaviour +-------------------------- + +Previously, recipes by tradition included both SHA256 and MD5 checksums +for remotely fetched files in :term:`SRC_URI`, even +though only one is actually mandated. However, the MD5 checksum does not +add much given its inherent weakness; thus when a checksum fails only +the SHA256 sum will now be printed. The md5sum will still be verified if +it is specified. + +.. _migration-3.1-npm: + +npm fetcher changes +------------------- + +The npm fetcher has been completely reworked in this release. The npm +fetcher now only fetches the package source itself and no longer the +dependencies; there is now also an npmsw fetcher which explicitly +fetches the shrinkwrap file and the dependencies. This removes the +slightly awkward ``NPM_LOCKDOWN`` and ``NPM_SHRINKWRAP`` variables which +pointed to local files; the lockdown file is no longer needed at all. +Additionally, the package name in ``npm://`` entries in +:term:`SRC_URI` is now specified using a ``package`` +parameter instead of the earlier ``name`` which overlapped with the +generic ``name`` parameter. All recipes using the npm fetcher will need +to be changed as a result. + +An example of the new scheme: :: + + SRC_URI = "npm://registry.npmjs.org;package=array-flatten;version=1.1.1 \\ + npmsw://${THISDIR}/npm-shrinkwrap.json" + +Another example where the sources are fetched from git rather than an npm repository: :: + + SRC_URI = "git://github.com/foo/bar.git;protocol=https \ + npmsw://${THISDIR}/npm-shrinkwrap.json" + +devtool and recipetool have also been updated to match with the npm +fetcher changes. Other than producing working and more complete recipes +for npm sources, there is also a minor change to the command line for +devtool: the ``--fetch-dev`` option has been renamed to ``--npm-dev`` as +it is npm-specific. + +.. _migration-3.1-packaging-changes: + +Packaging changes +----------------- + +- ``intltool`` has been removed from ``packagegroup-core-sdk`` as it is + rarely needed to build modern software - gettext can do most of the + things it used to be needed for. ``intltool`` has also been removed + from ``packagegroup-core-self-hosted`` as it is not needed to for + standard builds. + +- git: ``git-am``, ``git-difftool``, ``git-submodule``, and + ``git-request-pull`` are no longer perl-based, so are now installed + with the main ``git`` package instead of within ``git-perltools``. + +- The ``ldconfig`` binary built as part of glibc has now been moved to + its own ``ldconfig`` package (note no ``glibc-`` prefix). This + package is in the :term:`RRECOMMENDS` of the main + ``glibc`` package if ``ldconfig`` is present in + :term:`DISTRO_FEATURES`. + +- ``libevent`` now splits each shared library into its own package (as + Debian does). Since these are shared libraries and will be pulled in + through the normal shared library dependency handling, there should + be no impact to existing configurations other than less unnecessary + libraries being installed in some cases. + +- linux-firmware now has a new package for ``bcm4366c`` and includes + available NVRAM config files into the ``bcm43340``, ``bcm43362``, + ``bcm43430`` and ``bcm4356-pcie`` packages. + +- ``harfbuzz`` now splits the new ``libharfbuzz-subset.so`` library + into its own package to reduce the main package size in cases where + ``libharfbuzz-subset.so`` is not needed. + +.. _migration-3.1-package-qa-warnings: + +Additional warnings +------------------- + +Warnings will now be shown at ``do_package_qa`` time in the following +circumstances: + +- A recipe installs ``.desktop`` files containing ``MimeType`` keys but + does not inherit the new ``mime-xdg`` class + +- A recipe installs ``.xml`` files into ``${datadir}/mime/packages`` + but does not inherit the ``mime`` class + +.. _migration-3.1-x86-live-wic: + +``wic`` image type now used instead of ``live`` by default for x86 +------------------------------------------------------------------ + +``conf/machine/include/x86-base.inc`` (inherited by most x86 machine +configurations) now specifies ``wic`` instead of ``live`` by default in +:term:`IMAGE_FSTYPES`. The ``live`` image type will +likely be removed in a future release so it is recommended that you use +``wic`` instead. + +.. _migration-3.1-misc: + +Miscellaneous changes +--------------------- + +- The undocumented ``SRC_DISTRIBUTE_LICENSES`` variable has now been + removed in favour of a new ``AVAILABLE_LICENSES`` variable which is + dynamically set based upon license files found in + ``${COMMON_LICENSE_DIR}`` and ``${LICENSE_PATH}``. + +- The tune definition for big-endian microblaze machines is now + ``microblaze`` instead of ``microblazeeb``. + +- ``newlib`` no longer has built-in syscalls. ``libgloss`` should then + provide the syscalls, ``crt0.o`` and other functions that are no + longer part of ``newlib`` itself. If you are using + ``TCLIBC = "newlib"`` this now means that you must link applications + with both ``newlib`` and ``libgloss``, whereas before ``newlib`` + would run in many configurations by itself. diff --git a/poky/documentation/ref-manual/migration-general.rst b/poky/documentation/ref-manual/migration-general.rst new file mode 100644 index 000000000..182482ec4 --- /dev/null +++ b/poky/documentation/ref-manual/migration-general.rst @@ -0,0 +1,54 @@ +General Migration Considerations +================================ + +Some considerations are not tied to a specific Yocto Project release. +This section presents information you should consider when migrating to +any new Yocto Project release. + +- *Dealing with Customized Recipes*: + + Issues could arise if you take + older recipes that contain customizations and simply copy them + forward expecting them to work after you migrate to new Yocto Project + metadata. For example, suppose you have a recipe in your layer that + is a customized version of a core recipe copied from the earlier + release, rather than through the use of an append file. When you + migrate to a newer version of Yocto Project, the metadata (e.g. + perhaps an include file used by the recipe) could have changed in a + way that would break the build. Say, for example, a function is + removed from an include file and the customized recipe tries to call + that function. + + You could "forward-port" all your customizations in your recipe so + that everything works for the new release. However, this is not the + optimal solution as you would have to repeat this process with each + new release if changes occur that give rise to problems. + + The better solution (where practical) is to use append files + (``*.bbappend``) to capture any customizations you want to make to a + recipe. Doing so, isolates your changes from the main recipe making + them much more manageable. However, sometimes it is not practical to + use an append file. A good example of this is when introducing a + newer or older version of a recipe in another layer. + +- *Updating Append Files*: + + Since append files generally only contain + your customizations, they often do not need to be adjusted for new + releases. However, if the ``.bbappend`` file is specific to a + particular version of the recipe (i.e. its name does not use the % + wildcard) and the version of the recipe to which it is appending has + changed, then you will at a minimum need to rename the append file to + match the name of the recipe file. A mismatch between an append file + and its corresponding recipe file (``.bb``) will trigger an error + during parsing. + + Depending on the type of customization the append file applies, other + incompatibilities might occur when you upgrade. For example, if your + append file applies a patch and the recipe to which it is appending + is updated to a newer version, the patch might no longer apply. If + this is the case and assuming the patch is still needed, you must + modify the patch file so that it does apply. + + + diff --git a/poky/documentation/ref-manual/migration.rst b/poky/documentation/ref-manual/migration.rst new file mode 100644 index 000000000..6c6119dae --- /dev/null +++ b/poky/documentation/ref-manual/migration.rst @@ -0,0 +1,30 @@ +.. SPDX-License-Identifier: CC-BY-2.0-UK + +****************************************** +Migrating to a Newer Yocto Project Release +****************************************** + +This chapter provides information you can use to migrate work to a newer +Yocto Project release. You can find the same information in the release +notes for a given release. + +.. toctree:: + + migration-general + migration-1.3 + migration-1.4 + migration-1.5 + migration-1.6 + migration-1.7 + migration-1.8 + migration-2.0 + migration-2.1 + migration-2.2 + migration-2.3 + migration-2.4 + migration-2.5 + migration-2.6 + migration-2.7 + migration-3.0 + migration-3.1 + diff --git a/poky/documentation/ref-manual/migration.xml b/poky/documentation/ref-manual/migration.xml index affc8b90a..d3d5b16bd 100644 --- a/poky/documentation/ref-manual/migration.xml +++ b/poky/documentation/ref-manual/migration.xml @@ -1,6 +1,7 @@ <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > +<!--SPDX-License-Identifier: CC-BY-2.0-UK--> <chapter id='migration'> <title>Migrating to a Newer Yocto Project Release</title> diff --git a/poky/documentation/ref-manual/ref-classes.rst b/poky/documentation/ref-manual/ref-classes.rst new file mode 100644 index 000000000..b007e3482 --- /dev/null +++ b/poky/documentation/ref-manual/ref-classes.rst @@ -0,0 +1,2965 @@ +.. SPDX-License-Identifier: CC-BY-2.0-UK + +******* +Classes +******* + +Class files are used to abstract common functionality and share it +amongst multiple recipe (``.bb``) files. To use a class file, you simply +make sure the recipe inherits the class. In most cases, when a recipe +inherits a class it is enough to enable its features. There are cases, +however, where in the recipe you might need to set variables or override +some default behavior. + +Any :term:`Metadata` usually found in a recipe can also be +placed in a class file. Class files are identified by the extension +``.bbclass`` and are usually placed in a ``classes/`` directory beneath +the ``meta*/`` directory found in the :term:`Source Directory`. +Class files can also be pointed to by +:term:`BUILDDIR` (e.g. ``build/``) in the same way as +``.conf`` files in the ``conf`` directory. Class files are searched for +in :term:`BBPATH` using the same method by which ``.conf`` +files are searched. + +This chapter discusses only the most useful and important classes. Other +classes do exist within the ``meta/classes`` directory in the Source +Directory. You can reference the ``.bbclass`` files directly for more +information. + +.. _ref-classes-allarch: + +``allarch.bbclass`` +=================== + +The ``allarch`` class is inherited by recipes that do not produce +architecture-specific output. The class disables functionality that is +normally needed for recipes that produce executable binaries (such as +building the cross-compiler and a C library as pre-requisites, and +splitting out of debug symbols during packaging). + +.. note:: + + Unlike some distro recipes (e.g. Debian), OpenEmbedded recipes that + produce packages that depend on tunings through use of the + :term:`RDEPENDS` and + :term:`TUNE_PKGARCH` variables, should never be + configured for all architectures using ``allarch``. This is the case + even if the recipes do not produce architecture-specific output. + + Configuring such recipes for all architectures causes the + ```do_package_write_*`` tasks to + have different signatures for the machines with different tunings. + Additionally, unnecessary rebuilds occur every time an image for a + different ``MACHINE`` is built even when the recipe never changes. + +By default, all recipes inherit the :ref:`base <ref-classes-base>` and +:ref:`package <ref-classes-package>` classes, which enable +functionality needed for recipes that produce executable output. If your +recipe, for example, only produces packages that contain configuration +files, media files, or scripts (e.g. Python and Perl), then it should +inherit the ``allarch`` class. + +.. _ref-classes-archiver: + +``archiver.bbclass`` +==================== + +The ``archiver`` class supports releasing source code and other +materials with the binaries. + +For more details on the source archiver, see the +":ref:`dev-manual/dev-manual-common-tasks:maintaining open source license compliance during your product's lifecycle`" +section in the Yocto Project Development Tasks Manual. You can also see +the :term:`ARCHIVER_MODE` variable for information +about the variable flags (varflags) that help control archive creation. + +.. _ref-classes-autotools: + +``autotools*.bbclass`` +====================== + +The ``autotools*`` classes support Autotooled packages. + +The ``autoconf``, ``automake``, and ``libtool`` packages bring +standardization. This class defines a set of tasks (e.g. ``configure``, +``compile`` and so forth) that work for all Autotooled packages. It +should usually be enough to define a few standard variables and then +simply ``inherit autotools``. These classes can also work with software +that emulates Autotools. For more information, see the +":ref:`new-recipe-autotooled-package`" section +in the Yocto Project Development Tasks Manual. + +By default, the ``autotools*`` classes use out-of-tree builds (i.e. +``autotools.bbclass`` building with ``B != S``). + +If the software being built by a recipe does not support using +out-of-tree builds, you should have the recipe inherit the +``autotools-brokensep`` class. The ``autotools-brokensep`` class behaves +the same as the ``autotools`` class but builds with :term:`B` +== :term:`S`. This method is useful when out-of-tree build +support is either not present or is broken. + +.. note:: + + It is recommended that out-of-tree support be fixed and used if at + all possible. + +It's useful to have some idea of how the tasks defined by the +``autotools*`` classes work and what they do behind the scenes. + +- :ref:`ref-tasks-configure` - Regenerates the + configure script (using ``autoreconf``) and then launches it with a + standard set of arguments used during cross-compilation. You can pass + additional parameters to ``configure`` through the ``EXTRA_OECONF`` + or :term:`PACKAGECONFIG_CONFARGS` + variables. + +- :ref:`ref-tasks-compile` - Runs ``make`` with + arguments that specify the compiler and linker. You can pass + additional arguments through the ``EXTRA_OEMAKE`` variable. + +- :ref:`ref-tasks-install` - Runs ``make install`` and + passes in ``${``\ :term:`D`\ ``}`` as ``DESTDIR``. + +.. _ref-classes-base: + +``base.bbclass`` +================ + +The ``base`` class is special in that every ``.bb`` file implicitly +inherits the class. This class contains definitions for standard basic +tasks such as fetching, unpacking, configuring (empty by default), +compiling (runs any ``Makefile`` present), installing (empty by default) +and packaging (empty by default). These classes are often overridden or +extended by other classes such as the +:ref:`autotools <ref-classes-autotools>` class or the +:ref:`package <ref-classes-package>` class. + +The class also contains some commonly used functions such as +``oe_runmake``, which runs ``make`` with the arguments specified in +:term:`EXTRA_OEMAKE` variable as well as the +arguments passed directly to ``oe_runmake``. + +.. _ref-classes-bash-completion: + +``bash-completion.bbclass`` +=========================== + +Sets up packaging and dependencies appropriate for recipes that build +software that includes bash-completion data. + +.. _ref-classes-bin-package: + +``bin_package.bbclass`` +======================= + +The ``bin_package`` class is a helper class for recipes that extract the +contents of a binary package (e.g. an RPM) and install those contents +rather than building the binary from source. The binary package is +extracted and new packages in the configured output package format are +created. Extraction and installation of proprietary binaries is a good +example use for this class. + +.. note:: + + For RPMs and other packages that do not contain a subdirectory, you + should specify an appropriate fetcher parameter to point to the + subdirectory. For example, if BitBake is using the Git fetcher ( + git:// + ), the "subpath" parameter limits the checkout to a specific subpath + of the tree. Here is an example where + ${BP} + is used so that the files are extracted into the subdirectory + expected by the default value of + S + : + :: + + SRC_URI = "git://example.com/downloads/somepackage.rpm;subpath=${BP}" + + + See the " + Fetchers + " section in the BitBake User Manual for more information on + supported BitBake Fetchers. + +.. _ref-classes-binconfig: + +``binconfig.bbclass`` +===================== + +The ``binconfig`` class helps to correct paths in shell scripts. + +Before ``pkg-config`` had become widespread, libraries shipped shell +scripts to give information about the libraries and include paths needed +to build software (usually named ``LIBNAME-config``). This class assists +any recipe using such scripts. + +During staging, the OpenEmbedded build system installs such scripts into +the ``sysroots/`` directory. Inheriting this class results in all paths +in these scripts being changed to point into the ``sysroots/`` directory +so that all builds that use the script use the correct directories for +the cross compiling layout. See the +:term:`BINCONFIG_GLOB` variable for more +information. + +.. _ref-classes-binconfig-disabled: + +``binconfig-disabled.bbclass`` +============================== + +An alternative version of the :ref:`binconfig <ref-classes-binconfig>` +class, which disables binary configuration scripts by making them return +an error in favor of using ``pkg-config`` to query the information. The +scripts to be disabled should be specified using the +:term:`BINCONFIG` variable within the recipe inheriting +the class. + +.. _ref-classes-blacklist: + +``blacklist.bbclass`` +===================== + +The ``blacklist`` class prevents the OpenEmbedded build system from +building specific recipes (blacklists them). To use this class, inherit +the class globally and set :term:`PNBLACKLIST` for +each recipe you wish to blacklist. Specify the :term:`PN` +value as a variable flag (varflag) and provide a reason, which is +reported, if the package is requested to be built as the value. For +example, if you want to blacklist a recipe called "exoticware", you add +the following to your ``local.conf`` or distribution configuration: +:: + + INHERIT += "blacklist" + PNBLACKLIST[exoticware] = "Not supported by our organization." + +.. _ref-classes-buildhistory: + +``buildhistory.bbclass`` +======================== + +The ``buildhistory`` class records a history of build output metadata, +which can be used to detect possible regressions as well as used for +analysis of the build output. For more information on using Build +History, see the +":ref:`dev-manual/dev-manual-common-tasks:maintaining build output quality`" +section in the Yocto Project Development Tasks Manual. + +.. _ref-classes-buildstats: + +``buildstats.bbclass`` +====================== + +The ``buildstats`` class records performance statistics about each task +executed during the build (e.g. elapsed time, CPU usage, and I/O usage). + +When you use this class, the output goes into the +:term:`BUILDSTATS_BASE` directory, which defaults +to ``${TMPDIR}/buildstats/``. You can analyze the elapsed time using +``scripts/pybootchartgui/pybootchartgui.py``, which produces a cascading +chart of the entire build process and can be useful for highlighting +bottlenecks. + +Collecting build statistics is enabled by default through the +:term:`USER_CLASSES` variable from your +``local.conf`` file. Consequently, you do not have to do anything to +enable the class. However, if you want to disable the class, simply +remove "buildstats" from the ``USER_CLASSES`` list. + +.. _ref-classes-buildstats-summary: + +``buildstats-summary.bbclass`` +============================== + +When inherited globally, prints statistics at the end of the build on +sstate re-use. In order to function, this class requires the +:ref:`buildstats <ref-classes-buildstats>` class be enabled. + +.. _ref-classes-ccache: + +``ccache.bbclass`` +================== + +The ``ccache`` class enables the C/C++ Compiler Cache for the build. +This class is used to give a minor performance boost during the build. +However, using the class can lead to unexpected side-effects. Thus, it +is recommended that you do not use this class. See +http://ccache.samba.org/ for information on the C/C++ Compiler +Cache. + +.. _ref-classes-chrpath: + +``chrpath.bbclass`` +=================== + +The ``chrpath`` class is a wrapper around the "chrpath" utility, which +is used during the build process for ``nativesdk``, ``cross``, and +``cross-canadian`` recipes to change ``RPATH`` records within binaries +in order to make them relocatable. + +.. _ref-classes-clutter: + +``clutter.bbclass`` +=================== + +The ``clutter`` class consolidates the major and minor version naming +and other common items used by Clutter and related recipes. + +.. note:: + + Unlike some other classes related to specific libraries, recipes + building other software that uses Clutter do not need to inherit this + class unless they use the same recipe versioning scheme that the + Clutter and related recipes do. + +.. _ref-classes-cmake: + +``cmake.bbclass`` +================= + +The ``cmake`` class allows for recipes that need to build software using +the `CMake <https://cmake.org/overview/>`__ build system. You can use +the :term:`EXTRA_OECMAKE` variable to specify +additional configuration options to be passed using the ``cmake`` +command line. + +On the occasion that you would be installing custom CMake toolchain +files supplied by the application being built, you should install them +to the preferred CMake Module directory: ``${D}${datadir}/cmake/`` +Modules during +:ref:`ref-tasks-install`. + +.. _ref-classes-cml1: + +``cml1.bbclass`` +================ + +The ``cml1`` class provides basic support for the Linux kernel style +build configuration system. + +.. _ref-classes-compress_doc: + +``compress_doc.bbclass`` +======================== + +Enables compression for man pages and info pages. This class is intended +to be inherited globally. The default compression mechanism is gz (gzip) +but you can select an alternative mechanism by setting the +:term:`DOC_COMPRESS` variable. + +.. _ref-classes-copyleft_compliance: + +``copyleft_compliance.bbclass`` +=============================== + +The ``copyleft_compliance`` class preserves source code for the purposes +of license compliance. This class is an alternative to the ``archiver`` +class and is still used by some users even though it has been deprecated +in favor of the :ref:`archiver <ref-classes-archiver>` class. + +.. _ref-classes-copyleft_filter: + +``copyleft_filter.bbclass`` +=========================== + +A class used by the :ref:`archiver <ref-classes-archiver>` and +:ref:`copyleft_compliance <ref-classes-copyleft_compliance>` classes +for filtering licenses. The ``copyleft_filter`` class is an internal +class and is not intended to be used directly. + +.. _ref-classes-core-image: + +``core-image.bbclass`` +====================== + +The ``core-image`` class provides common definitions for the +``core-image-*`` image recipes, such as support for additional +:term:`IMAGE_FEATURES`. + +.. _ref-classes-cpan: + +``cpan*.bbclass`` +================= + +The ``cpan*`` classes support Perl modules. + +Recipes for Perl modules are simple. These recipes usually only need to +point to the source's archive and then inherit the proper class file. +Building is split into two methods depending on which method the module +authors used. + +- Modules that use old ``Makefile.PL``-based build system require + ``cpan.bbclass`` in their recipes. + +- Modules that use ``Build.PL``-based build system require using + ``cpan_build.bbclass`` in their recipes. + +Both build methods inherit the ``cpan-base`` class for basic Perl +support. + +.. _ref-classes-cross: + +``cross.bbclass`` +================= + +The ``cross`` class provides support for the recipes that build the +cross-compilation tools. + +.. _ref-classes-cross-canadian: + +``cross-canadian.bbclass`` +========================== + +The ``cross-canadian`` class provides support for the recipes that build +the Canadian Cross-compilation tools for SDKs. See the +":ref:`overview-manual/overview-manual-concepts:cross-development toolchain generation`" +section in the Yocto Project Overview and Concepts Manual for more +discussion on these cross-compilation tools. + +.. _ref-classes-crosssdk: + +``crosssdk.bbclass`` +==================== + +The ``crosssdk`` class provides support for the recipes that build the +cross-compilation tools used for building SDKs. See the +":ref:`overview-manual/overview-manual-concepts:cross-development toolchain generation`" +section in the Yocto Project Overview and Concepts Manual for more +discussion on these cross-compilation tools. + +.. _ref-classes-debian: + +``debian.bbclass`` +================== + +The ``debian`` class renames output packages so that they follow the +Debian naming policy (i.e. ``glibc`` becomes ``libc6`` and +``glibc-devel`` becomes ``libc6-dev``.) Renaming includes the library +name and version as part of the package name. + +If a recipe creates packages for multiple libraries (shared object files +of ``.so`` type), use the :term:`LEAD_SONAME` +variable in the recipe to specify the library on which to apply the +naming scheme. + +.. _ref-classes-deploy: + +``deploy.bbclass`` +================== + +The ``deploy`` class handles deploying files to the +:term:`DEPLOY_DIR_IMAGE` directory. The main +function of this class is to allow the deploy step to be accelerated by +shared state. Recipes that inherit this class should define their own +:ref:`ref-tasks-deploy` function to copy the files to be +deployed to :term:`DEPLOYDIR`, and use ``addtask`` to +add the task at the appropriate place, which is usually after +:ref:`ref-tasks-compile` or +:ref:`ref-tasks-install`. The class then takes care of +staging the files from ``DEPLOYDIR`` to ``DEPLOY_DIR_IMAGE``. + +.. _ref-classes-devshell: + +``devshell.bbclass`` +==================== + +The ``devshell`` class adds the ``do_devshell`` task. Distribution +policy dictates whether to include this class. See the ":ref:`platdev-appdev-devshell`" +section in the Yocto Project Development Tasks Manual for more +information about using ``devshell``. + +.. _ref-classes-devupstream: + +``devupstream.bbclass`` +======================= + +The ``devupstream`` class uses +:term:`BBCLASSEXTEND` to add a variant of the +recipe that fetches from an alternative URI (e.g. Git) instead of a +tarball. Following is an example: +:: + + BBCLASSEXTEND = "devupstream:target" + SRC_URI_class-devupstream = "git://git.example.com/example" + SRCREV_class-devupstream = "abcd1234" + +Adding the above statements to your recipe creates a variant that has +:term:`DEFAULT_PREFERENCE` set to "-1". +Consequently, you need to select the variant of the recipe to use it. +Any development-specific adjustments can be done by using the +``class-devupstream`` override. Here is an example: +:: + + DEPENDS_append_class-devupstream = " gperf-native" + do_configure_prepend_class-devupstream() { + touch ${S}/README + } + +The class +currently only supports creating a development variant of the target +recipe, not ``native`` or ``nativesdk`` variants. + +The ``BBCLASSEXTEND`` syntax (i.e. ``devupstream:target``) provides +support for ``native`` and ``nativesdk`` variants. Consequently, this +functionality can be added in a future release. + +Support for other version control systems such as Subversion is limited +due to BitBake's automatic fetch dependencies (e.g. +``subversion-native``). + +.. _ref-classes-distro_features_check: + +``distro_features_check.bbclass`` +================================= + +The ``distro_features_check`` class allows individual recipes to check +for required and conflicting +:term:`DISTRO_FEATURES`. + +This class provides support for the +:term:`REQUIRED_DISTRO_FEATURES` and +:term:`CONFLICT_DISTRO_FEATURES` +variables. If any conditions specified in the recipe using the above +variables are not met, the recipe will be skipped. + +.. _ref-classes-distutils: + +``distutils*.bbclass`` +====================== + +The ``distutils*`` classes support recipes for Python version 2.x +extensions, which are simple. These recipes usually only need to point +to the source's archive and then inherit the proper class. Building is +split into two methods depending on which method the module authors +used. + +- Extensions that use an Autotools-based build system require Autotools + and the classes based on ``distutils`` in their recipes. + +- Extensions that use build systems based on ``distutils`` require the + ``distutils`` class in their recipes. + +- Extensions that use build systems based on ``setuptools`` require the + :ref:`setuptools <ref-classes-setuptools>` class in their recipes. + +The ``distutils-common-base`` class is required by some of the +``distutils*`` classes to provide common Python2 support. + +.. _ref-classes-distutils3: + +``distutils3*.bbclass`` +======================= + +The ``distutils3*`` classes support recipes for Python version 3.x +extensions, which are simple. These recipes usually only need to point +to the source's archive and then inherit the proper class. Building is +split into three methods depending on which method the module authors +used. + +- Extensions that use an Autotools-based build system require Autotools + and ``distutils``-based classes in their recipes. + +- Extensions that use ``distutils``-based build systems require the + ``distutils`` class in their recipes. + +- Extensions that use build systems based on ``setuptools3`` require + the :ref:`setuptools3 <ref-classes-setuptools>` class in their + recipes. + +The ``distutils3*`` classes either inherit their corresponding +``distutils*`` class or replicate them using a Python3 version instead +(e.g. ``distutils3-base`` inherits ``distutils-common-base``, which is +the same as ``distutils-base`` but inherits ``python3native`` instead of +``pythonnative``). + +.. _ref-classes-externalsrc: + +``externalsrc.bbclass`` +======================= + +The ``externalsrc`` class supports building software from source code +that is external to the OpenEmbedded build system. Building software +from an external source tree means that the build system's normal fetch, +unpack, and patch process is not used. + +By default, the OpenEmbedded build system uses the :term:`S` +and :term:`B` variables to locate unpacked recipe source code +and to build it, respectively. When your recipe inherits the +``externalsrc`` class, you use the +:term:`EXTERNALSRC` and +:term:`EXTERNALSRC_BUILD` variables to +ultimately define ``S`` and ``B``. + +By default, this class expects the source code to support recipe builds +that use the :term:`B` variable to point to the directory in +which the OpenEmbedded build system places the generated objects built +from the recipes. By default, the ``B`` directory is set to the +following, which is separate from the source directory (``S``): +:: + + ${WORKDIR}/${BPN}/{PV}/ + +See these variables for more information: +:term:`WORKDIR`, :term:`BPN`, and +:term:`PV`, + +For more information on the ``externalsrc`` class, see the comments in +``meta/classes/externalsrc.bbclass`` in the :term:`Source Directory`. +For information on how to use the +``externalsrc`` class, see the +":ref:`dev-manual/dev-manual-common-tasks:building software from an external source`" +section in the Yocto Project Development Tasks Manual. + +.. _ref-classes-extrausers: + +``extrausers.bbclass`` +====================== + +The ``extrausers`` class allows additional user and group configuration +to be applied at the image level. Inheriting this class either globally +or from an image recipe allows additional user and group operations to +be performed using the +:term:`EXTRA_USERS_PARAMS` variable. + +.. note:: + + The user and group operations added using the + extrausers + class are not tied to a specific recipe outside of the recipe for the + image. Thus, the operations can be performed across the image as a + whole. Use the + useradd + class to add user and group configuration to a specific recipe. + +Here is an example that uses this class in an image recipe: +:: + + inherit extrausers + EXTRA_USERS_PARAMS = "\ + useradd -p '' tester; \ + groupadd developers; \ + userdel nobody; \ + groupdel -g video; \ + groupmod -g 1020 developers; \ + usermod -s /bin/sh tester; \ + " + +Here is an example that adds two users named "tester-jim" and "tester-sue" and assigns +passwords: +:: + + inherit extrausers + EXTRA_USERS_PARAMS = "\ + useradd -P tester01 tester-jim; \ + useradd -P tester01 tester-sue; \ + " + +Finally, here is an example that sets the root password to "1876*18": +:: + + inherit extrausers + EXTRA_USERS_PARAMS = "\ + usermod -P 1876*18 root; \ + " + +.. _ref-classes-fontcache: + +``fontcache.bbclass`` +===================== + +The ``fontcache`` class generates the proper post-install and +post-remove (postinst and postrm) scriptlets for font packages. These +scriptlets call ``fc-cache`` (part of ``Fontconfig``) to add the fonts +to the font information cache. Since the cache files are +architecture-specific, ``fc-cache`` runs using QEMU if the postinst +scriptlets need to be run on the build host during image creation. + +If the fonts being installed are in packages other than the main +package, set :term:`FONT_PACKAGES` to specify the +packages containing the fonts. + +.. _ref-classes-fs-uuid: + +``fs-uuid.bbclass`` +=================== + +The ``fs-uuid`` class extracts UUID from +``${``\ :term:`ROOTFS`\ ``}``, which must have been built +by the time that this function gets called. The ``fs-uuid`` class only +works on ``ext`` file systems and depends on ``tune2fs``. + +.. _ref-classes-gconf: + +``gconf.bbclass`` +================= + +The ``gconf`` class provides common functionality for recipes that need +to install GConf schemas. The schemas will be put into a separate +package (``${``\ :term:`PN`\ ``}-gconf``) that is created +automatically when this class is inherited. This package uses the +appropriate post-install and post-remove (postinst/postrm) scriptlets to +register and unregister the schemas in the target image. + +.. _ref-classes-gettext: + +``gettext.bbclass`` +=================== + +The ``gettext`` class provides support for building software that uses +the GNU ``gettext`` internationalization and localization system. All +recipes building software that use ``gettext`` should inherit this +class. + +.. _ref-classes-gnomebase: + +``gnomebase.bbclass`` +===================== + +The ``gnomebase`` class is the base class for recipes that build +software from the GNOME stack. This class sets +:term:`SRC_URI` to download the source from the GNOME +mirrors as well as extending :term:`FILES` with the typical +GNOME installation paths. + +.. _ref-classes-gobject-introspection: + +``gobject-introspection.bbclass`` +================================= + +Provides support for recipes building software that supports GObject +introspection. This functionality is only enabled if the +"gobject-introspection-data" feature is in +:term:`DISTRO_FEATURES` as well as +"qemu-usermode" being in +:term:`MACHINE_FEATURES`. + +.. note:: + + This functionality is backfilled by default and, if not applicable, + should be disabled through + DISTRO_FEATURES_BACKFILL_CONSIDERED + or + MACHINE_FEATURES_BACKFILL_CONSIDERED + , respectively. + +.. _ref-classes-grub-efi: + +``grub-efi.bbclass`` +==================== + +The ``grub-efi`` class provides ``grub-efi``-specific functions for +building bootable images. + +This class supports several variables: + +- :term:`INITRD`: Indicates list of filesystem images to + concatenate and use as an initial RAM disk (initrd) (optional). + +- :term:`ROOTFS`: Indicates a filesystem image to include + as the root filesystem (optional). + +- :term:`GRUB_GFXSERIAL`: Set this to "1" to have + graphics and serial in the boot menu. + +- :term:`LABELS`: A list of targets for the automatic + configuration. + +- :term:`APPEND`: An override list of append strings for + each ``LABEL``. + +- :term:`GRUB_OPTS`: Additional options to add to the + configuration (optional). Options are delimited using semi-colon + characters (``;``). + +- :term:`GRUB_TIMEOUT`: Timeout before executing + the default ``LABEL`` (optional). + +.. _ref-classes-gsettings: + +``gsettings.bbclass`` +===================== + +The ``gsettings`` class provides common functionality for recipes that +need to install GSettings (glib) schemas. The schemas are assumed to be +part of the main package. Appropriate post-install and post-remove +(postinst/postrm) scriptlets are added to register and unregister the +schemas in the target image. + +.. _ref-classes-gtk-doc: + +``gtk-doc.bbclass`` +=================== + +The ``gtk-doc`` class is a helper class to pull in the appropriate +``gtk-doc`` dependencies and disable ``gtk-doc``. + +.. _ref-classes-gtk-icon-cache: + +``gtk-icon-cache.bbclass`` +========================== + +The ``gtk-icon-cache`` class generates the proper post-install and +post-remove (postinst/postrm) scriptlets for packages that use GTK+ and +install icons. These scriptlets call ``gtk-update-icon-cache`` to add +the fonts to GTK+'s icon cache. Since the cache files are +architecture-specific, ``gtk-update-icon-cache`` is run using QEMU if +the postinst scriptlets need to be run on the build host during image +creation. + +.. _ref-classes-gtk-immodules-cache: + +``gtk-immodules-cache.bbclass`` +=============================== + +The ``gtk-immodules-cache`` class generates the proper post-install and +post-remove (postinst/postrm) scriptlets for packages that install GTK+ +input method modules for virtual keyboards. These scriptlets call +``gtk-update-icon-cache`` to add the input method modules to the cache. +Since the cache files are architecture-specific, +``gtk-update-icon-cache`` is run using QEMU if the postinst scriptlets +need to be run on the build host during image creation. + +If the input method modules being installed are in packages other than +the main package, set +:term:`GTKIMMODULES_PACKAGES` to specify +the packages containing the modules. + +.. _ref-classes-gzipnative: + +``gzipnative.bbclass`` +====================== + +The ``gzipnative`` class enables the use of different native versions of +``gzip`` and ``pigz`` rather than the versions of these tools from the +build host. + +.. _ref-classes-icecc: + +``icecc.bbclass`` +================= + +The ``icecc`` class supports +`Icecream <https://github.com/icecc/icecream>`__, which facilitates +taking compile jobs and distributing them among remote machines. + +The class stages directories with symlinks from ``gcc`` and ``g++`` to +``icecc``, for both native and cross compilers. Depending on each +configure or compile, the OpenEmbedded build system adds the directories +at the head of the ``PATH`` list and then sets the ``ICECC_CXX`` and +``ICEC_CC`` variables, which are the paths to the ``g++`` and ``gcc`` +compilers, respectively. + +For the cross compiler, the class creates a ``tar.gz`` file that +contains the Yocto Project toolchain and sets ``ICECC_VERSION``, which +is the version of the cross-compiler used in the cross-development +toolchain, accordingly. + +The class handles all three different compile stages (i.e native +,cross-kernel and target) and creates the necessary environment +``tar.gz`` file to be used by the remote machines. The class also +supports SDK generation. + +If :term:`ICECC_PATH` is not set in your +``local.conf`` file, then the class tries to locate the ``icecc`` binary +using ``which``. If :term:`ICECC_ENV_EXEC` is set +in your ``local.conf`` file, the variable should point to the +``icecc-create-env`` script provided by the user. If you do not point to +a user-provided script, the build system uses the default script +provided by the recipe ``icecc-create-env-native.bb``. + +.. note:: + + This script is a modified version and not the one that comes with + icecc. + +If you do not want the Icecream distributed compile support to apply to +specific recipes or classes, you can effectively "blacklist" them by +listing the recipes and classes using the +:term:`ICECC_USER_PACKAGE_BL` and +:term:`ICECC_USER_CLASS_BL`, variables, +respectively, in your ``local.conf`` file. Doing so causes the +OpenEmbedded build system to handle these compilations locally. + +Additionally, you can list recipes using the +:term:`ICECC_USER_PACKAGE_WL` variable in +your ``local.conf`` file to force ``icecc`` to be enabled for recipes +using an empty :term:`PARALLEL_MAKE` variable. + +Inheriting the ``icecc`` class changes all sstate signatures. +Consequently, if a development team has a dedicated build system that +populates :term:`SSTATE_MIRRORS` and they want to +reuse sstate from ``SSTATE_MIRRORS``, then all developers and the build +system need to either inherit the ``icecc`` class or nobody should. + +At the distribution level, you can inherit the ``icecc`` class to be +sure that all builders start with the same sstate signatures. After +inheriting the class, you can then disable the feature by setting the +:term:`ICECC_DISABLED` variable to "1" as follows: +:: + + INHERIT_DISTRO_append = " icecc" + ICECC_DISABLED ??= "1" + +This practice +makes sure everyone is using the same signatures but also requires +individuals that do want to use Icecream to enable the feature +individually as follows in your ``local.conf`` file: +:: + + ICECC_DISABLED = "" + +.. _ref-classes-image: + +``image.bbclass`` +================= + +The ``image`` class helps support creating images in different formats. +First, the root filesystem is created from packages using one of the +``rootfs*.bbclass`` files (depending on the package format used) and +then one or more image files are created. + +- The ``IMAGE_FSTYPES`` variable controls the types of images to + generate. + +- The ``IMAGE_INSTALL`` variable controls the list of packages to + install into the image. + +For information on customizing images, see the +":ref:`usingpoky-extend-customimage`" section +in the Yocto Project Development Tasks Manual. For information on how +images are created, see the +":ref:`images-dev-environment`" section in the +Yocto Project Overview and Concpets Manual. + +.. _ref-classes-image-buildinfo: + +``image-buildinfo.bbclass`` +=========================== + +The ``image-buildinfo`` class writes information to the target +filesystem on ``/etc/build``. + +.. _ref-classes-image_types: + +``image_types.bbclass`` +======================= + +The ``image_types`` class defines all of the standard image output types +that you can enable through the +:term:`IMAGE_FSTYPES` variable. You can use this +class as a reference on how to add support for custom image output +types. + +By default, the :ref:`image <ref-classes-image>` class automatically +enables the ``image_types`` class. The ``image`` class uses the +``IMGCLASSES`` variable as follows: +:: + + IMGCLASSES = "rootfs_${IMAGE_PKGTYPE} image_types ${IMAGE_CLASSES}" + IMGCLASSES += "${@['populate_sdk_base', 'populate_sdk_ext']['linux' in d.getVar("SDK_OS")]}" + IMGCLASSES += "${@bb.utils.contains_any('IMAGE_FSTYPES', 'live iso hddimg', 'image-live', '', d)}" + IMGCLASSES += "${@bb.utils.contains('IMAGE_FSTYPES', 'container', 'image-container', '', d)}" + IMGCLASSES += "image_types_wic" + IMGCLASSES += "rootfs-postcommands" + IMGCLASSES += "image-postinst-intercepts" + inherit ${IMGCLASSES} + +The ``image_types`` class also handles conversion and compression of images. + +.. note:: + + To build a VMware VMDK image, you need to add "wic.vmdk" to + IMAGE_FSTYPES + . This would also be similar for Virtual Box Virtual Disk Image + ("vdi") and QEMU Copy On Write Version 2 ("qcow2") images. + +.. _ref-classes-image-live: + +``image-live.bbclass`` +====================== + +This class controls building "live" (i.e. HDDIMG and ISO) images. Live +images contain syslinux for legacy booting, as well as the bootloader +specified by :term:`EFI_PROVIDER` if +:term:`MACHINE_FEATURES` contains "efi". + +Normally, you do not use this class directly. Instead, you add "live" to +:term:`IMAGE_FSTYPES`. + +.. _ref-classes-image-mklibs: + +``image-mklibs.bbclass`` +======================== + +The ``image-mklibs`` class enables the use of the ``mklibs`` utility +during the :ref:`ref-tasks-rootfs` task, which optimizes +the size of libraries contained in the image. + +By default, the class is enabled in the ``local.conf.template`` using +the :term:`USER_CLASSES` variable as follows: +:: + + USER_CLASSES ?= "buildstats image-mklibs image-prelink" + +.. _ref-classes-image-prelink: + +``image-prelink.bbclass`` +========================= + +The ``image-prelink`` class enables the use of the ``prelink`` utility +during the :ref:`ref-tasks-rootfs` task, which optimizes +the dynamic linking of shared libraries to reduce executable startup +time. + +By default, the class is enabled in the ``local.conf.template`` using +the :term:`USER_CLASSES` variable as follows: +:: + + USER_CLASSES ?= "buildstats image-mklibs image-prelink" + +.. _ref-classes-insane: + +``insane.bbclass`` +================== + +The ``insane`` class adds a step to the package generation process so +that output quality assurance checks are generated by the OpenEmbedded +build system. A range of checks are performed that check the build's +output for common problems that show up during runtime. Distribution +policy usually dictates whether to include this class. + +You can configure the sanity checks so that specific test failures +either raise a warning or an error message. Typically, failures for new +tests generate a warning. Subsequent failures for the same test would +then generate an error message once the metadata is in a known and good +condition. See the "`QA Error and Warning Messages <#ref-qa-checks>`__" +Chapter for a list of all the warning and error messages you might +encounter using a default configuration. + +Use the :term:`WARN_QA` and +:term:`ERROR_QA` variables to control the behavior of +these checks at the global level (i.e. in your custom distro +configuration). However, to skip one or more checks in recipes, you +should use :term:`INSANE_SKIP`. For example, to skip +the check for symbolic link ``.so`` files in the main package of a +recipe, add the following to the recipe. You need to realize that the +package name override, in this example ``${PN}``, must be used: +:: + + INSANE_SKIP_${PN} += "dev-so" + +Please keep in mind that the QA checks +exist in order to detect real or potential problems in the packaged +output. So exercise caution when disabling these checks. + +The following list shows the tests you can list with the ``WARN_QA`` and +``ERROR_QA`` variables: + +- ``already-stripped:`` Checks that produced binaries have not + already been stripped prior to the build system extracting debug + symbols. It is common for upstream software projects to default to + stripping debug symbols for output binaries. In order for debugging + to work on the target using ``-dbg`` packages, this stripping must be + disabled. + +- ``arch:`` Checks the Executable and Linkable Format (ELF) type, bit + size, and endianness of any binaries to ensure they match the target + architecture. This test fails if any binaries do not match the type + since there would be an incompatibility. The test could indicate that + the wrong compiler or compiler options have been used. Sometimes + software, like bootloaders, might need to bypass this check. + +- ``buildpaths:`` Checks for paths to locations on the build host + inside the output files. Currently, this test triggers too many false + positives and thus is not normally enabled. + +- ``build-deps:`` Determines if a build-time dependency that is + specified through :term:`DEPENDS`, explicit + :term:`RDEPENDS`, or task-level dependencies exists + to match any runtime dependency. This determination is particularly + useful to discover where runtime dependencies are detected and added + during packaging. If no explicit dependency has been specified within + the metadata, at the packaging stage it is too late to ensure that + the dependency is built, and thus you can end up with an error when + the package is installed into the image during the + :ref:`ref-tasks-rootfs` task because the auto-detected + dependency was not satisfied. An example of this would be where the + :ref:`update-rc.d <ref-classes-update-rc.d>` class automatically + adds a dependency on the ``initscripts-functions`` package to + packages that install an initscript that refers to + ``/etc/init.d/functions``. The recipe should really have an explicit + ``RDEPENDS`` for the package in question on ``initscripts-functions`` + so that the OpenEmbedded build system is able to ensure that the + ``initscripts`` recipe is actually built and thus the + ``initscripts-functions`` package is made available. + +- ``compile-host-path:`` Checks the + :ref:`ref-tasks-compile` log for indications that + paths to locations on the build host were used. Using such paths + might result in host contamination of the build output. + +- ``debug-deps:`` Checks that all packages except ``-dbg`` packages + do not depend on ``-dbg`` packages, which would cause a packaging + bug. + +- ``debug-files:`` Checks for ``.debug`` directories in anything but + the ``-dbg`` package. The debug files should all be in the ``-dbg`` + package. Thus, anything packaged elsewhere is incorrect packaging. + +- ``dep-cmp:`` Checks for invalid version comparison statements in + runtime dependency relationships between packages (i.e. in + :term:`RDEPENDS`, + :term:`RRECOMMENDS`, + :term:`RSUGGESTS`, + :term:`RPROVIDES`, + :term:`RREPLACES`, and + :term:`RCONFLICTS` variable values). Any invalid + comparisons might trigger failures or undesirable behavior when + passed to the package manager. + +- ``desktop:`` Runs the ``desktop-file-validate`` program against any + ``.desktop`` files to validate their contents against the + specification for ``.desktop`` files. + +- ``dev-deps:`` Checks that all packages except ``-dev`` or + ``-staticdev`` packages do not depend on ``-dev`` packages, which + would be a packaging bug. + +- ``dev-so:`` Checks that the ``.so`` symbolic links are in the + ``-dev`` package and not in any of the other packages. In general, + these symlinks are only useful for development purposes. Thus, the + ``-dev`` package is the correct location for them. Some very rare + cases do exist for dynamically loaded modules where these symlinks + are needed instead in the main package. + +- ``file-rdeps:`` Checks that file-level dependencies identified by + the OpenEmbedded build system at packaging time are satisfied. For + example, a shell script might start with the line ``#!/bin/bash``. + This line would translate to a file dependency on ``/bin/bash``. Of + the three package managers that the OpenEmbedded build system + supports, only RPM directly handles file-level dependencies, + resolving them automatically to packages providing the files. + However, the lack of that functionality in the other two package + managers does not mean the dependencies do not still need resolving. + This QA check attempts to ensure that explicitly declared + :term:`RDEPENDS` exist to handle any file-level + dependency detected in packaged files. + +- ``files-invalid:`` Checks for :term:`FILES` variable + values that contain "//", which is invalid. + +- ``host-user-contaminated:`` Checks that no package produced by the + recipe contains any files outside of ``/home`` with a user or group + ID that matches the user running BitBake. A match usually indicates + that the files are being installed with an incorrect UID/GID, since + target IDs are independent from host IDs. For additional information, + see the section describing the + :ref:`ref-tasks-install` task. + +- ``incompatible-license:`` Report when packages are excluded from + being created due to being marked with a license that is in + :term:`INCOMPATIBLE_LICENSE`. + +- ``install-host-path:`` Checks the + :ref:`ref-tasks-install` log for indications that + paths to locations on the build host were used. Using such paths + might result in host contamination of the build output. + +- ``installed-vs-shipped:`` Reports when files have been installed + within ``do_install`` but have not been included in any package by + way of the :term:`FILES` variable. Files that do not + appear in any package cannot be present in an image later on in the + build process. Ideally, all installed files should be packaged or not + installed at all. These files can be deleted at the end of + ``do_install`` if the files are not needed in any package. + +- ``invalid-chars:`` Checks that the recipe metadata variables + :term:`DESCRIPTION`, + :term:`SUMMARY`, :term:`LICENSE`, and + :term:`SECTION` do not contain non-UTF-8 characters. + Some package managers do not support such characters. + +- ``invalid-packageconfig:`` Checks that no undefined features are + being added to :term:`PACKAGECONFIG`. For + example, any name "foo" for which the following form does not exist: + :: + + PACKAGECONFIG[foo] = "..." + +- ``la:`` Checks ``.la`` files for any ``TMPDIR`` paths. Any ``.la`` + file containing these paths is incorrect since ``libtool`` adds the + correct sysroot prefix when using the files automatically itself. + +- ``ldflags:`` Ensures that the binaries were linked with the + :term:`LDFLAGS` options provided by the build system. + If this test fails, check that the ``LDFLAGS`` variable is being + passed to the linker command. + +- ``libdir:`` Checks for libraries being installed into incorrect + (possibly hardcoded) installation paths. For example, this test will + catch recipes that install ``/lib/bar.so`` when ``${base_libdir}`` is + "lib32". Another example is when recipes install + ``/usr/lib64/foo.so`` when ``${libdir}`` is "/usr/lib". + +- ``libexec:`` Checks if a package contains files in + ``/usr/libexec``. This check is not performed if the ``libexecdir`` + variable has been set explicitly to ``/usr/libexec``. + +- ``packages-list:`` Checks for the same package being listed + multiple times through the :term:`PACKAGES` variable + value. Installing the package in this manner can cause errors during + packaging. + +- ``perm-config:`` Reports lines in ``fs-perms.txt`` that have an + invalid format. + +- ``perm-line:`` Reports lines in ``fs-perms.txt`` that have an + invalid format. + +- ``perm-link:`` Reports lines in ``fs-perms.txt`` that specify + 'link' where the specified target already exists. + +- ``perms:`` Currently, this check is unused but reserved. + +- ``pkgconfig:`` Checks ``.pc`` files for any + :term:`TMPDIR`/:term:`WORKDIR` paths. + Any ``.pc`` file containing these paths is incorrect since + ``pkg-config`` itself adds the correct sysroot prefix when the files + are accessed. + +- ``pkgname:`` Checks that all packages in + :term:`PACKAGES` have names that do not contain + invalid characters (i.e. characters other than 0-9, a-z, ., +, and + -). + +- ``pkgv-undefined:`` Checks to see if the ``PKGV`` variable is + undefined during :ref:`ref-tasks-package`. + +- ``pkgvarcheck:`` Checks through the variables + :term:`RDEPENDS`, + :term:`RRECOMMENDS`, + :term:`RSUGGESTS`, + :term:`RCONFLICTS`, + :term:`RPROVIDES`, + :term:`RREPLACES`, :term:`FILES`, + :term:`ALLOW_EMPTY`, ``pkg_preinst``, + ``pkg_postinst``, ``pkg_prerm`` and ``pkg_postrm``, and reports if + there are variable sets that are not package-specific. Using these + variables without a package suffix is bad practice, and might + unnecessarily complicate dependencies of other packages within the + same recipe or have other unintended consequences. + +- ``pn-overrides:`` Checks that a recipe does not have a name + (:term:`PN`) value that appears in + :term:`OVERRIDES`. If a recipe is named such that + its ``PN`` value matches something already in ``OVERRIDES`` (e.g. + ``PN`` happens to be the same as :term:`MACHINE` or + :term:`DISTRO`), it can have unexpected consequences. + For example, assignments such as ``FILES_${PN} = "xyz"`` effectively + turn into ``FILES = "xyz"``. + +- ``rpaths:`` Checks for rpaths in the binaries that contain build + system paths such as ``TMPDIR``. If this test fails, bad ``-rpath`` + options are being passed to the linker commands and your binaries + have potential security issues. + +- ``split-strip:`` Reports that splitting or stripping debug symbols + from binaries has failed. + +- ``staticdev:`` Checks for static library files (``*.a``) in + non-``staticdev`` packages. + +- ``symlink-to-sysroot:`` Checks for symlinks in packages that point + into :term:`TMPDIR` on the host. Such symlinks will + work on the host, but are clearly invalid when running on the target. + +- ``textrel:`` Checks for ELF binaries that contain relocations in + their ``.text`` sections, which can result in a performance impact at + runtime. See the explanation for the + ```ELF binary`` <#qa-issue-textrel>`__ message for more information + regarding runtime performance issues. + +- ``unlisted-pkg-lics:`` Checks that all declared licenses applying + for a package are also declared on the recipe level (i.e. any license + in ``LICENSE_*`` should appear in :term:`LICENSE`). + +- ``useless-rpaths:`` Checks for dynamic library load paths (rpaths) + in the binaries that by default on a standard system are searched by + the linker (e.g. ``/lib`` and ``/usr/lib``). While these paths will + not cause any breakage, they do waste space and are unnecessary. + +- ``var-undefined:`` Reports when variables fundamental to packaging + (i.e. :term:`WORKDIR`, + :term:`DEPLOY_DIR`, :term:`D`, + :term:`PN`, and :term:`PKGD`) are undefined + during :ref:`ref-tasks-package`. + +- ``version-going-backwards:`` If Build History is enabled, reports + when a package being written out has a lower version than the + previously written package under the same name. If you are placing + output packages into a feed and upgrading packages on a target system + using that feed, the version of a package going backwards can result + in the target system not correctly upgrading to the "new" version of + the package. + + .. note:: + + If you are not using runtime package management on your target + system, then you do not need to worry about this situation. + +- ``xorg-driver-abi:`` Checks that all packages containing Xorg + drivers have ABI dependencies. The ``xserver-xorg`` recipe provides + driver ABI names. All drivers should depend on the ABI versions that + they have been built against. Driver recipes that include + ``xorg-driver-input.inc`` or ``xorg-driver-video.inc`` will + automatically get these versions. Consequently, you should only need + to explicitly add dependencies to binary driver recipes. + +.. _ref-classes-insserv: + +``insserv.bbclass`` +=================== + +The ``insserv`` class uses the ``insserv`` utility to update the order +of symbolic links in ``/etc/rc?.d/`` within an image based on +dependencies specified by LSB headers in the ``init.d`` scripts +themselves. + +.. _ref-classes-kernel: + +``kernel.bbclass`` +================== + +The ``kernel`` class handles building Linux kernels. The class contains +code to build all kernel trees. All needed headers are staged into the +``STAGING_KERNEL_DIR`` directory to allow out-of-tree module builds +using the :ref:`module <ref-classes-module>` class. + +This means that each built kernel module is packaged separately and +inter-module dependencies are created by parsing the ``modinfo`` output. +If all modules are required, then installing the ``kernel-modules`` +package installs all packages with modules and various other kernel +packages such as ``kernel-vmlinux``. + +The ``kernel`` class contains logic that allows you to embed an initial +RAM filesystem (initramfs) image when you build the kernel image. For +information on how to build an initramfs, see the +":ref:`building-an-initramfs-image`" section in +the Yocto Project Development Tasks Manual. + +Various other classes are used by the ``kernel`` and ``module`` classes +internally including the :ref:`kernel-arch <ref-classes-kernel-arch>`, +:ref:`module-base <ref-classes-module-base>`, and +:ref:`linux-kernel-base <ref-classes-linux-kernel-base>` classes. + +.. _ref-classes-kernel-arch: + +``kernel-arch.bbclass`` +======================= + +The ``kernel-arch`` class sets the ``ARCH`` environment variable for +Linux kernel compilation (including modules). + +.. _ref-classes-kernel-devicetree: + +``kernel-devicetree.bbclass`` +============================= + +The ``kernel-devicetree`` class, which is inherited by the +:ref:`kernel <ref-classes-kernel>` class, supports device tree +generation. + +.. _ref-classes-kernel-fitimage: + +``kernel-fitimage.bbclass`` +=========================== + +The ``kernel-fitimage`` class provides support to pack a kernel Image, +device trees and a RAM disk into a single FIT image. In theory, a FIT +image can support any number of kernels, RAM disks and device-trees. +However, ``kernel-fitimage`` currently only supports +limited usescases: just one kernel image, an optional RAM disk, and +any number of device tree. + +To create a FIT image, it is required that :term:`KERNEL_CLASSES` +is set to "kernel-fitimage" and :term:`KERNEL_IMAGETYPE` +is set to "fitImage". + +The options for the device tree compiler passed to mkimage -D feature +when creating the FIT image are specified using the +:term:`UBOOT_MKIMAGE_DTCOPTS` variable. + +Only a single kernel can be added to the FIT image created by +``kernel-fitimage`` and the kernel image in FIT is mandatory. The +address where the kernel image is to be loaded by U-boot is +specified by :term:`UBOOT_LOADADDRESS` and the entrypoint by +:term:`UBOOT_ENTRYPOINT`. + +Multiple device trees can be added to the FIT image created by +``kernel-fitimage`` and the device tree is optional. +The address where the device tree is to be loaded by U-boot is +specified by :term:`UBOOT_DTBO_LOADADDRESS` for device tree overlays +and by `:term:`UBOOT_DTB_LOADADDRESS` for device tree binaries. + +Only a single RAM disk can be added to the FIT image created by +``kernel-fitimage`` and the RAM disk in FIT is optional. +The address where the RAM disk image is to be loaded by U-boot +is specified by :term:`UBOOT_RD_LOADADDRESS` and the entrypoint by +:term:`UBOOT_RD_ENTRYPOINT`. The ramdisk is added to FIT image when +:term:`INITRAMFS_IMAGE` is specified. + +The FIT image generated by ``kernel-fitimage`` class is signed when the +variables :term:`UBOOT_SIGN_ENABLE`, :term:`UBOOT_MKIMAGE_DTCOPTS`, +:term:`UBOOT_SIGN_KEYDIR` and :term:`UBOOT_SIGN_KEYNAME` are set +appropriately. The default values used for :term:`FIT_HASH_ALG` and +:term:`FIT_SIGN_ALG` in ``kernel-fitimage`` are "sha256" and +"rsa2048" respectively. The keys for signing fitImage can be generated using +the ``kernel-fitimage`` class when both :term:`FIT_GENERATE_KEYS` and +:term:`UBOOT_SIGN_ENABLE` are set to "1". + + +.. _ref-classes-kernel-grub: + +``kernel-grub.bbclass`` +======================= + +The ``kernel-grub`` class updates the boot area and the boot menu with +the kernel as the priority boot mechanism while installing a RPM to +update the kernel on a deployed target. + +.. _ref-classes-kernel-module-split: + +``kernel-module-split.bbclass`` +=============================== + +The ``kernel-module-split`` class provides common functionality for +splitting Linux kernel modules into separate packages. + +.. _ref-classes-kernel-uboot: + +``kernel-uboot.bbclass`` +======================== + +The ``kernel-uboot`` class provides support for building from +vmlinux-style kernel sources. + +.. _ref-classes-kernel-uimage: + +``kernel-uimage.bbclass`` +========================= + +The ``kernel-uimage`` class provides support to pack uImage. + +.. _ref-classes-kernel-yocto: + +``kernel-yocto.bbclass`` +======================== + +The ``kernel-yocto`` class provides common functionality for building +from linux-yocto style kernel source repositories. + +.. _ref-classes-kernelsrc: + +``kernelsrc.bbclass`` +===================== + +The ``kernelsrc`` class sets the Linux kernel source and version. + +.. _ref-classes-lib_package: + +``lib_package.bbclass`` +======================= + +The ``lib_package`` class supports recipes that build libraries and +produce executable binaries, where those binaries should not be +installed by default along with the library. Instead, the binaries are +added to a separate ``${``\ :term:`PN`\ ``}-bin`` package to +make their installation optional. + +.. _ref-classes-libc*: + +``libc*.bbclass`` +================= + +The ``libc*`` classes support recipes that build packages with ``libc``: + +- The ``libc-common`` class provides common support for building with + ``libc``. + +- The ``libc-package`` class supports packaging up ``glibc`` and + ``eglibc``. + +.. _ref-classes-license: + +``license.bbclass`` +=================== + +The ``license`` class provides license manifest creation and license +exclusion. This class is enabled by default using the default value for +the :term:`INHERIT_DISTRO` variable. + +.. _ref-classes-linux-kernel-base: + +``linux-kernel-base.bbclass`` +============================= + +The ``linux-kernel-base`` class provides common functionality for +recipes that build out of the Linux kernel source tree. These builds +goes beyond the kernel itself. For example, the Perf recipe also +inherits this class. + +.. _ref-classes-linuxloader: + +``linuxloader.bbclass`` +======================= + +Provides the function ``linuxloader()``, which gives the value of the +dynamic loader/linker provided on the platform. This value is used by a +number of other classes. + +.. _ref-classes-logging: + +``logging.bbclass`` +=================== + +The ``logging`` class provides the standard shell functions used to log +messages for various BitBake severity levels (i.e. ``bbplain``, +``bbnote``, ``bbwarn``, ``bberror``, ``bbfatal``, and ``bbdebug``). + +This class is enabled by default since it is inherited by the ``base`` +class. + +.. _ref-classes-meta: + +``meta.bbclass`` +================ + +The ``meta`` class is inherited by recipes that do not build any output +packages themselves, but act as a "meta" target for building other +recipes. + +.. _ref-classes-metadata_scm: + +``metadata_scm.bbclass`` +======================== + +The ``metadata_scm`` class provides functionality for querying the +branch and revision of a Source Code Manager (SCM) repository. + +The :ref:`base <ref-classes-base>` class uses this class to print the +revisions of each layer before starting every build. The +``metadata_scm`` class is enabled by default because it is inherited by +the ``base`` class. + +.. _ref-classes-migrate_localcount: + +``migrate_localcount.bbclass`` +============================== + +The ``migrate_localcount`` class verifies a recipe's localcount data and +increments it appropriately. + +.. _ref-classes-mime: + +``mime.bbclass`` +================ + +The ``mime`` class generates the proper post-install and post-remove +(postinst/postrm) scriptlets for packages that install MIME type files. +These scriptlets call ``update-mime-database`` to add the MIME types to +the shared database. + +.. _ref-classes-mirrors: + +``mirrors.bbclass`` +=================== + +The ``mirrors`` class sets up some standard +:term:`MIRRORS` entries for source code mirrors. These +mirrors provide a fall-back path in case the upstream source specified +in :term:`SRC_URI` within recipes is unavailable. + +This class is enabled by default since it is inherited by the +:ref:`base <ref-classes-base>` class. + +.. _ref-classes-module: + +``module.bbclass`` +================== + +The ``module`` class provides support for building out-of-tree Linux +kernel modules. The class inherits the +:ref:`module-base <ref-classes-module-base>` and +:ref:`kernel-module-split <ref-classes-kernel-module-split>` classes, +and implements the :ref:`ref-tasks-compile` and +:ref:`ref-tasks-install` tasks. The class provides +everything needed to build and package a kernel module. + +For general information on out-of-tree Linux kernel modules, see the +":ref:`kernel-dev/kernel-dev-common:incorporating out-of-tree modules`" +section in the Yocto Project Linux Kernel Development Manual. + +.. _ref-classes-module-base: + +``module-base.bbclass`` +======================= + +The ``module-base`` class provides the base functionality for building +Linux kernel modules. Typically, a recipe that builds software that +includes one or more kernel modules and has its own means of building +the module inherits this class as opposed to inheriting the +:ref:`module <ref-classes-module>` class. + +.. _ref-classes-multilib*: + +``multilib*.bbclass`` +===================== + +The ``multilib*`` classes provide support for building libraries with +different target optimizations or target architectures and installing +them side-by-side in the same image. + +For more information on using the Multilib feature, see the +":ref:`combining-multiple-versions-library-files-into-one-image`" +section in the Yocto Project Development Tasks Manual. + +.. _ref-classes-native: + +``native.bbclass`` +================== + +The ``native`` class provides common functionality for recipes that +build tools to run on the `build host <#hardware-build-system-term>`__ +(i.e. tools that use the compiler or other tools from the build host). + +You can create a recipe that builds tools that run natively on the host +a couple different ways: + +- Create a myrecipe\ ``-native.bb`` recipe that inherits the ``native`` + class. If you use this method, you must order the inherit statement + in the recipe after all other inherit statements so that the + ``native`` class is inherited last. + + .. note:: + + When creating a recipe this way, the recipe name must follow this + naming convention: + :: + + myrecipe-native.bb + + + Not using this naming convention can lead to subtle problems + caused by existing code that depends on that naming convention. + +- Create or modify a target recipe that contains the following: + :: + + BBCLASSEXTEND = "native" + + Inside the + recipe, use ``_class-native`` and ``_class-target`` overrides to + specify any functionality specific to the respective native or target + case. + +Although applied differently, the ``native`` class is used with both +methods. The advantage of the second method is that you do not need to +have two separate recipes (assuming you need both) for native and +target. All common parts of the recipe are automatically shared. + +.. _ref-classes-nativesdk: + +``nativesdk.bbclass`` +===================== + +The ``nativesdk`` class provides common functionality for recipes that +wish to build tools to run as part of an SDK (i.e. tools that run on +:term:`SDKMACHINE`). + +You can create a recipe that builds tools that run on the SDK machine a +couple different ways: + +- Create a ``nativesdk-``\ myrecipe\ ``.bb`` recipe that inherits the + ``nativesdk`` class. If you use this method, you must order the + inherit statement in the recipe after all other inherit statements so + that the ``nativesdk`` class is inherited last. + +- Create a ``nativesdk`` variant of any recipe by adding the following: + :: + + BBCLASSEXTEND = "nativesdk" + + Inside the + recipe, use ``_class-nativesdk`` and ``_class-target`` overrides to + specify any functionality specific to the respective SDK machine or + target case. + +.. note:: + + When creating a recipe, you must follow this naming convention: + :: + + nativesdk-myrecipe.bb + + + Not doing so can lead to subtle problems because code exists that + depends on the naming convention. + +Although applied differently, the ``nativesdk`` class is used with both +methods. The advantage of the second method is that you do not need to +have two separate recipes (assuming you need both) for the SDK machine +and the target. All common parts of the recipe are automatically shared. + +.. _ref-classes-nopackages: + +``nopackages.bbclass`` +====================== + +Disables packaging tasks for those recipes and classes where packaging +is not needed. + +.. _ref-classes-npm: + +``npm.bbclass`` +=============== + +Provides support for building Node.js software fetched using the `node +package manager (NPM) <https://en.wikipedia.org/wiki/Npm_(software)>`__. + +.. note:: + + Currently, recipes inheriting this class must use the + npm:// + fetcher to have dependencies fetched and packaged automatically. + +For information on how to create NPM packages, see the +":ref:`dev-manual/dev-manual-common-tasks:creating node package manager (npm) packages`" +section in the Yocto Project Development Tasks Manual. + +.. _ref-classes-oelint: + +``oelint.bbclass`` +================== + +The ``oelint`` class is an obsolete lint checking tool that exists in +``meta/classes`` in the :term:`Source Directory`. + +A number of classes exist that could be generally useful in OE-Core but +are never actually used within OE-Core itself. The ``oelint`` class is +one such example. However, being aware of this class can reduce the +proliferation of different versions of similar classes across multiple +layers. + +.. _ref-classes-own-mirrors: + +``own-mirrors.bbclass`` +======================= + +The ``own-mirrors`` class makes it easier to set up your own +:term:`PREMIRRORS` from which to first fetch source +before attempting to fetch it from the upstream specified in +:term:`SRC_URI` within each recipe. + +To use this class, inherit it globally and specify +:term:`SOURCE_MIRROR_URL`. Here is an example: +:: + + INHERIT += "own-mirrors" + SOURCE_MIRROR_URL = "http://example.com/my-source-mirror" + +You can specify only a single URL +in ``SOURCE_MIRROR_URL``. + +.. _ref-classes-package: + +``package.bbclass`` +=================== + +The ``package`` class supports generating packages from a build's +output. The core generic functionality is in ``package.bbclass``. The +code specific to particular package types resides in these +package-specific classes: +:ref:`package_deb <ref-classes-package_deb>`, +:ref:`package_rpm <ref-classes-package_rpm>`, +:ref:`package_ipk <ref-classes-package_ipk>`, and +:ref:`package_tar <ref-classes-package_tar>`. + +.. note:: + + The + package_tar + class is broken and not supported. It is recommended that you do not + use this class. + +You can control the list of resulting package formats by using the +``PACKAGE_CLASSES`` variable defined in your ``conf/local.conf`` +configuration file, which is located in the :term:`Build Directory`. +When defining the variable, you can +specify one or more package types. Since images are generated from +packages, a packaging class is needed to enable image generation. The +first class listed in this variable is used for image generation. + +If you take the optional step to set up a repository (package feed) on +the development host that can be used by DNF, you can install packages +from the feed while you are running the image on the target (i.e. +runtime installation of packages). For more information, see the +":ref:`dev-manual/dev-manual-common-tasks:using runtime package management`" +section in the Yocto Project Development Tasks Manual. + +The package-specific class you choose can affect build-time performance +and has space ramifications. In general, building a package with IPK +takes about thirty percent less time as compared to using RPM to build +the same or similar package. This comparison takes into account a +complete build of the package with all dependencies previously built. +The reason for this discrepancy is because the RPM package manager +creates and processes more :term:`Metadata` than the IPK package +manager. Consequently, you might consider setting ``PACKAGE_CLASSES`` to +"package_ipk" if you are building smaller systems. + +Before making your package manager decision, however, you should +consider some further things about using RPM: + +- RPM starts to provide more abilities than IPK due to the fact that it + processes more Metadata. For example, this information includes + individual file types, file checksum generation and evaluation on + install, sparse file support, conflict detection and resolution for + Multilib systems, ACID style upgrade, and repackaging abilities for + rollbacks. + +- For smaller systems, the extra space used for the Berkeley Database + and the amount of metadata when using RPM can affect your ability to + perform on-device upgrades. + +You can find additional information on the effects of the package class +at these two Yocto Project mailing list links: + +- https://lists.yoctoproject.org/pipermail/poky/2011-May/006362.html + +- https://lists.yoctoproject.org/pipermail/poky/2011-May/006363.html + +.. _ref-classes-package_deb: + +``package_deb.bbclass`` +======================= + +The ``package_deb`` class provides support for creating packages that +use the Debian (i.e. ``.deb``) file format. The class ensures the +packages are written out in a ``.deb`` file format to the +``${``\ :term:`DEPLOY_DIR_DEB`\ ``}`` directory. + +This class inherits the :ref:`package <ref-classes-package>` class and +is enabled through the :term:`PACKAGE_CLASSES` +variable in the ``local.conf`` file. + +.. _ref-classes-package_ipk: + +``package_ipk.bbclass`` +======================= + +The ``package_ipk`` class provides support for creating packages that +use the IPK (i.e. ``.ipk``) file format. The class ensures the packages +are written out in a ``.ipk`` file format to the +``${``\ :term:`DEPLOY_DIR_IPK`\ ``}`` directory. + +This class inherits the :ref:`package <ref-classes-package>` class and +is enabled through the :term:`PACKAGE_CLASSES` +variable in the ``local.conf`` file. + +.. _ref-classes-package_rpm: + +``package_rpm.bbclass`` +======================= + +The ``package_rpm`` class provides support for creating packages that +use the RPM (i.e. ``.rpm``) file format. The class ensures the packages +are written out in a ``.rpm`` file format to the +``${``\ :term:`DEPLOY_DIR_RPM`\ ``}`` directory. + +This class inherits the :ref:`package <ref-classes-package>` class and +is enabled through the :term:`PACKAGE_CLASSES` +variable in the ``local.conf`` file. + +.. _ref-classes-package_tar: + +``package_tar.bbclass`` +======================= + +The ``package_tar`` class provides support for creating tarballs. The +class ensures the packages are written out in a tarball format to the +``${``\ :term:`DEPLOY_DIR_TAR`\ ``}`` directory. + +This class inherits the :ref:`package <ref-classes-package>` class and +is enabled through the :term:`PACKAGE_CLASSES` +variable in the ``local.conf`` file. + +.. note:: + + You cannot specify the + package_tar + class first using the + PACKAGE_CLASSES + variable. You must use + .deb + , + .ipk + , or + .rpm + file formats for your image or SDK. + +.. _ref-classes-packagedata: + +``packagedata.bbclass`` +======================= + +The ``packagedata`` class provides common functionality for reading +``pkgdata`` files found in :term:`PKGDATA_DIR`. These +files contain information about each output package produced by the +OpenEmbedded build system. + +This class is enabled by default because it is inherited by the +:ref:`package <ref-classes-package>` class. + +.. _ref-classes-packagegroup: + +``packagegroup.bbclass`` +======================== + +The ``packagegroup`` class sets default values appropriate for package +group recipes (e.g. ``PACKAGES``, ``PACKAGE_ARCH``, ``ALLOW_EMPTY``, and +so forth). It is highly recommended that all package group recipes +inherit this class. + +For information on how to use this class, see the +":ref:`usingpoky-extend-customimage-customtasks`" +section in the Yocto Project Development Tasks Manual. + +Previously, this class was called the ``task`` class. + +.. _ref-classes-patch: + +``patch.bbclass`` +================= + +The ``patch`` class provides all functionality for applying patches +during the :ref:`ref-tasks-patch` task. + +This class is enabled by default because it is inherited by the +:ref:`base <ref-classes-base>` class. + +.. _ref-classes-perlnative: + +``perlnative.bbclass`` +====================== + +When inherited by a recipe, the ``perlnative`` class supports using the +native version of Perl built by the build system rather than using the +version provided by the build host. + +.. _ref-classes-pixbufcache: + +``pixbufcache.bbclass`` +======================= + +The ``pixbufcache`` class generates the proper post-install and +post-remove (postinst/postrm) scriptlets for packages that install +pixbuf loaders, which are used with ``gdk-pixbuf``. These scriptlets +call ``update_pixbuf_cache`` to add the pixbuf loaders to the cache. +Since the cache files are architecture-specific, ``update_pixbuf_cache`` +is run using QEMU if the postinst scriptlets need to be run on the build +host during image creation. + +If the pixbuf loaders being installed are in packages other than the +recipe's main package, set +:term:`PIXBUF_PACKAGES` to specify the packages +containing the loaders. + +.. _ref-classes-pkgconfig: + +``pkgconfig.bbclass`` +===================== + +The ``pkgconfig`` class provides a standard way to get header and +library information by using ``pkg-config``. This class aims to smooth +integration of ``pkg-config`` into libraries that use it. + +During staging, BitBake installs ``pkg-config`` data into the +``sysroots/`` directory. By making use of sysroot functionality within +``pkg-config``, the ``pkgconfig`` class no longer has to manipulate the +files. + +.. _ref-classes-populate-sdk: + +``populate_sdk.bbclass`` +======================== + +The ``populate_sdk`` class provides support for SDK-only recipes. For +information on advantages gained when building a cross-development +toolchain using the :ref:`ref-tasks-populate_sdk` +task, see the ":ref:`sdk-manual/sdk-appendix-obtain:building an sdk installer`" +section in the Yocto Project Application Development and the Extensible +Software Development Kit (eSDK) manual. + +.. _ref-classes-populate-sdk-*: + +``populate_sdk_*.bbclass`` +========================== + +The ``populate_sdk_*`` classes support SDK creation and consist of the +following classes: + +- ``populate_sdk_base``: The base class supporting SDK creation under + all package managers (i.e. DEB, RPM, and opkg). + +- ``populate_sdk_deb``: Supports creation of the SDK given the Debian + package manager. + +- ``populate_sdk_rpm``: Supports creation of the SDK given the RPM + package manager. + +- ``populate_sdk_ipk``: Supports creation of the SDK given the opkg + (IPK format) package manager. + +- ``populate_sdk_ext``: Supports extensible SDK creation under all + package managers. + +The ``populate_sdk_base`` class inherits the appropriate +``populate_sdk_*`` (i.e. ``deb``, ``rpm``, and ``ipk``) based on +:term:`IMAGE_PKGTYPE`. + +The base class ensures all source and destination directories are +established and then populates the SDK. After populating the SDK, the +``populate_sdk_base`` class constructs two sysroots: +``${``\ :term:`SDK_ARCH`\ ``}-nativesdk``, which +contains the cross-compiler and associated tooling, and the target, +which contains a target root filesystem that is configured for the SDK +usage. These two images reside in :term:`SDK_OUTPUT`, +which consists of the following: +:: + + ${SDK_OUTPUT}/${SDK_ARCH}-nativesdk-pkgs + ${SDK_OUTPUT}/${SDKTARGETSYSROOT}/target-pkgs + +Finally, the base populate SDK class creates the toolchain environment +setup script, the tarball of the SDK, and the installer. + +The respective ``populate_sdk_deb``, ``populate_sdk_rpm``, and +``populate_sdk_ipk`` classes each support the specific type of SDK. +These classes are inherited by and used with the ``populate_sdk_base`` +class. + +For more information on the cross-development toolchain generation, see +the ":ref:`overview-manual/overview-manual-concepts:cross-development toolchain generation`" +section in the Yocto Project Overview and Concepts Manual. For +information on advantages gained when building a cross-development +toolchain using the :ref:`ref-tasks-populate_sdk` +task, see the +":ref:`sdk-manual/sdk-appendix-obtain:building an sdk installer`" +section in the Yocto Project Application Development and the Extensible +Software Development Kit (eSDK) manual. + +.. _ref-classes-prexport: + +``prexport.bbclass`` +==================== + +The ``prexport`` class provides functionality for exporting +:term:`PR` values. + +.. note:: + + This class is not intended to be used directly. Rather, it is enabled + when using " + bitbake-prserv-tool export + ". + +.. _ref-classes-primport: + +``primport.bbclass`` +==================== + +The ``primport`` class provides functionality for importing +:term:`PR` values. + +.. note:: + + This class is not intended to be used directly. Rather, it is enabled + when using " + bitbake-prserv-tool import + ". + +.. _ref-classes-prserv: + +``prserv.bbclass`` +================== + +The ``prserv`` class provides functionality for using a :ref:`PR +service <dev-manual/dev-manual-common-tasks:working with a pr service>` in order to +automatically manage the incrementing of the :term:`PR` +variable for each recipe. + +This class is enabled by default because it is inherited by the +:ref:`package <ref-classes-package>` class. However, the OpenEmbedded +build system will not enable the functionality of this class unless +:term:`PRSERV_HOST` has been set. + +.. _ref-classes-ptest: + +``ptest.bbclass`` +================= + +The ``ptest`` class provides functionality for packaging and installing +runtime tests for recipes that build software that provides these tests. + +This class is intended to be inherited by individual recipes. However, +the class' functionality is largely disabled unless "ptest" appears in +:term:`DISTRO_FEATURES`. See the +":ref:`dev-manual/dev-manual-common-tasks:testing packages with ptest`" +section in the Yocto Project Development Tasks Manual for more information +on ptest. + +.. _ref-classes-ptest-gnome: + +``ptest-gnome.bbclass`` +======================= + +Enables package tests (ptests) specifically for GNOME packages, which +have tests intended to be executed with ``gnome-desktop-testing``. + +For information on setting up and running ptests, see the +":ref:`dev-manual/dev-manual-common-tasks:testing packages with ptest`" +section in the Yocto Project Development Tasks Manual. + +.. _ref-classes-python-dir: + +``python-dir.bbclass`` +====================== + +The ``python-dir`` class provides the base version, location, and site +package location for Python. + +.. _ref-classes-python3native: + +``python3native.bbclass`` +========================= + +The ``python3native`` class supports using the native version of Python +3 built by the build system rather than support of the version provided +by the build host. + +.. _ref-classes-pythonnative: + +``pythonnative.bbclass`` +======================== + +When inherited by a recipe, the ``pythonnative`` class supports using +the native version of Python built by the build system rather than using +the version provided by the build host. + +.. _ref-classes-qemu: + +``qemu.bbclass`` +================ + +The ``qemu`` class provides functionality for recipes that either need +QEMU or test for the existence of QEMU. Typically, this class is used to +run programs for a target system on the build host using QEMU's +application emulation mode. + +.. _ref-classes-recipe_sanity: + +``recipe_sanity.bbclass`` +========================= + +The ``recipe_sanity`` class checks for the presence of any host system +recipe prerequisites that might affect the build (e.g. variables that +are set or software that is present). + +.. _ref-classes-relocatable: + +``relocatable.bbclass`` +======================= + +The ``relocatable`` class enables relocation of binaries when they are +installed into the sysroot. + +This class makes use of the :ref:`chrpath <ref-classes-chrpath>` class +and is used by both the :ref:`cross <ref-classes-cross>` and +:ref:`native <ref-classes-native>` classes. + +.. _ref-classes-remove-libtool: + +``remove-libtool.bbclass`` +========================== + +The ``remove-libtool`` class adds a post function to the +:ref:`ref-tasks-install` task to remove all ``.la`` files +installed by ``libtool``. Removing these files results in them being +absent from both the sysroot and target packages. + +If a recipe needs the ``.la`` files to be installed, then the recipe can +override the removal by setting ``REMOVE_LIBTOOL_LA`` to "0" as follows: +:: + + REMOVE_LIBTOOL_LA = "0" + +.. note:: + + The + remove-libtool + class is not enabled by default. + +.. _ref-classes-report-error: + +``report-error.bbclass`` +======================== + +The ``report-error`` class supports enabling the :ref:`error reporting +tool <dev-manual/dev-manual-common-tasks:using the error reporting tool>`", +which allows you to submit build error information to a central database. + +The class collects debug information for recipe, recipe version, task, +machine, distro, build system, target system, host distro, branch, +commit, and log. From the information, report files using a JSON format +are created and stored in +``${``\ :term:`LOG_DIR`\ ``}/error-report``. + +.. _ref-classes-rm-work: + +``rm_work.bbclass`` +=================== + +The ``rm_work`` class supports deletion of temporary workspace, which +can ease your hard drive demands during builds. + +The OpenEmbedded build system can use a substantial amount of disk space +during the build process. A portion of this space is the work files +under the ``${TMPDIR}/work`` directory for each recipe. Once the build +system generates the packages for a recipe, the work files for that +recipe are no longer needed. However, by default, the build system +preserves these files for inspection and possible debugging purposes. If +you would rather have these files deleted to save disk space as the +build progresses, you can enable ``rm_work`` by adding the following to +your ``local.conf`` file, which is found in the :term:`Build Directory`. +:: + + INHERIT += "rm_work" + +If you are +modifying and building source code out of the work directory for a +recipe, enabling ``rm_work`` will potentially result in your changes to +the source being lost. To exclude some recipes from having their work +directories deleted by ``rm_work``, you can add the names of the recipe +or recipes you are working on to the ``RM_WORK_EXCLUDE`` variable, which +can also be set in your ``local.conf`` file. Here is an example: +:: + + RM_WORK_EXCLUDE += "busybox glibc" + +.. _ref-classes-rootfs*: + +``rootfs*.bbclass`` +=================== + +The ``rootfs*`` classes support creating the root filesystem for an +image and consist of the following classes: + +- The ``rootfs-postcommands`` class, which defines filesystem + post-processing functions for image recipes. + +- The ``rootfs_deb`` class, which supports creation of root filesystems + for images built using ``.deb`` packages. + +- The ``rootfs_rpm`` class, which supports creation of root filesystems + for images built using ``.rpm`` packages. + +- The ``rootfs_ipk`` class, which supports creation of root filesystems + for images built using ``.ipk`` packages. + +- The ``rootfsdebugfiles`` class, which installs additional files found + on the build host directly into the root filesystem. + +The root filesystem is created from packages using one of the +``rootfs*.bbclass`` files as determined by the +:term:`PACKAGE_CLASSES` variable. + +For information on how root filesystem images are created, see the +:ref:`image-generation-dev-environment`" +section in the Yocto Project Overview and Concepts Manual. + +.. _ref-classes-sanity: + +``sanity.bbclass`` +================== + +The ``sanity`` class checks to see if prerequisite software is present +on the host system so that users can be notified of potential problems +that might affect their build. The class also performs basic user +configuration checks from the ``local.conf`` configuration file to +prevent common mistakes that cause build failures. Distribution policy +usually determines whether to include this class. + +.. _ref-classes-scons: + +``scons.bbclass`` +================= + +The ``scons`` class supports recipes that need to build software that +uses the SCons build system. You can use the +:term:`EXTRA_OESCONS` variable to specify +additional configuration options you want to pass SCons command line. + +.. _ref-classes-sdl: + +``sdl.bbclass`` +=============== + +The ``sdl`` class supports recipes that need to build software that uses +the Simple DirectMedia Layer (SDL) library. + +.. _ref-classes-setuptools: + +``setuptools.bbclass`` +====================== + +The ``setuptools`` class supports Python version 2.x extensions that use +build systems based on ``setuptools``. If your recipe uses these build +systems, the recipe needs to inherit the ``setuptools`` class. + +.. _ref-classes-setuptools3: + +``setuptools3.bbclass`` +======================= + +The ``setuptools3`` class supports Python version 3.x extensions that +use build systems based on ``setuptools3``. If your recipe uses these +build systems, the recipe needs to inherit the ``setuptools3`` class. + +.. _ref-classes-sign_rpm: + +``sign_rpm.bbclass`` +==================== + +The ``sign_rpm`` class supports generating signed RPM packages. + +.. _ref-classes-sip: + +``sip.bbclass`` +=============== + +The ``sip`` class supports recipes that build or package SIP-based +Python bindings. + +.. _ref-classes-siteconfig: + +``siteconfig.bbclass`` +====================== + +The ``siteconfig`` class provides functionality for handling site +configuration. The class is used by the +:ref:`autotools <ref-classes-autotools>` class to accelerate the +:ref:`ref-tasks-configure` task. + +.. _ref-classes-siteinfo: + +``siteinfo.bbclass`` +==================== + +The ``siteinfo`` class provides information about the targets that might +be needed by other classes or recipes. + +As an example, consider Autotools, which can require tests that must +execute on the target hardware. Since this is not possible in general +when cross compiling, site information is used to provide cached test +results so these tests can be skipped over but still make the correct +values available. The ``meta/site directory`` contains test results +sorted into different categories such as architecture, endianness, and +the ``libc`` used. Site information provides a list of files containing +data relevant to the current build in the ``CONFIG_SITE`` variable that +Autotools automatically picks up. + +The class also provides variables like ``SITEINFO_ENDIANNESS`` and +``SITEINFO_BITS`` that can be used elsewhere in the metadata. + +.. _ref-classes-spdx: + +``spdx.bbclass`` +================ + +The ``spdx`` class integrates real-time license scanning, generation of +SPDX standard output, and verification of license information during the +build. + +.. note:: + + This class is currently at the prototype stage in the 1.6 release. + +.. _ref-classes-sstate: + +``sstate.bbclass`` +================== + +The ``sstate`` class provides support for Shared State (sstate). By +default, the class is enabled through the +:term:`INHERIT_DISTRO` variable's default value. + +For more information on sstate, see the +":ref:`overview-manual/overview-manual-concepts:shared state cache`" +section in the Yocto Project Overview and Concepts Manual. + +.. _ref-classes-staging: + +``staging.bbclass`` +=================== + +The ``staging`` class installs files into individual recipe work +directories for sysroots. The class contains the following key tasks: + +- The :ref:`ref-tasks-populate_sysroot` task, + which is responsible for handing the files that end up in the recipe + sysroots. + +- The + :ref:`ref-tasks-prepare_recipe_sysroot` + task (a "partner" task to the ``populate_sysroot`` task), which + installs the files into the individual recipe work directories (i.e. + :term:`WORKDIR`). + +The code in the ``staging`` class is complex and basically works in two +stages: + +- *Stage One:* The first stage addresses recipes that have files they + want to share with other recipes that have dependencies on the + originating recipe. Normally these dependencies are installed through + the :ref:`ref-tasks-install` task into + ``${``\ :term:`D`\ ``}``. The ``do_populate_sysroot`` task + copies a subset of these files into ``${SYSROOT_DESTDIR}``. This + subset of files is controlled by the + :term:`SYSROOT_DIRS`, + :term:`SYSROOT_DIRS_NATIVE`, and + :term:`SYSROOT_DIRS_BLACKLIST` + variables. + + .. note:: + + Additionally, a recipe can customize the files further by + declaring a processing function in the + SYSROOT_PREPROCESS_FUNCS + variable. + + A shared state (sstate) object is built from these files and the + files are placed into a subdirectory of + ```tmp/sysroots-components/`` <#structure-build-tmp-sysroots-components>`__. + The files are scanned for hardcoded paths to the original + installation location. If the location is found in text files, the + hardcoded locations are replaced by tokens and a list of the files + needing such replacements is created. These adjustments are referred + to as "FIXMEs". The list of files that are scanned for paths is + controlled by the :term:`SSTATE_SCAN_FILES` + variable. + +- *Stage Two:* The second stage addresses recipes that want to use + something from another recipe and declare a dependency on that recipe + through the :term:`DEPENDS` variable. The recipe will + have a + :ref:`ref-tasks-prepare_recipe_sysroot` + task and when this task executes, it creates the ``recipe-sysroot`` + and ``recipe-sysroot-native`` in the recipe work directory (i.e. + :term:`WORKDIR`). The OpenEmbedded build system + creates hard links to copies of the relevant files from + ``sysroots-components`` into the recipe work directory. + + .. note:: + + If hard links are not possible, the build system uses actual + copies. + + The build system then addresses any "FIXMEs" to paths as defined from + the list created in the first stage. + + Finally, any files in ``${bindir}`` within the sysroot that have the + prefix "``postinst-``" are executed. + + .. note:: + + Although such sysroot post installation scripts are not + recommended for general use, the files do allow some issues such + as user creation and module indexes to be addressed. + + Because recipes can have other dependencies outside of ``DEPENDS`` + (e.g. ``do_unpack[depends] += "tar-native:do_populate_sysroot"``), + the sysroot creation function ``extend_recipe_sysroot`` is also added + as a pre-function for those tasks whose dependencies are not through + ``DEPENDS`` but operate similarly. + + When installing dependencies into the sysroot, the code traverses the + dependency graph and processes dependencies in exactly the same way + as the dependencies would or would not be when installed from sstate. + This processing means, for example, a native tool would have its + native dependencies added but a target library would not have its + dependencies traversed or installed. The same sstate dependency code + is used so that builds should be identical regardless of whether + sstate was used or not. For a closer look, see the + ``setscene_depvalid()`` function in the + :ref:`sstate <ref-classes-sstate>` class. + + The build system is careful to maintain manifests of the files it + installs so that any given dependency can be installed as needed. The + sstate hash of the installed item is also stored so that if it + changes, the build system can reinstall it. + +.. _ref-classes-syslinux: + +``syslinux.bbclass`` +==================== + +The ``syslinux`` class provides syslinux-specific functions for building +bootable images. + +The class supports the following variables: + +- :term:`INITRD`: Indicates list of filesystem images to + concatenate and use as an initial RAM disk (initrd). This variable is + optional. + +- :term:`ROOTFS`: Indicates a filesystem image to include + as the root filesystem. This variable is optional. + +- :term:`AUTO_SYSLINUXMENU`: Enables creating + an automatic menu when set to "1". + +- :term:`LABELS`: Lists targets for automatic + configuration. + +- :term:`APPEND`: Lists append string overrides for each + label. + +- :term:`SYSLINUX_OPTS`: Lists additional options + to add to the syslinux file. Semicolon characters separate multiple + options. + +- :term:`SYSLINUX_SPLASH`: Lists a background + for the VGA boot menu when you are using the boot menu. + +- :term:`SYSLINUX_DEFAULT_CONSOLE`: Set + to "console=ttyX" to change kernel boot default console. + +- :term:`SYSLINUX_SERIAL`: Sets an alternate + serial port. Or, turns off serial when the variable is set with an + empty string. + +- :term:`SYSLINUX_SERIAL_TTY`: Sets an + alternate "console=tty..." kernel boot argument. + +.. _ref-classes-systemd: + +``systemd.bbclass`` +=================== + +The ``systemd`` class provides support for recipes that install systemd +unit files. + +The functionality for this class is disabled unless you have "systemd" +in :term:`DISTRO_FEATURES`. + +Under this class, the recipe or Makefile (i.e. whatever the recipe is +calling during the :ref:`ref-tasks-install` task) +installs unit files into +``${``\ :term:`D`\ ``}${systemd_unitdir}/system``. If the unit +files being installed go into packages other than the main package, you +need to set :term:`SYSTEMD_PACKAGES` in your +recipe to identify the packages in which the files will be installed. + +You should set :term:`SYSTEMD_SERVICE` to the +name of the service file. You should also use a package name override to +indicate the package to which the value applies. If the value applies to +the recipe's main package, use ``${``\ :term:`PN`\ ``}``. Here +is an example from the connman recipe: +:: + + SYSTEMD_SERVICE_${PN} = "connman.service" + +Services are set up to start on boot automatically +unless you have set +:term:`SYSTEMD_AUTO_ENABLE` to "disable". + +For more information on ``systemd``, see the +":ref:`dev-manual/dev-manual-common-tasks:selecting an initialization manager`" +section in the Yocto Project Development Tasks Manual. + +.. _ref-classes-systemd-boot: + +``systemd-boot.bbclass`` +======================== + +The ``systemd-boot`` class provides functions specific to the +systemd-boot bootloader for building bootable images. This is an +internal class and is not intended to be used directly. + +.. note:: + + The + systemd-boot + class is a result from merging the + gummiboot + class used in previous Yocto Project releases with the + systemd + project. + +Set the :term:`EFI_PROVIDER` variable to +"systemd-boot" to use this class. Doing so creates a standalone EFI +bootloader that is not dependent on systemd. + +For information on more variables used and supported in this class, see +the :term:`SYSTEMD_BOOT_CFG`, +:term:`SYSTEMD_BOOT_ENTRIES`, and +:term:`SYSTEMD_BOOT_TIMEOUT` variables. + +You can also see the `Systemd-boot +documentation <http://www.freedesktop.org/wiki/Software/systemd/systemd-boot/>`__ +for more information. + +.. _ref-classes-terminal: + +``terminal.bbclass`` +==================== + +The ``terminal`` class provides support for starting a terminal session. +The :term:`OE_TERMINAL` variable controls which +terminal emulator is used for the session. + +Other classes use the ``terminal`` class anywhere a separate terminal +session needs to be started. For example, the +:ref:`patch <ref-classes-patch>` class assuming +:term:`PATCHRESOLVE` is set to "user", the +:ref:`cml1 <ref-classes-cml1>` class, and the +:ref:`devshell <ref-classes-devshell>` class all use the ``terminal`` +class. + +.. _ref-classes-testimage*: + +``testimage*.bbclass`` +====================== + +The ``testimage*`` classes support running automated tests against +images using QEMU and on actual hardware. The classes handle loading the +tests and starting the image. To use the classes, you need to perform +steps to set up the environment. + +.. note:: + + Best practices include using + IMAGE_CLASSES + rather than + INHERIT + to inherit the + testimage + class for automated image testing. + +The tests are commands that run on the target system over ``ssh``. Each +test is written in Python and makes use of the ``unittest`` module. + +The ``testimage.bbclass`` runs tests on an image when called using the +following: +:: + + $ bitbake -c testimage image + +The ``testimage-auto`` class +runs tests on an image after the image is constructed (i.e. +:term:`TESTIMAGE_AUTO` must be set to "1"). + +For information on how to enable, run, and create new tests, see the +":ref:`dev-manual/dev-manual-common-tasks:performing automated runtime testing`" +section in the Yocto Project Development Tasks Manual. + +.. _ref-classes-testsdk: + +``testsdk.bbclass`` +=================== + +This class supports running automated tests against software development +kits (SDKs). The ``testsdk`` class runs tests on an SDK when called +using the following: +:: + + $ bitbake -c testsdk image + +.. note:: + + Best practices include using + IMAGE_CLASSES + rather than + INHERIT + to inherit the + testsdk + class for automated SDK testing. + +.. _ref-classes-texinfo: + +``texinfo.bbclass`` +=================== + +This class should be inherited by recipes whose upstream packages invoke +the ``texinfo`` utilities at build-time. Native and cross recipes are +made to use the dummy scripts provided by ``texinfo-dummy-native``, for +improved performance. Target architecture recipes use the genuine +Texinfo utilities. By default, they use the Texinfo utilities on the +host system. + +.. note:: + + If you want to use the Texinfo recipe shipped with the build system, + you can remove "texinfo-native" from + ASSUME_PROVIDED + and makeinfo from + SANITY_REQUIRED_UTILITIES + . + +.. _ref-classes-tinderclient: + +``tinderclient.bbclass`` +======================== + +The ``tinderclient`` class submits build results to an external +Tinderbox instance. + +.. note:: + + This class is currently unmaintained. + +.. _ref-classes-toaster: + +``toaster.bbclass`` +=================== + +The ``toaster`` class collects information about packages and images and +sends them as events that the BitBake user interface can receive. The +class is enabled when the Toaster user interface is running. + +This class is not intended to be used directly. + +.. _ref-classes-toolchain-scripts: + +``toolchain-scripts.bbclass`` +============================= + +The ``toolchain-scripts`` class provides the scripts used for setting up +the environment for installed SDKs. + +.. _ref-classes-typecheck: + +``typecheck.bbclass`` +===================== + +The ``typecheck`` class provides support for validating the values of +variables set at the configuration level against their defined types. +The OpenEmbedded build system allows you to define the type of a +variable using the "type" varflag. Here is an example: +:: + + IMAGE_FEATURES[type] = "list" + +.. _ref-classes-uboot-config: + +``uboot-config.bbclass`` +======================== + +The ``uboot-config`` class provides support for U-Boot configuration for +a machine. Specify the machine in your recipe as follows: +:: + + UBOOT_CONFIG ??= <default> + UBOOT_CONFIG[foo] = "config,images" + +You can also specify the machine using this method: +:: + + UBOOT_MACHINE = "config" + +See the :term:`UBOOT_CONFIG` and :term:`UBOOT_MACHINE` variables for additional +information. + +.. _ref-classes-uninative: + +``uninative.bbclass`` +===================== + +Attempts to isolate the build system from the host distribution's C +library in order to make re-use of native shared state artifacts across +different host distributions practical. With this class enabled, a +tarball containing a pre-built C library is downloaded at the start of +the build. In the Poky reference distribution this is enabled by default +through ``meta/conf/distro/include/yocto-uninative.inc``. Other +distributions that do not derive from poky can also +"``require conf/distro/include/yocto-uninative.inc``" to use this. +Alternatively if you prefer, you can build the uninative-tarball recipe +yourself, publish the resulting tarball (e.g. via HTTP) and set +``UNINATIVE_URL`` and ``UNINATIVE_CHECKSUM`` appropriately. For an +example, see the ``meta/conf/distro/include/yocto-uninative.inc``. + +The ``uninative`` class is also used unconditionally by the extensible +SDK. When building the extensible SDK, ``uninative-tarball`` is built +and the resulting tarball is included within the SDK. + +.. _ref-classes-update-alternatives: + +``update-alternatives.bbclass`` +=============================== + +The ``update-alternatives`` class helps the alternatives system when +multiple sources provide the same command. This situation occurs when +several programs that have the same or similar function are installed +with the same name. For example, the ``ar`` command is available from +the ``busybox``, ``binutils`` and ``elfutils`` packages. The +``update-alternatives`` class handles renaming the binaries so that +multiple packages can be installed without conflicts. The ``ar`` command +still works regardless of which packages are installed or subsequently +removed. The class renames the conflicting binary in each package and +symlinks the highest priority binary during installation or removal of +packages. + +To use this class, you need to define a number of variables: + +- :term:`ALTERNATIVE` + +- :term:`ALTERNATIVE_LINK_NAME` + +- :term:`ALTERNATIVE_TARGET` + +- :term:`ALTERNATIVE_PRIORITY` + +These variables list alternative commands needed by a package, provide +pathnames for links, default links for targets, and so forth. For +details on how to use this class, see the comments in the +:yocto_git:`update-alternatives.bbclass </cgit/cgit.cgi/poky/tree/meta/classes/update-alternatives.bbclass>` +file. + +.. note:: + + You can use the + update-alternatives + command directly in your recipes. However, this class simplifies + things in most cases. + +.. _ref-classes-update-rc.d: + +``update-rc.d.bbclass`` +======================= + +The ``update-rc.d`` class uses ``update-rc.d`` to safely install an +initialization script on behalf of the package. The OpenEmbedded build +system takes care of details such as making sure the script is stopped +before a package is removed and started when the package is installed. + +Three variables control this class: ``INITSCRIPT_PACKAGES``, +``INITSCRIPT_NAME`` and ``INITSCRIPT_PARAMS``. See the variable links +for details. + +.. _ref-classes-useradd: + +``useradd*.bbclass`` +==================== + +The ``useradd*`` classes support the addition of users or groups for +usage by the package on the target. For example, if you have packages +that contain system services that should be run under their own user or +group, you can use these classes to enable creation of the user or +group. The ``meta-skeleton/recipes-skeleton/useradd/useradd-example.bb`` +recipe in the :term:`Source Directory` provides a simple +example that shows how to add three users and groups to two packages. +See the ``useradd-example.bb`` recipe for more information on how to use +these classes. + +The ``useradd_base`` class provides basic functionality for user or +groups settings. + +The ``useradd*`` classes support the +:term:`USERADD_PACKAGES`, +:term:`USERADD_PARAM`, +:term:`GROUPADD_PARAM`, and +:term:`GROUPMEMS_PARAM` variables. + +The ``useradd-staticids`` class supports the addition of users or groups +that have static user identification (``uid``) and group identification +(``gid``) values. + +The default behavior of the OpenEmbedded build system for assigning +``uid`` and ``gid`` values when packages add users and groups during +package install time is to add them dynamically. This works fine for +programs that do not care what the values of the resulting users and +groups become. In these cases, the order of the installation determines +the final ``uid`` and ``gid`` values. However, if non-deterministic +``uid`` and ``gid`` values are a problem, you can override the default, +dynamic application of these values by setting static values. When you +set static values, the OpenEmbedded build system looks in +:term:`BBPATH` for ``files/passwd`` and ``files/group`` +files for the values. + +To use static ``uid`` and ``gid`` values, you need to set some +variables. See the :term:`USERADDEXTENSION`, +:term:`USERADD_UID_TABLES`, +:term:`USERADD_GID_TABLES`, and +:term:`USERADD_ERROR_DYNAMIC` variables. +You can also see the :ref:`useradd <ref-classes-useradd>` class for +additional information. + +.. note:: + + You do not use the + useradd-staticids + class directly. You either enable or disable the class by setting the + USERADDEXTENSION + variable. If you enable or disable the class in a configured system, + TMPDIR + might contain incorrect + uid + and + gid + values. Deleting the + TMPDIR + directory will correct this condition. + +.. _ref-classes-utility-tasks: + +``utility-tasks.bbclass`` +========================= + +The ``utility-tasks`` class provides support for various "utility" type +tasks that are applicable to all recipes, such as +:ref:`ref-tasks-clean` and +:ref:`ref-tasks-listtasks`. + +This class is enabled by default because it is inherited by the +:ref:`base <ref-classes-base>` class. + +.. _ref-classes-utils: + +``utils.bbclass`` +================= + +The ``utils`` class provides some useful Python functions that are +typically used in inline Python expressions (e.g. ``${@...}``). One +example use is for ``bb.utils.contains()``. + +This class is enabled by default because it is inherited by the +:ref:`base <ref-classes-base>` class. + +.. _ref-classes-vala: + +``vala.bbclass`` +================ + +The ``vala`` class supports recipes that need to build software written +using the Vala programming language. + +.. _ref-classes-waf: + +``waf.bbclass`` +=============== + +The ``waf`` class supports recipes that need to build software that uses +the Waf build system. You can use the +:term:`EXTRA_OECONF` or +:term:`PACKAGECONFIG_CONFARGS` variables +to specify additional configuration options to be passed on the Waf +command line. diff --git a/poky/documentation/ref-manual/ref-classes.xml b/poky/documentation/ref-manual/ref-classes.xml index f8920d8c1..1dcd5fdd0 100644 --- a/poky/documentation/ref-manual/ref-classes.xml +++ b/poky/documentation/ref-manual/ref-classes.xml @@ -1,6 +1,7 @@ <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > +<!--SPDX-License-Identifier: CC-BY-2.0-UK--> <chapter id='ref-classes'> <title>Classes</title> @@ -1879,8 +1880,82 @@ This check was removed for YP 2.3 release <para> The <filename>kernel-fitimage</filename> class provides support to - pack zImages. + pack a kernel Image, device trees and a RAM disk into a single + FIT image. In theory, a FIT image can support any number of kernels, + RAM disks and device-trees. + However, <filename>kernel-fitimage</filename> currently only supports + limited usescases: just one kernel image, an optional RAM disk, and + any number of device tree. </para> + + <para> + To create a FIT image, it is required that + <filename><link linkend='var-KERNEL_CLASSES'>KERNEL_CLASSES</link></filename> + is set to "kernel-fitimage" and + <filename><link linkend='var-KERNEL_IMAGETYPE'>KERNEL_IMAGETYPE</link></filename> + is set to "fitImage". + </para> + + <para> + The options for the device tree compiler passed to mkimage -D feature + when creating the FIT image are specified using the + <filename><link linkend='var-UBOOT_MKIMAGE_DTCOPTS'>UBOOT_MKIMAGE_DTCOPTS</link></filename> + variable. + </para> + + <para> + Only a single kernel can be added to the FIT image created by + <filename>kernel-fitimage</filename> and the kernel image in FIT is + mandatory. + The address where the kernel image is to be loaded by U-boot is + specified by + <filename><link linkend='var-UBOOT_LOADADDRESS'>UBOOT_LOADADDRESS</link></filename> + and the entrypoint by + <filename><link linkend='var-UBOOT_ENTRYPOINT'>UBOOT_ENTRYPOINT</link></filename>. + </para> + + <para> + Multiple device trees can be added to the FIT image created by + <filename>kernel-fitimage</filename> and the device tree is optional. + The address where the device tree is to be loaded by U-boot is + specified by + <filename><link linkend='var-UBOOT_DTBO_LOADADDRESS'>UBOOT_DTBO_LOADADDRESS</link></filename> + for device tree overlays and by + <filename><link linkend='var-UBOOT_DTB_LOADADDRESS'>UBOOT_DTB_LOADADDRESS</link></filename> + for device tree binaries. + </para> + + <para> + Only a single RAM disk can be added to the FIT image created by + <filename>kernel-fitimage</filename> and the RAM disk in FIT is + optional. + The address where the RAM disk image is to be loaded by U-boot + is specified by + <filename><link linkend='var-UBOOT_RD_LOADADDRESS'>UBOOT_RD_LOADADDRESS</link></filename> + and the entrypoint by + <filename><link linkend='var-UBOOT_RD_ENTRYPOINT'>UBOOT_RD_ENTRYPOINT</link></filename>. + The ramdisk is added to FIT image when + <filename><link linkend='var-INITRAMFS_IMAGE'>INITRAMFS_IMAGE</link></filename> + is specified. + </para> + + <para> + The FIT image generated by <filename>kernel-fitimage</filename> class + is signed when the variables + <filename><link linkend='var-UBOOT_SIGN_ENABLE'>UBOOT_SIGN_ENABLE</link></filename>, + <filename><link linkend='var-UBOOT_MKIMAGE_DTCOPTS'>UBOOT_MKIMAGE_DTCOPTS</link></filename>, + <filename><link linkend='var-UBOOT_SIGN_KEYDIR'>UBOOT_SIGN_KEYDIR</link></filename> + and + <filename><link linkend='var-UBOOT_SIGN_KEYNAME'>UBOOT_SIGN_KEYNAME</link></filename> + are set appropriately. + The default values used for + <filename><link linkend='var-FIT_HASH_ALG'>FIT_HASH_ALG</link></filename> + and + <filename><link linkend='var-FIT_SIGN_ALG'>FIT_SIGN_ALG</link></filename> + in <filename>kernel-fitimage</filename> are "sha256" and "rsa2048" + respectively. + </para> + </section> <section id='ref-classes-kernel-grub'> diff --git a/poky/documentation/ref-manual/ref-devtool-reference.rst b/poky/documentation/ref-manual/ref-devtool-reference.rst new file mode 100644 index 000000000..eaca45ae2 --- /dev/null +++ b/poky/documentation/ref-manual/ref-devtool-reference.rst @@ -0,0 +1,625 @@ +.. SPDX-License-Identifier: CC-BY-2.0-UK + +*************************** +``devtool`` Quick Reference +*************************** + +The ``devtool`` command-line tool provides a number of features that +help you build, test, and package software. This command is available +alongside the ``bitbake`` command. Additionally, the ``devtool`` command +is a key part of the extensible SDK. + +This chapter provides a Quick Reference for the ``devtool`` command. For +more information on how to apply the command when using the extensible +SDK, see the ":doc:`../sdk-manual/sdk-extensible`" chapter in the Yocto +Project Application Development and the Extensible Software Development +Kit (eSDK) manual. + +.. _devtool-getting-help: + +Getting Help +============ + +The ``devtool`` command line is organized similarly to Git in that it +has a number of sub-commands for each function. You can run +``devtool --help`` to see all the commands: +:: + + $ devtool -h + NOTE: Starting bitbake server... + usage: devtool [--basepath BASEPATH] [--bbpath BBPATH] [-d] [-q] [--color COLOR] [-h] <subcommand> ... + + OpenEmbedded development tool + + options: + --basepath BASEPATH Base directory of SDK / build directory + --bbpath BBPATH Explicitly specify the BBPATH, rather than getting it from the metadata + -d, --debug Enable debug output + -q, --quiet Print only errors + --color COLOR Colorize output (where COLOR is auto, always, never) + -h, --help show this help message and exit + + subcommands: + Beginning work on a recipe: + add Add a new recipe + modify Modify the source for an existing recipe + upgrade Upgrade an existing recipe + Getting information: + status Show workspace status + latest-version Report the latest version of an existing recipe + check-upgrade-status Report upgradability for multiple (or all) recipes + search Search available recipes + Working on a recipe in the workspace: + build Build a recipe + rename Rename a recipe file in the workspace + edit-recipe Edit a recipe file + find-recipe Find a recipe file + configure-help Get help on configure script options + update-recipe Apply changes from external source tree to recipe + reset Remove a recipe from your workspace + finish Finish working on a recipe in your workspace + Testing changes on target: + deploy-target Deploy recipe output files to live target machine + undeploy-target Undeploy recipe output files in live target machine + build-image Build image including workspace recipe packages + Advanced: + create-workspace Set up workspace in an alternative location + extract Extract the source for an existing recipe + sync Synchronize the source tree for an existing recipe + menuconfig Alter build-time configuration for a recipe + import Import exported tar archive into workspace + export Export workspace into a tar archive + other: + selftest-reverse Reverse value (for selftest) + pluginfile Print the filename of this plugin + bbdir Print the BBPATH directory of this plugin + count How many times have this plugin been registered. + multiloaded How many times have this plugin been initialized + Use devtool <subcommand> --help to get help on a specific command + +As directed in the general help output, you can +get more syntax on a specific command by providing the command name and +using "--help": +:: + + $ devtool add --help + NOTE: Starting bitbake server... + usage: devtool add [-h] [--same-dir | --no-same-dir] [--fetch URI] [--npm-dev] [--version VERSION] [--no-git] [--srcrev SRCREV | --autorev] [--srcbranch SRCBRANCH] [--binary] [--also-native] [--src-subdir SUBDIR] [--mirrors] + [--provides PROVIDES] + [recipename] [srctree] [fetchuri] + + Adds a new recipe to the workspace to build a specified source tree. Can optionally fetch a remote URI and unpack it to create the source tree. + + arguments: + recipename Name for new recipe to add (just name - no version, path or extension). If not specified, will attempt to auto-detect it. + srctree Path to external source tree. If not specified, a subdirectory of /media/build1/poky/build/workspace/sources will be used. + fetchuri Fetch the specified URI and extract it to create the source tree + + options: + -h, --help show this help message and exit + --same-dir, -s Build in same directory as source + --no-same-dir Force build in a separate build directory + --fetch URI, -f URI Fetch the specified URI and extract it to create the source tree (deprecated - pass as positional argument instead) + --npm-dev For npm, also fetch devDependencies + --version VERSION, -V VERSION + Version to use within recipe (PV) + --no-git, -g If fetching source, do not set up source tree as a git repository + --srcrev SRCREV, -S SRCREV + Source revision to fetch if fetching from an SCM such as git (default latest) + --autorev, -a When fetching from a git repository, set SRCREV in the recipe to a floating revision instead of fixed + --srcbranch SRCBRANCH, -B SRCBRANCH + Branch in source repository if fetching from an SCM such as git (default master) + --binary, -b Treat the source tree as something that should be installed verbatim (no compilation, same directory structure). Useful with binary packages e.g. RPMs. + --also-native Also add native variant (i.e. support building recipe for the build host as well as the target machine) + --src-subdir SUBDIR Specify subdirectory within source tree to use + --mirrors Enable PREMIRRORS and MIRRORS for source tree fetching (disable by default). + --provides PROVIDES, -p PROVIDES + Specify an alias for the item provided by the recipe. E.g. virtual/libgl + +.. _devtool-the-workspace-layer-structure: + +The Workspace Layer Structure +============================= + +``devtool`` uses a "Workspace" layer in which to accomplish builds. This +layer is not specific to any single ``devtool`` command but is rather a +common working area used across the tool. + +The following figure shows the workspace structure: + +.. image:: figures/build-workspace-directory.png + :align: center + :scale: 70% + +:: + + attic - A directory created if devtool believes it must preserve + anything when you run "devtool reset". For example, if you + run "devtool add", make changes to the recipe, and then + run "devtool reset", devtool takes notice that the file has + been changed and moves it into the attic should you still + want the recipe. + + README - Provides information on what is in workspace layer and how to + manage it. + + .devtool_md5 - A checksum file used by devtool. + + appends - A directory that contains *.bbappend files, which point to + external source. + + conf - A configuration directory that contains the layer.conf file. + + recipes - A directory containing recipes. This directory contains a + folder for each directory added whose name matches that of the + added recipe. devtool places the recipe.bb file + within that sub-directory. + + sources - A directory containing a working copy of the source files used + when building the recipe. This is the default directory used + as the location of the source tree when you do not provide a + source tree path. This directory contains a folder for each + set of source files matched to a corresponding recipe. + +.. _devtool-adding-a-new-recipe-to-the-workspace: + +Adding a New Recipe to the Workspace Layer +========================================== + +Use the ``devtool add`` command to add a new recipe to the workspace +layer. The recipe you add should not exist - ``devtool`` creates it for +you. The source files the recipe uses should exist in an external area. + +The following example creates and adds a new recipe named ``jackson`` to +a workspace layer the tool creates. The source code built by the recipes +resides in ``/home/user/sources/jackson``: +:: + + $ devtool add jackson /home/user/sources/jackson + +If you add a recipe and the workspace layer does not exist, the command +creates the layer and populates it as described in "`The Workspace Layer +Structure <#devtool-the-workspace-layer-structure>`__" section. + +Running ``devtool add`` when the workspace layer exists causes the tool +to add the recipe, append files, and source files into the existing +workspace layer. The ``.bbappend`` file is created to point to the +external source tree. + +.. note:: + + If your recipe has runtime dependencies defined, you must be sure + that these packages exist on the target hardware before attempting to + run your application. If dependent packages (e.g. libraries) do not + exist on the target, your application, when run, will fail to find + those functions. For more information, see the + ":ref:`ref-manual/ref-devtool-reference:deploying your software on the target machine`" + section. + +By default, ``devtool add`` uses the latest revision (i.e. master) when +unpacking files from a remote URI. In some cases, you might want to +specify a source revision by branch, tag, or commit hash. You can +specify these options when using the ``devtool add`` command: + +- To specify a source branch, use the ``--srcbranch`` option: + :: + + $ devtool add --srcbranch DISTRO_NAME_NO_CAP jackson /home/user/sources/jackson + + In the previous example, you are checking out the DISTRO_NAME_NO_CAP + branch. + +- To specify a specific tag or commit hash, use the ``--srcrev`` + option: + :: + + $ devtool add --srcrev DISTRO_REL_TAG jackson /home/user/sources/jackson + $ devtool add --srcrev some_commit_hash /home/user/sources/jackson + + The previous examples check out the + DISTRO_REL_TAG tag and the commit associated with the + some_commit_hash hash. + +.. note:: + + If you prefer to use the latest revision every time the recipe is + built, use the options --autorev or -a. + +.. _devtool-extracting-the-source-for-an-existing-recipe: + +Extracting the Source for an Existing Recipe +============================================ + +Use the ``devtool extract`` command to extract the source for an +existing recipe. When you use this command, you must supply the root +name of the recipe (i.e. no version, paths, or extensions), and you must +supply the directory to which you want the source extracted. + +Additional command options let you control the name of a development +branch into which you can checkout the source and whether or not to keep +a temporary directory, which is useful for debugging. + +.. _devtool-synchronizing-a-recipes-extracted-source-tree: + +Synchronizing a Recipe's Extracted Source Tree +============================================== + +Use the ``devtool sync`` command to synchronize a previously extracted +source tree for an existing recipe. When you use this command, you must +supply the root name of the recipe (i.e. no version, paths, or +extensions), and you must supply the directory to which you want the +source extracted. + +Additional command options let you control the name of a development +branch into which you can checkout the source and whether or not to keep +a temporary directory, which is useful for debugging. + +.. _devtool-modifying-a-recipe: + +Modifying an Existing Recipe +============================ + +Use the ``devtool modify`` command to begin modifying the source of an +existing recipe. This command is very similar to the +```add`` <#devtool-adding-a-new-recipe-to-the-workspace>`__ command +except that it does not physically create the recipe in the workspace +layer because the recipe already exists in an another layer. + +The ``devtool modify`` command extracts the source for a recipe, sets it +up as a Git repository if the source had not already been fetched from +Git, checks out a branch for development, and applies any patches from +the recipe as commits on top. You can use the following command to +checkout the source files: +:: + + $ devtool modify recipe + +Using the above command form, ``devtool`` uses the existing recipe's +:term:`SRC_URI` statement to locate the upstream source, +extracts the source into the default sources location in the workspace. +The default development branch used is "devtool". + +.. _devtool-edit-an-existing-recipe: + +Edit an Existing Recipe +======================= + +Use the ``devtool edit-recipe`` command to run the default editor, which +is identified using the ``EDITOR`` variable, on the specified recipe. + +When you use the ``devtool edit-recipe`` command, you must supply the +root name of the recipe (i.e. no version, paths, or extensions). Also, +the recipe file itself must reside in the workspace as a result of the +``devtool add`` or ``devtool upgrade`` commands. However, you can +override that requirement by using the "-a" or "--any-recipe" option. +Using either of these options allows you to edit any recipe regardless +of its location. + +.. _devtool-updating-a-recipe: + +Updating a Recipe +================= + +Use the ``devtool update-recipe`` command to update your recipe with +patches that reflect changes you make to the source files. For example, +if you know you are going to work on some code, you could first use the +```devtool modify`` <#devtool-modifying-a-recipe>`__ command to extract +the code and set up the workspace. After which, you could modify, +compile, and test the code. + +When you are satisfied with the results and you have committed your +changes to the Git repository, you can then run the +``devtool update-recipe`` to create the patches and update the recipe: +:: + + $ devtool update-recipe recipe + +If you run the ``devtool update-recipe`` +without committing your changes, the command ignores the changes. + +Often, you might want to apply customizations made to your software in +your own layer rather than apply them to the original recipe. If so, you +can use the ``-a`` or ``--append`` option with the +``devtool update-recipe`` command. These options allow you to specify +the layer into which to write an append file: +:: + + $ devtool update-recipe recipe -a base-layer-directory + +The ``*.bbappend`` file is created at the +appropriate path within the specified layer directory, which may or may +not be in your ``bblayers.conf`` file. If an append file already exists, +the command updates it appropriately. + +.. _devtool-checking-on-the-upgrade-status-of-a-recipe: + +Checking on the Upgrade Status of a Recipe +========================================== + +Upstream recipes change over time. Consequently, you might find that you +need to determine if you can upgrade a recipe to a newer version. + +To check on the upgrade status of a recipe, use the +``devtool check-upgrade-status`` command. The command displays a table +of your current recipe versions, the latest upstream versions, the email +address of the recipe's maintainer, and any additional information such +as commit hash strings and reasons you might not be able to upgrade a +particular recipe. + +.. note:: + + - For the ``oe-core`` layer, recipe maintainers come from the + `maintainers.inc <http://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/meta/conf/distro/include/maintainers.inc>`_ + file. + + - If the recipe is using the :ref:`bitbake:git-fetcher` + rather than a + tarball, the commit hash points to the commit that matches the + recipe's latest version tag. + +As with all ``devtool`` commands, you can get help on the individual +command: +:: + + $ devtool check-upgrade-status -h + NOTE: Starting bitbake server... + usage: devtool check-upgrade-status [-h] [--all] [recipe [recipe ...]] + + Prints a table of recipes together with versions currently provided by recipes, and latest upstream versions, when there is a later version available + + arguments: + recipe Name of the recipe to report (omit to report upgrade info for all recipes) + + options: + -h, --help show this help message and exit + --all, -a Show all recipes, not just recipes needing upgrade + +Unless you provide a specific recipe name on the command line, the +command checks all recipes in all configured layers. + +Following is a partial example table that reports on all the recipes. +Notice the reported reason for not upgrading the ``base-passwd`` recipe. +In this example, while a new version is available upstream, you do not +want to use it because the dependency on ``cdebconf`` is not easily +satisfied. + +.. note:: + + When a reason for not upgrading displays, the reason is usually + written into the recipe using the RECIPE_NO_UPDATE_REASON + variable. See the base-passwd.bb recipe for an example. + +:: + + $ devtool check-upgrade-status ... + NOTE: acpid 2.0.30 2.0.31 Ross Burton <ross.burton@intel.com> + NOTE: u-boot-fw-utils 2018.11 2019.01 Marek Vasut <marek.vasut@gmail.com> d3689267f92c5956e09cc7d1baa4700141662bff + NOTE: u-boot-tools 2018.11 2019.01 Marek Vasut <marek.vasut@gmail.com> d3689267f92c5956e09cc7d1baa4700141662bff . . . + NOTE: base-passwd 3.5.29 3.5.45 Anuj Mittal <anuj.mittal@intel.com> cannot be updated due to: Version 3.5.38 requires cdebconf for update-passwd utility + NOTE: busybox 1.29.2 1.30.0 Andrej Valek <andrej.valek@siemens.com> + NOTE: dbus-test 1.12.10 1.12.12 Chen Qi <Qi.Chen@windriver.com> + +.. _devtool-upgrading-a-recipe: + +Upgrading a Recipe +================== + +As software matures, upstream recipes are upgraded to newer versions. As +a developer, you need to keep your local recipes up-to-date with the +upstream version releases. Several methods exist by which you can +upgrade recipes. You can read about them in the ":ref:`gs-upgrading-recipes`" +section of the Yocto Project Development Tasks Manual. This section +overviews the ``devtool upgrade`` command. + +Before you upgrade a recipe, you can check on its upgrade status. See +the ":ref:`devtool-checking-on-the-upgrade-status-of-a-recipe`" section +for more information. + +The ``devtool upgrade`` command upgrades an existing recipe to a more +recent version of the recipe upstream. The command puts the upgraded +recipe file along with any associated files into a "workspace" and, if +necessary, extracts the source tree to a specified location. During the +upgrade, patches associated with the recipe are rebased or added as +needed. + +When you use the ``devtool upgrade`` command, you must supply the root +name of the recipe (i.e. no version, paths, or extensions), and you must +supply the directory to which you want the source extracted. Additional +command options let you control things such as the version number to +which you want to upgrade (i.e. the :term:`PV`), the source +revision to which you want to upgrade (i.e. the +:term:`SRCREV`), whether or not to apply patches, and so +forth. + +You can read more on the ``devtool upgrade`` workflow in the +":ref:`sdk-devtool-use-devtool-upgrade-to-create-a-version-of-the-recipe-that-supports-a-newer-version-of-the-software`" +section in the Yocto Project Application Development and the Extensible +Software Development Kit (eSDK) manual. You can also see an example of +how to use ``devtool upgrade`` in the ":ref:`gs-using-devtool-upgrade`" +section in the Yocto Project Development Tasks Manual. + +.. _devtool-resetting-a-recipe: + +Resetting a Recipe +================== + +Use the ``devtool reset`` command to remove a recipe and its +configuration (e.g. the corresponding ``.bbappend`` file) from the +workspace layer. Realize that this command deletes the recipe and the +append file. The command does not physically move them for you. +Consequently, you must be sure to physically relocate your updated +recipe and the append file outside of the workspace layer before running +the ``devtool reset`` command. + +If the ``devtool reset`` command detects that the recipe or the append +files have been modified, the command preserves the modified files in a +separate "attic" subdirectory under the workspace layer. + +Here is an example that resets the workspace directory that contains the +``mtr`` recipe: +:: + + $ devtool reset mtr + NOTE: Cleaning sysroot for recipe mtr... + NOTE: Leaving source tree /home/scottrif/poky/build/workspace/sources/mtr as-is; if you no longer need it then please delete it manually + $ + +.. _devtool-building-your-recipe: + +Building Your Recipe +==================== + +Use the ``devtool build`` command to build your recipe. The +``devtool build`` command is equivalent to the +``bitbake -c populate_sysroot`` command. + +When you use the ``devtool build`` command, you must supply the root +name of the recipe (i.e. do not provide versions, paths, or extensions). +You can use either the "-s" or the "--disable-parallel-make" options to +disable parallel makes during the build. Here is an example: +:: + + $ devtool build recipe + +.. _devtool-building-your-image: + +Building Your Image +=================== + +Use the ``devtool build-image`` command to build an image, extending it +to include packages from recipes in the workspace. Using this command is +useful when you want an image that ready for immediate deployment onto a +device for testing. For proper integration into a final image, you need +to edit your custom image recipe appropriately. + +When you use the ``devtool build-image`` command, you must supply the +name of the image. This command has no command line options: +:: + + $ devtool build-image image + +.. _devtool-deploying-your-software-on-the-target-machine: + +Deploying Your Software on the Target Machine +============================================= + +Use the ``devtool deploy-target`` command to deploy the recipe's build +output to the live target machine: +:: + + $ devtool deploy-target recipe target + +The target is the address of the target machine, which must be running +an SSH server (i.e. ``user@hostname[:destdir]``). + +This command deploys all files installed during the +:ref:`ref-tasks-install` task. Furthermore, you do not +need to have package management enabled within the target machine. If +you do, the package manager is bypassed. + +.. note:: + + The ``deploy-target`` functionality is for development only. You + should never use it to update an image that will be used in + production. + +Some conditions exist that could prevent a deployed application from +behaving as expected. When both of the following conditions exist, your +application has the potential to not behave correctly when run on the +target: + +- You are deploying a new application to the target and the recipe you + used to build the application had correctly defined runtime + dependencies. + +- The target does not physically have the packages on which the + application depends installed. + +If both of these conditions exist, your application will not behave as +expected. The reason for this misbehavior is because the +``devtool deploy-target`` command does not deploy the packages (e.g. +libraries) on which your new application depends. The assumption is that +the packages are already on the target. Consequently, when a runtime +call is made in the application for a dependent function (e.g. a library +call), the function cannot be found. + +To be sure you have all the dependencies local to the target, you need +to be sure that the packages are pre-deployed (installed) on the target +before attempting to run your application. + +.. _devtool-removing-your-software-from-the-target-machine: + +Removing Your Software from the Target Machine +============================================== + +Use the ``devtool undeploy-target`` command to remove deployed build +output from the target machine. For the ``devtool undeploy-target`` +command to work, you must have previously used the +":ref:`devtool deploy-target <ref-manual/ref-devtool-reference:deploying your software on the target machine>`" +command. +:: + + $ devtool undeploy-target recipe target + +The target is the +address of the target machine, which must be running an SSH server (i.e. +``user@hostname``). + +.. _devtool-creating-the-workspace: + +Creating the Workspace Layer in an Alternative Location +======================================================= + +Use the ``devtool create-workspace`` command to create a new workspace +layer in your :term:`Build Directory`. When you create a +new workspace layer, it is populated with the ``README`` file and the +``conf`` directory only. + +The following example creates a new workspace layer in your current +working and by default names the workspace layer "workspace": +:: + + $ devtool create-workspace + +You can create a workspace layer anywhere by supplying a pathname with +the command. The following command creates a new workspace layer named +"new-workspace": +:: + + $ devtool create-workspace /home/scottrif/new-workspace + +.. _devtool-get-the-status-of-the-recipes-in-your-workspace: + +Get the Status of the Recipes in Your Workspace +=============================================== + +Use the ``devtool status`` command to list the recipes currently in your +workspace. Information includes the paths to their respective external +source trees. + +The ``devtool status`` command has no command-line options: +:: + + $ devtool status + +Following is sample output after using +:ref:`devtool add <ref-manual/ref-devtool-reference:adding a new recipe to the workspace layer>` +to create and add the ``mtr_0.86.bb`` recipe to the ``workspace`` directory: +:: + + $ devtool status mtr + :/home/scottrif/poky/build/workspace/sources/mtr (/home/scottrif/poky/build/workspace/recipes/mtr/mtr_0.86.bb) + $ + +.. _devtool-search-for-available-target-recipes: + +Search for Available Target Recipes +=================================== + +Use the ``devtool search`` command to search for available target +recipes. The command matches the recipe name, package name, description, +and installed files. The command displays the recipe name as a result of +a match. + +When you use the ``devtool search`` command, you must supply a keyword. +The command uses the keyword when searching for a match. diff --git a/poky/documentation/ref-manual/ref-devtool-reference.xml b/poky/documentation/ref-manual/ref-devtool-reference.xml index 11f7399c5..6c3ccc303 100644 --- a/poky/documentation/ref-manual/ref-devtool-reference.xml +++ b/poky/documentation/ref-manual/ref-devtool-reference.xml @@ -1,6 +1,7 @@ <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > +<!--SPDX-License-Identifier: CC-BY-2.0-UK--> <chapter id='ref-devtool-reference'> <title><filename>devtool</filename> Quick Reference</title> diff --git a/poky/documentation/ref-manual/ref-features.rst b/poky/documentation/ref-manual/ref-features.rst new file mode 100644 index 000000000..ae5a0e3b2 --- /dev/null +++ b/poky/documentation/ref-manual/ref-features.rst @@ -0,0 +1,353 @@ +.. SPDX-License-Identifier: CC-BY-2.0-UK + +******** +Features +******** + +This chapter provides a reference of shipped machine and distro features +you can include as part of your image, a reference on image features you +can select, and a reference on feature backfilling. + +Features provide a mechanism for working out which packages should be +included in the generated images. Distributions can select which +features they want to support through the ``DISTRO_FEATURES`` variable, +which is set or appended to in a distribution's configuration file such +as ``poky.conf``, ``poky-tiny.conf``, ``poky-lsb.conf`` and so forth. +Machine features are set in the ``MACHINE_FEATURES`` variable, which is +set in the machine configuration file and specifies the hardware +features for a given machine. + +These two variables combine to work out which kernel modules, utilities, +and other packages to include. A given distribution can support a +selected subset of features so some machine features might not be +included if the distribution itself does not support them. + +One method you can use to determine which recipes are checking to see if +a particular feature is contained or not is to ``grep`` through the +:term:`Metadata` for the feature. Here is an example that +discovers the recipes whose build is potentially changed based on a +given feature: +:: + + $ cd poky + $ git grep 'contains.*MACHINE_FEATURES.*feature' + +.. _ref-features-machine: + +Machine Features +================ + +The items below are features you can use with +:term:`MACHINE_FEATURES`. Features do not have a +one-to-one correspondence to packages, and they can go beyond simply +controlling the installation of a package or packages. Sometimes a +feature can influence how certain recipes are built. For example, a +feature might determine whether a particular configure option is +specified within the :ref:`ref-tasks-configure` task +for a particular recipe. + +This feature list only represents features as shipped with the Yocto +Project metadata: + +- *acpi:* Hardware has ACPI (x86/x86_64 only) + +- *alsa:* Hardware has ALSA audio drivers + +- *apm:* Hardware uses APM (or APM emulation) + +- *bluetooth:* Hardware has integrated BT + +- *efi:* Support for booting through EFI + +- *ext2:* Hardware HDD or Microdrive + +- *keyboard:* Hardware has a keyboard + +- *pcbios:* Support for booting through BIOS + +- *pci:* Hardware has a PCI bus + +- *pcmcia:* Hardware has PCMCIA or CompactFlash sockets + +- *phone:* Mobile phone (voice) support + +- *qvga:* Machine has a QVGA (320x240) display + +- *rtc:* Machine has a Real-Time Clock + +- *screen:* Hardware has a screen + +- *serial:* Hardware has serial support (usually RS232) + +- *touchscreen:* Hardware has a touchscreen + +- *usbgadget:* Hardware is USB gadget device capable + +- *usbhost:* Hardware is USB Host capable + +- *vfat:* FAT file system support + +- *wifi:* Hardware has integrated WiFi + +.. _ref-features-distro: + +Distro Features +=============== + +The items below are features you can use with +:term:`DISTRO_FEATURES` to enable features across +your distribution. Features do not have a one-to-one correspondence to +packages, and they can go beyond simply controlling the installation of +a package or packages. In most cases, the presence or absence of a +feature translates to the appropriate option supplied to the configure +script during the :ref:`ref-tasks-configure` task for +the recipes that optionally support the feature. + +Some distro features are also machine features. These select features +make sense to be controlled both at the machine and distribution +configuration level. See the +:term:`COMBINED_FEATURES` variable for more +information. + +This list only represents features as shipped with the Yocto Project +metadata: + +- *alsa:* Include ALSA support (OSS compatibility kernel modules + installed if available). + +- *api-documentation:* Enables generation of API documentation during + recipe builds. The resulting documentation is added to SDK tarballs + when the ``bitbake -c populate_sdk`` command is used. See the + ":ref:`sdk-manual/sdk-appendix-customizing-standard:adding api documentation to the standard sdk`" + section in the Yocto Project Application Development and the + Extensible Software Development Kit (eSDK) manual. + +- *bluetooth:* Include bluetooth support (integrated BT only). + +- *cramfs:* Include CramFS support. + +- *directfb:* Include DirectFB support. + +- *ext2:* Include tools for supporting for devices with internal + HDD/Microdrive for storing files (instead of Flash only devices). + +- *ipsec:* Include IPSec support. + +- *ipv6:* Include IPv6 support. + +- *keyboard:* Include keyboard support (e.g. keymaps will be loaded + during boot). + +- *ldconfig:* Include support for ldconfig and ``ld.so.conf`` on the + target. + +- *nfs:* Include NFS client support (for mounting NFS exports on + device). + +- *opengl:* Include the Open Graphics Library, which is a + cross-language, multi-platform application programming interface used + for rendering two and three-dimensional graphics. + +- *pci:* Include PCI bus support. + +- *pcmcia:* Include PCMCIA/CompactFlash support. + +- *ppp:* Include PPP dialup support. + +- *ptest:* Enables building the package tests where supported by + individual recipes. For more information on package tests, see the + ":ref:`dev-manual/dev-manual-common-tasks:testing packages with ptest`" section + in the Yocto Project Development Tasks Manual. + +- *smbfs:* Include SMB networks client support (for mounting + Samba/Microsoft Windows shares on device). + +- *systemd:* Include support for this ``init`` manager, which is a full + replacement of for ``init`` with parallel starting of services, + reduced shell overhead, and other features. This ``init`` manager is + used by many distributions. + +- *usbgadget:* Include USB Gadget Device support (for USB + networking/serial/storage). + +- *usbhost:* Include USB Host support (allows to connect external + keyboard, mouse, storage, network etc). + +- *usrmerge:* Merges the ``/bin``, ``/sbin``, ``/lib``, and ``/lib64`` + directories into their respective counterparts in the ``/usr`` + directory to provide better package and application compatibility. + +- *wayland:* Include the Wayland display server protocol and the + library that supports it. + +- *wifi:* Include WiFi support (integrated only). + +- *x11:* Include the X server and libraries. + +.. _ref-features-image: + +Image Features +============== + +The contents of images generated by the OpenEmbedded build system can be +controlled by the :term:`IMAGE_FEATURES` and +:term:`EXTRA_IMAGE_FEATURES` variables that +you typically configure in your image recipes. Through these variables, +you can add several different predefined packages such as development +utilities or packages with debug information needed to investigate +application problems or profile applications. + +The following image features are available for all images: + +- *allow-empty-password:* Allows Dropbear and OpenSSH to accept root + logins and logins from accounts having an empty password string. + +- *dbg-pkgs:* Installs debug symbol packages for all packages installed + in a given image. + +- *debug-tweaks:* Makes an image suitable for development (e.g. allows + root logins without passwords and enables post-installation logging). + See the 'allow-empty-password', 'empty-root-password', and + 'post-install-logging' features in this list for additional + information. + +- *dev-pkgs:* Installs development packages (headers and extra library + links) for all packages installed in a given image. + +- *doc-pkgs:* Installs documentation packages for all packages + installed in a given image. + +- *empty-root-password:* Sets the root password to an empty string, + which allows logins with a blank password. + +- *package-management:* Installs package management tools and preserves + the package manager database. + +- *post-install-logging:* Enables logging postinstall script runs to + the ``/var/log/postinstall.log`` file on first boot of the image on + the target system. + + .. note:: + + To make the + /var/log + directory on the target persistent, use the + VOLATILE_LOG_DIR + variable by setting it to "no". + +- *ptest-pkgs:* Installs ptest packages for all ptest-enabled recipes. + +- *read-only-rootfs:* Creates an image whose root filesystem is + read-only. See the + ":ref:`dev-manual/dev-manual-common-tasks:creating a read-only root filesystem`" + section in the Yocto Project Development Tasks Manual for more + information. + +- *splash:* Enables showing a splash screen during boot. By default, + this screen is provided by ``psplash``, which does allow + customization. If you prefer to use an alternative splash screen + package, you can do so by setting the ``SPLASH`` variable to a + different package name (or names) within the image recipe or at the + distro configuration level. + +- *staticdev-pkgs:* Installs static development packages, which are + static libraries (i.e. ``*.a`` files), for all packages installed in + a given image. + +Some image features are available only when you inherit the +:ref:`core-image <ref-classes-core-image>` class. The current list of +these valid features is as follows: + +- *hwcodecs:* Installs hardware acceleration codecs. + +- *nfs-server:* Installs an NFS server. + +- *perf:* Installs profiling tools such as ``perf``, ``systemtap``, and + ``LTTng``. For general information on user-space tools, see the + :doc:`../sdk-manual/sdk-manual` manual. + +- *ssh-server-dropbear:* Installs the Dropbear minimal SSH server. + +- *ssh-server-openssh:* Installs the OpenSSH SSH server, which is more + full-featured than Dropbear. Note that if both the OpenSSH SSH server + and the Dropbear minimal SSH server are present in + ``IMAGE_FEATURES``, then OpenSSH will take precedence and Dropbear + will not be installed. + +- *tools-debug:* Installs debugging tools such as ``strace`` and + ``gdb``. For information on GDB, see the + ":ref:`platdev-gdb-remotedebug`" section + in the Yocto Project Development Tasks Manual. For information on + tracing and profiling, see the :doc:`../profile-manual/profile-manual`. + +- *tools-sdk:* Installs a full SDK that runs on the device. + +- *tools-testapps:* Installs device testing tools (e.g. touchscreen + debugging). + +- *x11:* Installs the X server. + +- *x11-base:* Installs the X server with a minimal environment. + +- *x11-sato:* Installs the OpenedHand Sato environment. + +.. _ref-features-backfill: + +Feature Backfilling +=================== + +Sometimes it is necessary in the OpenEmbedded build system to extend +:term:`MACHINE_FEATURES` or +:term:`DISTRO_FEATURES` to control functionality +that was previously enabled and not able to be disabled. For these +cases, we need to add an additional feature item to appear in one of +these variables, but we do not want to force developers who have +existing values of the variables in their configuration to add the new +feature in order to retain the same overall level of functionality. +Thus, the OpenEmbedded build system has a mechanism to automatically +"backfill" these added features into existing distro or machine +configurations. You can see the list of features for which this is done +by finding the +:term:`DISTRO_FEATURES_BACKFILL` and +:term:`MACHINE_FEATURES_BACKFILL` +variables in the ``meta/conf/bitbake.conf`` file. + +Because such features are backfilled by default into all configurations +as described in the previous paragraph, developers who wish to disable +the new features need to be able to selectively prevent the backfilling +from occurring. They can do this by adding the undesired feature or +features to the +:term:`DISTRO_FEATURES_BACKFILL_CONSIDERED` +or +:term:`MACHINE_FEATURES_BACKFILL_CONSIDERED` +variables for distro features and machine features respectively. + +Here are two examples to help illustrate feature backfilling: + +- *The "pulseaudio" distro feature option*: Previously, PulseAudio + support was enabled within the Qt and GStreamer frameworks. Because + of this, the feature is backfilled and thus enabled for all distros + through the ``DISTRO_FEATURES_BACKFILL`` variable in the + ``meta/conf/bitbake.conf`` file. However, your distro needs to + disable the feature. You can disable the feature without affecting + other existing distro configurations that need PulseAudio support by + adding "pulseaudio" to ``DISTRO_FEATURES_BACKFILL_CONSIDERED`` in + your distro's ``.conf`` file. Adding the feature to this variable + when it also exists in the ``DISTRO_FEATURES_BACKFILL`` variable + prevents the build system from adding the feature to your + configuration's ``DISTRO_FEATURES``, effectively disabling the + feature for that particular distro. + +- *The "rtc" machine feature option*: Previously, real time clock (RTC) + support was enabled for all target devices. Because of this, the + feature is backfilled and thus enabled for all machines through the + ``MACHINE_FEATURES_BACKFILL`` variable in the + ``meta/conf/bitbake.conf`` file. However, your target device does not + have this capability. You can disable RTC support for your device + without affecting other machines that need RTC support by adding the + feature to your machine's ``MACHINE_FEATURES_BACKFILL_CONSIDERED`` + list in the machine's ``.conf`` file. Adding the feature to this + variable when it also exists in the ``MACHINE_FEATURES_BACKFILL`` + variable prevents the build system from adding the feature to your + configuration's ``MACHINE_FEATURES``, effectively disabling RTC + support for that particular machine. diff --git a/poky/documentation/ref-manual/ref-features.xml b/poky/documentation/ref-manual/ref-features.xml index 294b297c2..8cab5ec3a 100644 --- a/poky/documentation/ref-manual/ref-features.xml +++ b/poky/documentation/ref-manual/ref-features.xml @@ -1,6 +1,7 @@ <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > +<!--SPDX-License-Identifier: CC-BY-2.0-UK--> <chapter id='ref-features'> <title>Features</title> diff --git a/poky/documentation/ref-manual/ref-images.rst b/poky/documentation/ref-manual/ref-images.rst new file mode 100644 index 000000000..c88d4d75c --- /dev/null +++ b/poky/documentation/ref-manual/ref-images.rst @@ -0,0 +1,139 @@ +.. SPDX-License-Identifier: CC-BY-2.0-UK + +****** +Images +****** + +The OpenEmbedded build system provides several example images to satisfy +different needs. When you issue the ``bitbake`` command you provide a +"top-level" recipe that essentially begins the build for the type of +image you want. + +.. note:: + + Building an image without GNU General Public License Version 3 + (GPLv3), GNU Lesser General Public License Version 3 (LGPLv3), and + the GNU Affero General Public License Version 3 (AGPL-3.0) components + is only supported for minimal and base images. Furthermore, if you + are going to build an image using non-GPLv3 and similarly licensed + components, you must make the following changes in the + local.conf + file before using the BitBake command to build the minimal or base + image: + :: + + 1. Comment out the EXTRA_IMAGE_FEATURES line + 2. Set INCOMPATIBLE_LICENSE = "GPL-3.0 LGPL-3.0 AGPL-3.0" + + +From within the ``poky`` Git repository, you can use the following +command to display the list of directories within the :term:`Source Directory` +that contain image recipe files: :: + + $ ls meta*/recipes*/images/*.bb + +Following is a list of supported recipes: + +- ``build-appliance-image``: An example virtual machine that contains + all the pieces required to run builds using the build system as well + as the build system itself. You can boot and run the image using + either the `VMware + Player <http://www.vmware.com/products/player/overview.html>`__ or + `VMware + Workstation <http://www.vmware.com/products/workstation/overview.html>`__. + For more information on this image, see the :yocto_home:`Build + Appliance </software-item/build-appliance>` page + on the Yocto Project website. + +- ``core-image-base``: A console-only image that fully supports the + target device hardware. + +- ``core-image-clutter``: An image with support for the Open GL-based + toolkit Clutter, which enables development of rich and animated + graphical user interfaces. + +- ``core-image-full-cmdline``: A console-only image with more + full-featured Linux system functionality installed. + +- ``core-image-lsb``: An image that conforms to the Linux Standard Base + (LSB) specification. This image requires a distribution configuration + that enables LSB compliance (e.g. ``poky-lsb``). If you build + ``core-image-lsb`` without that configuration, the image will not be + LSB-compliant. + +- ``core-image-lsb-dev``: A ``core-image-lsb`` image that is suitable + for development work using the host. The image includes headers and + libraries you can use in a host development environment. This image + requires a distribution configuration that enables LSB compliance + (e.g. ``poky-lsb``). If you build ``core-image-lsb-dev`` without that + configuration, the image will not be LSB-compliant. + +- ``core-image-lsb-sdk``: A ``core-image-lsb`` that includes everything + in the cross-toolchain but also includes development headers and + libraries to form a complete standalone SDK. This image requires a + distribution configuration that enables LSB compliance (e.g. + ``poky-lsb``). If you build ``core-image-lsb-sdk`` without that + configuration, the image will not be LSB-compliant. This image is + suitable for development using the target. + +- ``core-image-minimal``: A small image just capable of allowing a + device to boot. + +- ``core-image-minimal-dev``: A ``core-image-minimal`` image suitable + for development work using the host. The image includes headers and + libraries you can use in a host development environment. + +- ``core-image-minimal-initramfs``: A ``core-image-minimal`` image that + has the Minimal RAM-based Initial Root Filesystem (initramfs) as part + of the kernel, which allows the system to find the first "init" + program more efficiently. See the + :term:`PACKAGE_INSTALL` variable for + additional information helpful when working with initramfs images. + +- ``core-image-minimal-mtdutils``: A ``core-image-minimal`` image that + has support for the Minimal MTD Utilities, which let the user + interact with the MTD subsystem in the kernel to perform operations + on flash devices. + +- ``core-image-rt``: A ``core-image-minimal`` image plus a real-time + test suite and tools appropriate for real-time use. + +- ``core-image-rt-sdk``: A ``core-image-rt`` image that includes + everything in the cross-toolchain. The image also includes + development headers and libraries to form a complete stand-alone SDK + and is suitable for development using the target. + +- ``core-image-sato``: An image with Sato support, a mobile environment + and visual style that works well with mobile devices. The image + supports X11 with a Sato theme and applications such as a terminal, + editor, file manager, media player, and so forth. + +- ``core-image-sato-dev``: A ``core-image-sato`` image suitable for + development using the host. The image includes libraries needed to + build applications on the device itself, testing and profiling tools, + and debug symbols. This image was formerly ``core-image-sdk``. + +- ``core-image-sato-sdk``: A ``core-image-sato`` image that includes + everything in the cross-toolchain. The image also includes + development headers and libraries to form a complete standalone SDK + and is suitable for development using the target. + +- ``core-image-testmaster``: A "master" image designed to be used for + automated runtime testing. Provides a "known good" image that is + deployed to a separate partition so that you can boot into it and use + it to deploy a second image to be tested. You can find more + information about runtime testing in the + ":ref:`dev-manual/dev-manual-common-tasks:performing automated runtime testing`" + section in the Yocto Project Development Tasks Manual. + +- ``core-image-testmaster-initramfs``: A RAM-based Initial Root + Filesystem (initramfs) image tailored for use with the + ``core-image-testmaster`` image. + +- ``core-image-weston``: A very basic Wayland image with a terminal. + This image provides the Wayland protocol libraries and the reference + Weston compositor. For more information, see the + ":ref:`dev-manual/dev-manual-common-tasks:using wayland and weston`" + section in the Yocto Project Development Tasks Manual. + +- ``core-image-x11``: A very basic X11 image with a terminal. diff --git a/poky/documentation/ref-manual/ref-images.xml b/poky/documentation/ref-manual/ref-images.xml index 1f96186c6..6f10a6fd2 100644 --- a/poky/documentation/ref-manual/ref-images.xml +++ b/poky/documentation/ref-manual/ref-images.xml @@ -1,6 +1,7 @@ <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > +<!--SPDX-License-Identifier: CC-BY-2.0-UK--> <chapter id='ref-images'> <title>Images</title> @@ -8,7 +9,7 @@ <para> The OpenEmbedded build system provides several example images to satisfy different needs. - When you issue the <filename>bitbake</filename> command you provide a “top-level” recipe + When you issue the <filename>bitbake</filename> command you provide a "top-level" recipe that essentially begins the build for the type of image you want. </para> @@ -99,7 +100,7 @@ <listitem><para id='images-core-image-minimal-initramfs'><filename>core-image-minimal-initramfs</filename>: A <filename>core-image-minimal</filename> image that has the Minimal RAM-based Initial Root Filesystem (initramfs) as part of the kernel, - which allows the system to find the first “init” program more efficiently. + which allows the system to find the first "init" program more efficiently. See the <link linkend='var-PACKAGE_INSTALL'><filename>PACKAGE_INSTALL</filename></link> variable for additional information helpful when working with diff --git a/poky/documentation/ref-manual/ref-kickstart.rst b/poky/documentation/ref-manual/ref-kickstart.rst new file mode 100644 index 000000000..45222de05 --- /dev/null +++ b/poky/documentation/ref-manual/ref-kickstart.rst @@ -0,0 +1,212 @@ +.. SPDX-License-Identifier: CC-BY-2.0-UK + +******************************************* +OpenEmbedded Kickstart (``.wks``) Reference +******************************************* + +.. _openembedded-kickstart-wks-reference: + +Introduction +============ + +The current Wic implementation supports only the basic kickstart +partitioning commands: ``partition`` (or ``part`` for short) and +``bootloader``. + +.. note:: + + Future updates will implement more commands and options. If you use + anything that is not specifically supported, results can be + unpredictable. + +This chapter provides a reference on the available kickstart commands. +The information lists the commands, their syntax, and meanings. +Kickstart commands are based on the Fedora kickstart versions but with +modifications to reflect Wic capabilities. You can see the original +documentation for those commands at the following link: +http://pykickstart.readthedocs.io/en/latest/kickstart-docs.html + +Command: part or partition +========================== + +Either of these commands creates a partition on the system and uses the +following syntax: +:: + + part [mntpoint] + partition [mntpoint] + +If you do not +provide mntpoint, Wic creates a partition but does not mount it. + +The ``mntpoint`` is where the partition is mounted and must be in one of +the following forms: + +- ``/path``: For example, "/", "/usr", or "/home" + +- ``swap``: The created partition is used as swap space + +Specifying a mntpoint causes the partition to automatically be mounted. +Wic achieves this by adding entries to the filesystem table (fstab) +during image generation. In order for Wic to generate a valid fstab, you +must also provide one of the ``--ondrive``, ``--ondisk``, or +``--use-uuid`` partition options as part of the command. + +.. note:: + + The mount program must understand the PARTUUID syntax you use with + --use-uuid + and non-root + mountpoint + , including swap. The busybox versions of these application are + currently excluded. + +Here is an example that uses "/" as the mountpoint. The command uses +``--ondisk`` to force the partition onto the ``sdb`` disk: part / +--source rootfs --ondisk sdb --fstype=ext3 --label platform --align 1024 + +Here is a list that describes other supported options you can use with +the ``part`` and ``partition`` commands: + +- ``--size``: The minimum partition size in MBytes. Specify an + integer value such as 500. Do not append the number with "MB". You do + not need this option if you use ``--source``. + +- ``--fixed-size``: The exact partition size in MBytes. You cannot + specify with ``--size``. An error occurs when assembling the disk + image if the partition data is larger than ``--fixed-size``. + +- ``--source``: This option is a Wic-specific option that names the + source of the data that populates the partition. The most common + value for this option is "rootfs", but you can use any value that + maps to a valid source plugin. For information on the source plugins, + see the ":ref:`dev-manual/dev-manual-common-tasks:using the wic plugin interface`" + section in the Yocto Project Development Tasks Manual. + + If you use ``--source rootfs``, Wic creates a partition as large as + needed and fills it with the contents of the root filesystem pointed + to by the ``-r`` command-line option or the equivalent rootfs derived + from the ``-e`` command-line option. The filesystem type used to + create the partition is driven by the value of the ``--fstype`` + option specified for the partition. See the entry on ``--fstype`` + that follows for more information. + + If you use ``--source plugin-name``, Wic creates a partition as large + as needed and fills it with the contents of the partition that is + generated by the specified plugin name using the data pointed to by + the ``-r`` command-line option or the equivalent rootfs derived from + the ``-e`` command-line option. Exactly what those contents are and + filesystem type used are dependent on the given plugin + implementation. + + If you do not use the ``--source`` option, the ``wic`` command + creates an empty partition. Consequently, you must use the ``--size`` + option to specify the size of the empty partition. + +- ``--ondisk`` or ``--ondrive``: Forces the partition to be created + on a particular disk. + +- ``--fstype``: Sets the file system type for the partition. Valid + values are: + + - ``ext4`` + + - ``ext3`` + + - ``ext2`` + + - ``btrfs`` + + - ``squashfs`` + + - ``swap`` + +- ``--fsoptions``: Specifies a free-form string of options to be used + when mounting the filesystem. This string is copied into the + ``/etc/fstab`` file of the installed system and should be enclosed in + quotes. If not specified, the default string is "defaults". + +- ``--label label``: Specifies the label to give to the filesystem to + be made on the partition. If the given label is already in use by + another filesystem, a new label is created for the partition. + +- ``--active``: Marks the partition as active. + +- ``--align (in KBytes)``: This option is a Wic-specific option that + says to start partitions on boundaries given x KBytes. + +- ``--no-table``: This option is a Wic-specific option. Using the + option reserves space for the partition and causes it to become + populated. However, the partition is not added to the partition + table. + +- ``--exclude-path``: This option is a Wic-specific option that + excludes the given relative path from the resulting image. This + option is only effective with the rootfs source plugin. + +- ``--extra-space``: This option is a Wic-specific option that adds + extra space after the space filled by the content of the partition. + The final size can exceed the size specified by the ``--size`` + option. The default value is 10 Mbytes. + +- ``--overhead-factor``: This option is a Wic-specific option that + multiplies the size of the partition by the option's value. You must + supply a value greater than or equal to "1". The default value is + "1.3". + +- ``--part-name``: This option is a Wic-specific option that + specifies a name for GPT partitions. + +- ``--part-type``: This option is a Wic-specific option that + specifies the partition type globally unique identifier (GUID) for + GPT partitions. You can find the list of partition type GUIDs at + http://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_type_GUIDs. + +- ``--use-uuid``: This option is a Wic-specific option that causes + Wic to generate a random GUID for the partition. The generated + identifier is used in the bootloader configuration to specify the + root partition. + +- ``--uuid``: This option is a Wic-specific option that specifies the + partition UUID. + +- ``--fsuuid``: This option is a Wic-specific option that specifies + the filesystem UUID. You can generate or modify + :term:`WKS_FILE` with this option if a preconfigured + filesystem UUID is added to the kernel command line in the bootloader + configuration before you run Wic. + +- ``--system-id``: This option is a Wic-specific option that + specifies the partition system ID, which is a one byte long, + hexadecimal parameter with or without the 0x prefix. + +- ``--mkfs-extraopts``: This option specifies additional options to + pass to the ``mkfs`` utility. Some default options for certain + filesystems do not take effect. See Wic's help on kickstart (i.e. + ``wic help kickstart``). + +Command: bootloader +=================== + +This command specifies how the bootloader should be configured and +supports the following options: + +.. note:: + + Bootloader functionality and boot partitions are implemented by the + various + --source + plugins that implement bootloader functionality. The bootloader + command essentially provides a means of modifying bootloader + configuration. + +- ``--timeout``: Specifies the number of seconds before the + bootloader times out and boots the default option. + +- ``--append``: Specifies kernel parameters. These parameters will be + added to the syslinux ``APPEND`` or ``grub`` kernel command line. + +- ``--configfile``: Specifies a user-defined configuration file for + the bootloader. You can provide a full pathname for the file or a + file that exists in the ``canned-wks`` folder. This option overrides + all other bootloader options. diff --git a/poky/documentation/ref-manual/ref-kickstart.xml b/poky/documentation/ref-manual/ref-kickstart.xml index 1128bd50d..45db1c0ff 100644 --- a/poky/documentation/ref-manual/ref-kickstart.xml +++ b/poky/documentation/ref-manual/ref-kickstart.xml @@ -1,6 +1,7 @@ <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > +<!--SPDX-License-Identifier: CC-BY-2.0-UK--> <chapter id='ref-kickstart'> <title>OpenEmbedded Kickstart (<filename>.wks</filename>) Reference</title> diff --git a/poky/documentation/ref-manual/ref-manual-customization.xsl b/poky/documentation/ref-manual/ref-manual-customization.xsl index c58dd905b..3181f618e 100644 --- a/poky/documentation/ref-manual/ref-manual-customization.xsl +++ b/poky/documentation/ref-manual/ref-manual-customization.xsl @@ -1,4 +1,6 @@ <?xml version='1.0'?> +<!--SPDX-License-Identifier: CC-BY-2.0-UK--> + <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns="http://www.w3.org/1999/xhtml" xmlns:fo="http://www.w3.org/1999/XSL/Format" version="1.0"> <xsl:import href="http://downloads.yoctoproject.org/mirror/docbook-mirror/docbook-xsl-1.76.1/xhtml/docbook.xsl" /> diff --git a/poky/documentation/ref-manual/ref-manual.rst b/poky/documentation/ref-manual/ref-manual.rst new file mode 100644 index 000000000..a106af21d --- /dev/null +++ b/poky/documentation/ref-manual/ref-manual.rst @@ -0,0 +1,31 @@ +.. SPDX-License-Identifier: CC-BY-2.0-UK + +============================== +Yocto Project Reference Manual +============================== + +| + +.. toctree:: + :caption: Table of Contents + :numbered: + + ref-system-requirements + ref-terms + ref-release-process + migration + ref-structure + ref-classes + ref-tasks + ref-devtool-reference + ref-kickstart + ref-qa-checks + ref-images + ref-features + ref-variables + ref-varlocality + faq + resources + history + +.. include:: /boilerplate.rst diff --git a/poky/documentation/ref-manual/ref-qa-checks.rst b/poky/documentation/ref-manual/ref-qa-checks.rst new file mode 100644 index 000000000..3e76ac150 --- /dev/null +++ b/poky/documentation/ref-manual/ref-qa-checks.rst @@ -0,0 +1,533 @@ +.. SPDX-License-Identifier: CC-BY-2.0-UK + +***************************** +QA Error and Warning Messages +***************************** + +.. _qa-introduction: + +Introduction +============ + +When building a recipe, the OpenEmbedded build system performs various +QA checks on the output to ensure that common issues are detected and +reported. Sometimes when you create a new recipe to build new software, +it will build with no problems. When this is not the case, or when you +have QA issues building any software, it could take a little time to +resolve them. + +While it is tempting to ignore a QA message or even to disable QA +checks, it is best to try and resolve any reported QA issues. This +chapter provides a list of the QA messages and brief explanations of the +issues you could encounter so that you can properly resolve problems. + +The next section provides a list of all QA error and warning messages +based on a default configuration. Each entry provides the message or +error form along with an explanation. + +.. note:: + + - At the end of each message, the name of the associated QA test (as + listed in the ":ref:`insane.bbclass <ref-classes-insane>`" + section) appears within square brackets. + + - As mentioned, this list of error and warning messages is for QA + checks only. The list does not cover all possible build errors or + warnings you could encounter. + + - Because some QA checks are disabled by default, this list does not + include all possible QA check errors and warnings. + +.. _qa-errors-and-warnings: + +Errors and Warnings +=================== + +- ``<packagename>: <path> is using libexec please relocate to <libexecdir> [libexec]`` + + The specified package contains files in ``/usr/libexec`` when the + distro configuration uses a different path for ``<libexecdir>`` By + default, ``<libexecdir>`` is ``$prefix/libexec``. However, this + default can be changed (e.g. ``${libdir}``). + + + +- ``package <packagename> contains bad RPATH <rpath> in file <file> [rpaths]`` + + The specified binary produced by the recipe contains dynamic library + load paths (rpaths) that contain build system paths such as + :term:`TMPDIR`, which are incorrect for the target and + could potentially be a security issue. Check for bad ``-rpath`` + options being passed to the linker in your + :ref:`ref-tasks-compile` log. Depending on the build + system used by the software being built, there might be a configure + option to disable rpath usage completely within the build of the + software. + + + +- ``<packagename>: <file> contains probably-redundant RPATH <rpath> [useless-rpaths]`` + + The specified binary produced by the recipe contains dynamic library + load paths (rpaths) that on a standard system are searched by default + by the linker (e.g. ``/lib`` and ``/usr/lib``). While these paths + will not cause any breakage, they do waste space and are unnecessary. + Depending on the build system used by the software being built, there + might be a configure option to disable rpath usage completely within + the build of the software. + + + +- ``<packagename> requires <files>, but no providers in its RDEPENDS [file-rdeps]`` + + A file-level dependency has been identified from the specified + package on the specified files, but there is no explicit + corresponding entry in :term:`RDEPENDS`. If + particular files are required at runtime then ``RDEPENDS`` should be + declared in the recipe to ensure the packages providing them are + built. + + + +- ``<packagename1> rdepends on <packagename2>, but it isn't a build dependency? [build-deps]`` + + A runtime dependency exists between the two specified packages, but + there is nothing explicit within the recipe to enable the + OpenEmbedded build system to ensure that dependency is satisfied. + This condition is usually triggered by an + :term:`RDEPENDS` value being added at the packaging + stage rather than up front, which is usually automatic based on the + contents of the package. In most cases, you should change the recipe + to add an explicit ``RDEPENDS`` for the dependency. + + + +- ``non -dev/-dbg/nativesdk- package contains symlink .so: <packagename> path '<path>' [dev-so]`` + + Symlink ``.so`` files are for development only, and should therefore + go into the ``-dev`` package. This situation might occur if you add + ``*.so*`` rather than ``*.so.*`` to a non-dev package. Change + :term:`FILES` (and possibly + :term:`PACKAGES`) such that the specified ``.so`` + file goes into an appropriate ``-dev`` package. + + + +- ``non -staticdev package contains static .a library: <packagename> path '<path>' [staticdev]`` + + Static ``.a`` library files should go into a ``-staticdev`` package. + Change :term:`FILES` (and possibly + :term:`PACKAGES`) such that the specified ``.a`` file + goes into an appropriate ``-staticdev`` package. + + + +- ``<packagename>: found library in wrong location [libdir]`` + + The specified file may have been installed into an incorrect + (possibly hardcoded) installation path. For example, this test will + catch recipes that install ``/lib/bar.so`` when ``${base_libdir}`` is + "lib32". Another example is when recipes install + ``/usr/lib64/foo.so`` when ``${libdir}`` is "/usr/lib". False + positives occasionally exist. For these cases add "libdir" to + :term:`INSANE_SKIP` for the package. + + + +- ``non debug package contains .debug directory: <packagename> path <path> [debug-files]`` + + The specified package contains a ``.debug`` directory, which should + not appear in anything but the ``-dbg`` package. This situation might + occur if you add a path which contains a ``.debug`` directory and do + not explicitly add the ``.debug`` directory to the ``-dbg`` package. + If this is the case, add the ``.debug`` directory explicitly to + ``FILES_${PN}-dbg``. See :term:`FILES` for additional + information on ``FILES``. + + + +- ``Architecture did not match (<machine_arch> to <file_arch>) on <file> [arch]`` + + By default, the OpenEmbedded build system checks the Executable and + Linkable Format (ELF) type, bit size, and endianness of any binaries + to ensure they match the target architecture. This test fails if any + binaries do not match the type since there would be an + incompatibility. The test could indicate that the wrong compiler or + compiler options have been used. Sometimes software, like + bootloaders, might need to bypass this check. If the file you receive + the error for is firmware that is not intended to be executed within + the target operating system or is intended to run on a separate + processor within the device, you can add "arch" to + :term:`INSANE_SKIP` for the package. Another + option is to check the :ref:`ref-tasks-compile` log + and verify that the compiler options being used are correct. + + + +- ``Bit size did not match (<machine_bits> to <file_bits>) <recipe> on <file> [arch]`` + + By default, the OpenEmbedded build system checks the Executable and + Linkable Format (ELF) type, bit size, and endianness of any binaries + to ensure they match the target architecture. This test fails if any + binaries do not match the type since there would be an + incompatibility. The test could indicate that the wrong compiler or + compiler options have been used. Sometimes software, like + bootloaders, might need to bypass this check. If the file you receive + the error for is firmware that is not intended to be executed within + the target operating system or is intended to run on a separate + processor within the device, you can add "arch" to + :term:`INSANE_SKIP` for the package. Another + option is to check the :ref:`ref-tasks-compile` log + and verify that the compiler options being used are correct. + + + +- ``Endianness did not match (<machine_endianness> to <file_endianness>) on <file> [arch]`` + + By default, the OpenEmbedded build system checks the Executable and + Linkable Format (ELF) type, bit size, and endianness of any binaries + to ensure they match the target architecture. This test fails if any + binaries do not match the type since there would be an + incompatibility. The test could indicate that the wrong compiler or + compiler options have been used. Sometimes software, like + bootloaders, might need to bypass this check. If the file you receive + the error for is firmware that is not intended to be executed within + the target operating system or is intended to run on a separate + processor within the device, you can add "arch" to + :term:`INSANE_SKIP` for the package. Another + option is to check the :ref:`ref-tasks-compile` log + and verify that the compiler options being used are correct. + + + +- ``ELF binary '<file>' has relocations in .text [textrel]`` + + The specified ELF binary contains relocations in its ``.text`` + sections. This situation can result in a performance impact at + runtime. + + Typically, the way to solve this performance issue is to add "-fPIC" + or "-fpic" to the compiler command-line options. For example, given + software that reads :term:`CFLAGS` when you build it, + you could add the following to your recipe: + :: + + CFLAGS_append = " -fPIC " + + For more information on text relocations at runtime, see + http://www.akkadia.org/drepper/textrelocs.html. + + + +- ``No GNU_HASH in the elf binary: '<file>' [ldflags]`` + + This indicates that binaries produced when building the recipe have + not been linked with the :term:`LDFLAGS` options + provided by the build system. Check to be sure that the ``LDFLAGS`` + variable is being passed to the linker command. A common workaround + for this situation is to pass in ``LDFLAGS`` using + :term:`TARGET_CC_ARCH` within the recipe as + follows: + :: + + TARGET_CC_ARCH += "${LDFLAGS}" + + + +- ``Package <packagename> contains Xorg driver (<driver>) but no xorg-abi- dependencies [xorg-driver-abi]`` + + The specified package contains an Xorg driver, but does not have a + corresponding ABI package dependency. The xserver-xorg recipe + provides driver ABI names. All drivers should depend on the ABI + versions that they have been built against. Driver recipes that + include ``xorg-driver-input.inc`` or ``xorg-driver-video.inc`` will + automatically get these versions. Consequently, you should only need + to explicitly add dependencies to binary driver recipes. + + + +- ``The /usr/share/info/dir file is not meant to be shipped in a particular package. [infodir]`` + + The ``/usr/share/info/dir`` should not be packaged. Add the following + line to your :ref:`ref-tasks-install` task or to your + ``do_install_append`` within the recipe as follows: + :: + + rm ${D}${infodir}/dir + + +- ``Symlink <path> in <packagename> points to TMPDIR [symlink-to-sysroot]`` + + The specified symlink points into :term:`TMPDIR` on the + host. Such symlinks will work on the host. However, they are clearly + invalid when running on the target. You should either correct the + symlink to use a relative path or remove the symlink. + + + +- ``<file> failed sanity test (workdir) in path <path> [la]`` + + The specified ``.la`` file contains :term:`TMPDIR` + paths. Any ``.la`` file containing these paths is incorrect since + ``libtool`` adds the correct sysroot prefix when using the files + automatically itself. + + + +- ``<file> failed sanity test (tmpdir) in path <path> [pkgconfig]`` + + The specified ``.pc`` file contains + :term:`TMPDIR`\ ``/``\ :term:`WORKDIR` + paths. Any ``.pc`` file containing these paths is incorrect since + ``pkg-config`` itself adds the correct sysroot prefix when the files + are accessed. + + + +- ``<packagename> rdepends on <debug_packagename> [debug-deps]`` + + A dependency exists between the specified non-dbg package (i.e. a + package whose name does not end in ``-dbg``) and a package that is a + ``dbg`` package. The ``dbg`` packages contain debug symbols and are + brought in using several different methods: + + - Using the ``dbg-pkgs`` + :term:`IMAGE_FEATURES` value. + + - Using :term:`IMAGE_INSTALL`. + + - As a dependency of another ``dbg`` package that was brought in + using one of the above methods. + + The dependency might have been automatically added because the + ``dbg`` package erroneously contains files that it should not contain + (e.g. a non-symlink ``.so`` file) or it might have been added + manually (e.g. by adding to :term:`RDEPENDS`). + + + +- ``<packagename> rdepends on <dev_packagename> [dev-deps]`` + + A dependency exists between the specified non-dev package (a package + whose name does not end in ``-dev``) and a package that is a ``dev`` + package. The ``dev`` packages contain development headers and are + usually brought in using several different methods: + + - Using the ``dev-pkgs`` + :term:`IMAGE_FEATURES` value. + + - Using :term:`IMAGE_INSTALL`. + + - As a dependency of another ``dev`` package that was brought in + using one of the above methods. + + The dependency might have been automatically added (because the + ``dev`` package erroneously contains files that it should not have + (e.g. a non-symlink ``.so`` file) or it might have been added + manually (e.g. by adding to :term:`RDEPENDS`). + + + +- ``<var>_<packagename> is invalid: <comparison> (<value>) only comparisons <, =, >, <=, and >= are allowed [dep-cmp]`` + + If you are adding a versioned dependency relationship to one of the + dependency variables (:term:`RDEPENDS`, + :term:`RRECOMMENDS`, + :term:`RSUGGESTS`, + :term:`RPROVIDES`, + :term:`RREPLACES`, or + :term:`RCONFLICTS`), you must only use the named + comparison operators. Change the versioned dependency values you are + adding to match those listed in the message. + + + +- ``<recipename>: The compile log indicates that host include and/or library paths were used. Please check the log '<logfile>' for more information. [compile-host-path]`` + + The log for the :ref:`ref-tasks-compile` task + indicates that paths on the host were searched for files, which is + not appropriate when cross-compiling. Look for "is unsafe for + cross-compilation" or "CROSS COMPILE Badness" in the specified log + file. + + + +- ``<recipename>: The install log indicates that host include and/or library paths were used. Please check the log '<logfile>' for more information. [install-host-path]`` + + The log for the :ref:`ref-tasks-install` task + indicates that paths on the host were searched for files, which is + not appropriate when cross-compiling. Look for "is unsafe for + cross-compilation" or "CROSS COMPILE Badness" in the specified log + file. + + + +- ``This autoconf log indicates errors, it looked at host include and/or library paths while determining system capabilities. Rerun configure task after fixing this. The path was '<path>'`` + + The log for the :ref:`ref-tasks-configure` task + indicates that paths on the host were searched for files, which is + not appropriate when cross-compiling. Look for "is unsafe for + cross-compilation" or "CROSS COMPILE Badness" in the specified log + file. + + + +- ``<packagename> doesn't match the [a-z0-9.+-]+ regex [pkgname]`` + + The convention within the OpenEmbedded build system (sometimes + enforced by the package manager itself) is to require that package + names are all lower case and to allow a restricted set of characters. + If your recipe name does not match this, or you add packages to + :term:`PACKAGES` that do not conform to the + convention, then you will receive this error. Rename your recipe. Or, + if you have added a non-conforming package name to ``PACKAGES``, + change the package name appropriately. + + + +- ``<recipe>: configure was passed unrecognized options: <options> [unknown-configure-option]`` + + The configure script is reporting that the specified options are + unrecognized. This situation could be because the options were + previously valid but have been removed from the configure script. Or, + there was a mistake when the options were added and there is another + option that should be used instead. If you are unsure, consult the + upstream build documentation, the ``./configure --help`` output, and + the upstream change log or release notes. Once you have worked out + what the appropriate change is, you can update + :term:`EXTRA_OECONF`, + :term:`PACKAGECONFIG_CONFARGS`, or the + individual :term:`PACKAGECONFIG` option values + accordingly. + + + +- ``Recipe <recipefile> has PN of "<recipename>" which is in OVERRIDES, this can result in unexpected behavior. [pn-overrides]`` + + The specified recipe has a name (:term:`PN`) value that + appears in :term:`OVERRIDES`. If a recipe is named + such that its ``PN`` value matches something already in ``OVERRIDES`` + (e.g. ``PN`` happens to be the same as :term:`MACHINE` + or :term:`DISTRO`), it can have unexpected + consequences. For example, assignments such as + ``FILES_${PN} = "xyz"`` effectively turn into ``FILES = "xyz"``. + Rename your recipe (or if ``PN`` is being set explicitly, change the + ``PN`` value) so that the conflict does not occur. See + :term:`FILES` for additional information. + + + +- ``<recipefile>: Variable <variable> is set as not being package specific, please fix this. [pkgvarcheck]`` + + Certain variables (:term:`RDEPENDS`, + :term:`RRECOMMENDS`, + :term:`RSUGGESTS`, + :term:`RCONFLICTS`, + :term:`RPROVIDES`, + :term:`RREPLACES`, :term:`FILES`, + ``pkg_preinst``, ``pkg_postinst``, ``pkg_prerm``, ``pkg_postrm``, and + :term:`ALLOW_EMPTY`) should always be set specific + to a package (i.e. they should be set with a package name override + such as ``RDEPENDS_${PN} = "value"`` rather than + ``RDEPENDS = "value"``). If you receive this error, correct any + assignments to these variables within your recipe. + + + +- ``File '<file>' from <recipename> was already stripped, this will prevent future debugging! [already-stripped]`` + + Produced binaries have already been stripped prior to the build + system extracting debug symbols. It is common for upstream software + projects to default to stripping debug symbols for output binaries. + In order for debugging to work on the target using ``-dbg`` packages, + this stripping must be disabled. + + Depending on the build system used by the software being built, + disabling this stripping could be as easy as specifying an additional + configure option. If not, disabling stripping might involve patching + the build scripts. In the latter case, look for references to "strip" + or "STRIP", or the "-s" or "-S" command-line options being specified + on the linker command line (possibly through the compiler command + line if preceded with "-Wl,"). + + .. note:: + + Disabling stripping here does not mean that the final packaged + binaries will be unstripped. Once the OpenEmbedded build system + splits out debug symbols to the + -dbg + package, it will then strip the symbols from the binaries. + + + +- ``<packagename> is listed in PACKAGES multiple times, this leads to packaging errors. [packages-list]`` + + Package names must appear only once in the + :term:`PACKAGES` variable. You might receive this + error if you are attempting to add a package to ``PACKAGES`` that is + already in the variable's value. + + + +- ``FILES variable for package <packagename> contains '//' which is invalid. Attempting to fix this but you should correct the metadata. [files-invalid]`` + + The string "//" is invalid in a Unix path. Correct all occurrences + where this string appears in a :term:`FILES` variable so + that there is only a single "/". + + + +- ``<recipename>: Files/directories were installed but not shipped in any package [installed-vs-shipped]`` + + Files have been installed within the + :ref:`ref-tasks-install` task but have not been + included in any package by way of the :term:`FILES` + variable. Files that do not appear in any package cannot be present + in an image later on in the build process. You need to do one of the + following: + + - Add the files to ``FILES`` for the package you want them to appear + in (e.g. ``FILES_${``\ :term:`PN`\ ``}`` for the main + package). + + - Delete the files at the end of the ``do_install`` task if the + files are not needed in any package. + + + +- ``<oldpackage>-<oldpkgversion> was registered as shlib provider for <library>, changing it to <newpackage>-<newpkgversion> because it was built later`` + + This message means that both ``<oldpackage>`` and ``<newpackage>`` + provide the specified shared library. You can expect this message + when a recipe has been renamed. However, if that is not the case, the + message might indicate that a private version of a library is being + erroneously picked up as the provider for a common library. If that + is the case, you should add the library's ``.so`` file name to + :term:`PRIVATE_LIBS` in the recipe that provides + the private version of the library. + +- ``LICENSE_<packagename> includes licenses (<licenses>) that are not listed in LICENSE [unlisted-pkg-lics]`` + + The :term:`LICENSE` of the recipe should be a superset + of all the licenses of all packages produced by this recipe. In other + words, any license in ``LICENSE_*`` should also appear in + :term:`LICENSE`. + + + +Configuring and Disabling QA Checks +=================================== + +You can configure the QA checks globally so that specific check failures +either raise a warning or an error message, using the +:term:`WARN_QA` and :term:`ERROR_QA` +variables, respectively. You can also disable checks within a particular +recipe using :term:`INSANE_SKIP`. For information on +how to work with the QA checks, see the +":ref:`insane.bbclass <ref-classes-insane>`" section. + +.. note:: + + Please keep in mind that the QA checks exist in order to detect real + or potential problems in the packaged output. So exercise caution + when disabling these checks. diff --git a/poky/documentation/ref-manual/ref-qa-checks.xml b/poky/documentation/ref-manual/ref-qa-checks.xml index 424a19c59..0071e4a55 100644 --- a/poky/documentation/ref-manual/ref-qa-checks.xml +++ b/poky/documentation/ref-manual/ref-qa-checks.xml @@ -1,6 +1,7 @@ <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > +<!--SPDX-License-Identifier: CC-BY-2.0-UK--> <chapter id='ref-qa-checks'> <title>QA Error and Warning Messages</title> diff --git a/poky/documentation/ref-manual/ref-release-process.rst b/poky/documentation/ref-manual/ref-release-process.rst new file mode 100644 index 000000000..be041e725 --- /dev/null +++ b/poky/documentation/ref-manual/ref-release-process.rst @@ -0,0 +1,193 @@ +.. SPDX-License-Identifier: CC-BY-2.0-UK + +***************************************************** +Yocto Project Releases and the Stable Release Process +***************************************************** + +The Yocto Project release process is predictable and consists of both +major and minor (point) releases. This brief chapter provides +information on how releases are named, their life cycle, and their +stability. + +Major and Minor Release Cadence +=============================== + +The Yocto Project delivers major releases (e.g. DISTRO) using a six +month cadence roughly timed each April and October of the year. +Following are examples of some major YP releases with their codenames +also shown. See the "`Major Release +Codenames <#major-release-codenames>`__" section for information on +codenames used with major releases. + + - 2.2 (Morty) + - 2.1 (Krogoth) + - 2.0 (Jethro) + +While the cadence is never perfect, this timescale facilitates +regular releases that have strong QA cycles while not overwhelming users +with too many new releases. The cadence is predictable and avoids many +major holidays in various geographies. + +The Yocto project delivers minor (point) releases on an unscheduled +basis and are usually driven by the accumulation of enough significant +fixes or enhancements to the associated major release. Following are +some example past point releases: + + - 2.1.1 + - 2.1.2 + - 2.2.1 + +The point release +indicates a point in the major release branch where a full QA cycle and +release process validates the content of the new branch. + +.. note:: + + Realize that there can be patches merged onto the stable release + branches as and when they become available. + +Major Release Codenames +======================= + +Each major release receives a codename that identifies the release in +the :ref:`overview-manual/overview-manual-development-environment:yocto project source repositories`. +The concept is that branches of :term:`Metadata` with the same +codename are likely to be compatible and thus work together. + +.. note:: + + Codenames are associated with major releases because a Yocto Project + release number (e.g. DISTRO) could conflict with a given layer or + company versioning scheme. Codenames are unique, interesting, and + easily identifiable. + +Releases are given a nominal release version as well but the codename is +used in repositories for this reason. You can find information on Yocto +Project releases and codenames at +https://wiki.yoctoproject.org/wiki/Releases. + +Stable Release Process +====================== + +Once released, the release enters the stable release process at which +time a person is assigned as the maintainer for that stable release. +This maintainer monitors activity for the release by investigating and +handling nominated patches and backport activity. Only fixes and +enhancements that have first been applied on the "master" branch (i.e. +the current, in-development branch) are considered for backporting to a +stable release. + +.. note:: + + The current Yocto Project policy regarding backporting is to consider + bug fixes and security fixes only. Policy dictates that features are + not backported to a stable release. This policy means generic recipe + version upgrades are unlikely to be accepted for backporting. The + exception to this policy occurs when a strong reason exists such as + the fix happens to also be the preferred upstream approach. + +Stable release branches have strong maintenance for about a year after +their initial release. Should significant issues be found for any +release regardless of its age, fixes could be backported to older +releases. For issues that are not backported given an older release, +Community LTS trees and branches exist where community members share +patches for older releases. However, these types of patches do not go +through the same release process as do point releases. You can find more +information about stable branch maintenance at +https://wiki.yoctoproject.org/wiki/Stable_branch_maintenance. + +Testing and Quality Assurance +============================= + +Part of the Yocto Project development and release process is quality +assurance through the execution of test strategies. Test strategies +provide the Yocto Project team a way to ensure a release is validated. +Additionally, because the test strategies are visible to you as a +developer, you can validate your projects. This section overviews the +available test infrastructure used in the Yocto Project. For information +on how to run available tests on your projects, see the +":ref:`dev-manual/dev-manual-common-tasks:performing automated runtime testing`" +section in the Yocto Project Development Tasks Manual. + +The QA/testing infrastructure is woven into the project to the point +where core developers take some of it for granted. The infrastructure +consists of the following pieces: + +- ``bitbake-selftest``: A standalone command that runs unit tests on + key pieces of BitBake and its fetchers. + +- :ref:`sanity.bbclass <ref-classes-sanity>`: This automatically + included class checks the build environment for missing tools (e.g. + ``gcc``) or common misconfigurations such as + :term:`MACHINE` set incorrectly. + +- :ref:`insane.bbclass <ref-classes-insane>`: This class checks the + generated output from builds for sanity. For example, if building for + an ARM target, did the build produce ARM binaries. If, for example, + the build produced PPC binaries then there is a problem. + +- :ref:`testimage.bbclass <ref-classes-testimage*>`: This class + performs runtime testing of images after they are built. The tests + are usually used with :doc:`QEMU <../dev-manual/dev-manual-qemu>` + to boot the images and check the combined runtime result boot + operation and functions. However, the test can also use the IP + address of a machine to test. + +- :ref:`ptest <dev-manual/dev-manual-common-tasks:testing packages with ptest>`: + Runs tests against packages produced during the build for a given + piece of software. The test allows the packages to be be run within a + target image. + +- ``oe-selftest``: Tests combination BitBake invocations. These tests + operate outside the OpenEmbedded build system itself. The + ``oe-selftest`` can run all tests by default or can run selected + tests or test suites. + + .. note:: + + Running + oe-selftest + requires host packages beyond the "Essential" grouping. See the " + Required Packages for the Build Host + " section for more information. + +Originally, much of this testing was done manually. However, significant +effort has been made to automate the tests so that more people can use +them and the Yocto Project development team can run them faster and more +efficiently. + +The Yocto Project's main Autobuilder (https://autobuilder.yoctoproject.org/) +publicly tests each Yocto Project release's code in the +:term:`OpenEmbedded-Core (OE-Core)`, Poky, and BitBake repositories. The testing +occurs for both the current state of the "master" branch and also for +submitted patches. Testing for submitted patches usually occurs in the +"ross/mut" branch in the ``poky-contrib`` repository (i.e. the +master-under-test branch) or in the "master-next" branch in the ``poky`` +repository. + +.. note:: + + You can find all these branches in the Yocto Project + Source Repositories + . + +Testing within these public branches ensures in a publicly visible way +that all of the main supposed architectures and recipes in OE-Core +successfully build and behave properly. + +Various features such as ``multilib``, sub architectures (e.g. ``x32``, +``poky-tiny``, ``musl``, ``no-x11`` and and so forth), +``bitbake-selftest``, and ``oe-selftest`` are tested as part of the QA +process of a release. Complete testing and validation for a release +takes the Autobuilder workers several hours. + +.. note:: + + The Autobuilder workers are non-homogeneous, which means regular + testing across a variety of Linux distributions occurs. The + Autobuilder is limited to only testing QEMU-based setups and not real + hardware. + +Finally, in addition to the Autobuilder's tests, the Yocto Project QA +team also performs testing on a variety of platforms, which includes +actual hardware, to ensure expected results. diff --git a/poky/documentation/ref-manual/ref-release-process.xml b/poky/documentation/ref-manual/ref-release-process.xml index 5efe17417..87f530806 100644 --- a/poky/documentation/ref-manual/ref-release-process.xml +++ b/poky/documentation/ref-manual/ref-release-process.xml @@ -1,6 +1,7 @@ <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > +<!--SPDX-License-Identifier: CC-BY-2.0-UK--> <chapter id='ref-release-process'> <title>Yocto Project Releases and the Stable Release Process</title> diff --git a/poky/documentation/ref-manual/ref-structure.rst b/poky/documentation/ref-manual/ref-structure.rst new file mode 100644 index 000000000..48a443331 --- /dev/null +++ b/poky/documentation/ref-manual/ref-structure.rst @@ -0,0 +1,890 @@ +.. SPDX-License-Identifier: CC-BY-2.0-UK + +************************** +Source Directory Structure +************************** + +The :term:`Source Directory` consists of numerous files, +directories and subdirectories; understanding their locations and +contents is key to using the Yocto Project effectively. This chapter +describes the Source Directory and gives information about those files +and directories. + +For information on how to establish a local Source Directory on your +development system, see the +":ref:`dev-manual/dev-manual-start:locating yocto project source files`" +section in the Yocto Project Development Tasks Manual. + +.. note:: + + The OpenEmbedded build system does not support file or directory + names that contain spaces. Be sure that the Source Directory you use + does not contain these types of names. + +.. _structure-core: + +Top-Level Core Components +========================= + +This section describes the top-level components of the :term:`Source Directory`. + +.. _structure-core-bitbake: + +``bitbake/`` +------------ + +This directory includes a copy of BitBake for ease of use. The copy +usually matches the current stable BitBake release from the BitBake +project. BitBake, a :term:`Metadata` interpreter, reads the +Yocto Project Metadata and runs the tasks defined by that data. Failures +are usually caused by errors in your Metadata and not from BitBake +itself; consequently, most users do not need to worry about BitBake. + +When you run the ``bitbake`` command, the main BitBake executable (which +resides in the ``bitbake/bin/`` directory) starts. Sourcing the +environment setup script (i.e. :ref:`structure-core-script`) places +the ``scripts/`` and ``bitbake/bin/`` directories (in that order) into +the shell's ``PATH`` environment variable. + +For more information on BitBake, see the :doc:`BitBake User Manual +<bitbake:index>`. + +.. _structure-core-build: + +``build/`` +---------- + +This directory contains user configuration files and the output +generated by the OpenEmbedded build system in its standard configuration +where the source tree is combined with the output. The :term:`Build Directory` +is created initially when you ``source`` +the OpenEmbedded build environment setup script (i.e. +:ref:`structure-core-script`). + +It is also possible to place output and configuration files in a +directory separate from the :term:`Source Directory` by +providing a directory name when you ``source`` the setup script. For +information on separating output from your local Source Directory files +(commonly described as an "out of tree" build), see the +":ref:`structure-core-script`" section. + +.. _handbook: + +``documentation/`` +------------------ + +This directory holds the source for the Yocto Project documentation as +well as templates and tools that allow you to generate PDF and HTML +versions of the manuals. Each manual is contained in its own sub-folder; +for example, the files for this reference manual reside in the +``ref-manual/`` directory. + +.. _structure-core-meta: + +``meta/`` +--------- + +This directory contains the minimal, underlying OpenEmbedded-Core +metadata. The directory holds recipes, common classes, and machine +configuration for strictly emulated targets (``qemux86``, ``qemuarm``, +and so forth.) + +.. _structure-core-meta-poky: + +``meta-poky/`` +-------------- + +Designed above the ``meta/`` content, this directory adds just enough +metadata to define the Poky reference distribution. + +.. _structure-core-meta-yocto-bsp: + +``meta-yocto-bsp/`` +------------------- + +This directory contains the Yocto Project reference hardware Board +Support Packages (BSPs). For more information on BSPs, see the +:doc:`../bsp-guide/bsp-guide`. + +.. _structure-meta-selftest: + +``meta-selftest/`` +------------------ + +This directory adds additional recipes and append files used by the +OpenEmbedded selftests to verify the behavior of the build system. You +do not have to add this layer to your ``bblayers.conf`` file unless you +want to run the selftests. + +.. _structure-meta-skeleton: + +``meta-skeleton/`` +------------------ + +This directory contains template recipes for BSP and kernel development. + +.. _structure-core-scripts: + +``scripts/`` +------------ + +This directory contains various integration scripts that implement extra +functionality in the Yocto Project environment (e.g. QEMU scripts). The +:ref:`structure-core-script` script prepends this directory to the +shell's ``PATH`` environment variable. + +The ``scripts`` directory has useful scripts that assist in contributing +back to the Yocto Project, such as ``create-pull-request`` and +``send-pull-request``. + +.. _structure-core-script: + +``oe-init-build-env`` +--------------------- + +This script sets up the OpenEmbedded build environment. Running this +script with the ``source`` command in a shell makes changes to ``PATH`` +and sets other core BitBake variables based on the current working +directory. You need to run an environment setup script before running +BitBake commands. The script uses other scripts within the ``scripts`` +directory to do the bulk of the work. + +When you run this script, your Yocto Project environment is set up, a +:term:`Build Directory` is created, your working +directory becomes the Build Directory, and you are presented with some +simple suggestions as to what to do next, including a list of some +possible targets to build. Here is an example: +:: + + $ source oe-init-build-env + + ### Shell environment set up for builds. ### + + You can now run 'bitbake <target>' + + Common targets are: + core-image-minimal + core-image-sato + meta-toolchain + meta-ide-support + + You can also run generated qemu images with a command like 'runqemu qemux86-64' + +The default output of the ``oe-init-build-env`` script is from the +``conf-notes.txt`` file, which is found in the ``meta-poky`` directory +within the :term:`Source Directory`. If you design a +custom distribution, you can include your own version of this +configuration file to mention the targets defined by your distribution. +See the +":ref:`dev-manual/dev-manual-common-tasks:creating a custom template configuration directory`" +section in the Yocto Project Development Tasks Manual for more +information. + +By default, running this script without a Build Directory argument +creates the ``build/`` directory in your current working directory. If +you provide a Build Directory argument when you ``source`` the script, +you direct the OpenEmbedded build system to create a Build Directory of +your choice. For example, the following command creates a Build +Directory named ``mybuilds/`` that is outside of the :term:`Source Directory`: +:: + + $ source OE_INIT_FILE ~/mybuilds + +The OpenEmbedded build system uses the template configuration files, which +are found by default in the ``meta-poky/conf/`` directory in the Source +Directory. See the +":ref:`dev-manual/dev-manual-common-tasks:creating a custom template configuration directory`" +section in the Yocto Project Development Tasks Manual for more +information. + +.. note:: + + The OpenEmbedded build system does not support file or directory + names that contain spaces. If you attempt to run the + OE_INIT_FILE + script from a Source Directory that contains spaces in either the + filenames or directory names, the script returns an error indicating + no such file or directory. Be sure to use a Source Directory free of + names containing spaces. + +.. _structure-basic-top-level: + +``LICENSE, README, and README.hardware`` +---------------------------------------- + +These files are standard top-level files. + +.. _structure-build: + +The Build Directory - ``build/`` +================================ + +The OpenEmbedded build system creates the :term:`Build Directory` +when you run the build environment setup +script :ref:`structure-core-script`. If you do not give the Build +Directory a specific name when you run the setup script, the name +defaults to ``build/``. + +For subsequent parsing and processing, the name of the Build directory +is available via the :term:`TOPDIR` variable. + +.. _structure-build-buildhistory: + +``build/buildhistory/`` +----------------------- + +The OpenEmbedded build system creates this directory when you enable +build history via the ``buildhistory`` class file. The directory +organizes build information into image, packages, and SDK +subdirectories. For information on the build history feature, see the +":ref:`dev-manual/dev-manual-common-tasks:maintaining build output quality`" +section in the Yocto Project Development Tasks Manual. + +.. _structure-build-conf-local.conf: + +``build/conf/local.conf`` +------------------------- + +This configuration file contains all the local user configurations for +your build environment. The ``local.conf`` file contains documentation +on the various configuration options. Any variable set here overrides +any variable set elsewhere within the environment unless that variable +is hard-coded within a file (e.g. by using '=' instead of '?='). Some +variables are hard-coded for various reasons but such variables are +relatively rare. + +At a minimum, you would normally edit this file to select the target +``MACHINE``, which package types you wish to use +(:term:`PACKAGE_CLASSES`), and the location from +which you want to access downloaded files (``DL_DIR``). + +If ``local.conf`` is not present when you start the build, the +OpenEmbedded build system creates it from ``local.conf.sample`` when you +``source`` the top-level build environment setup script +:ref:`structure-core-script`. + +The source ``local.conf.sample`` file used depends on the +``$TEMPLATECONF`` script variable, which defaults to ``meta-poky/conf/`` +when you are building from the Yocto Project development environment, +and to ``meta/conf/`` when you are building from the OpenEmbedded-Core +environment. Because the script variable points to the source of the +``local.conf.sample`` file, this implies that you can configure your +build environment from any layer by setting the variable in the +top-level build environment setup script as follows: +:: + + TEMPLATECONF=your_layer/conf + +Once the build process gets the sample +file, it uses ``sed`` to substitute final +``${``\ :term:`OEROOT`\ ``}`` values for all +``##OEROOT##`` values. + +.. note:: + + You can see how the + TEMPLATECONF + variable is used by looking at the + scripts/oe-setup-builddir + script in the + Source Directory + . You can find the Yocto Project version of the + local.conf.sample + file in the + meta-poky/conf + directory. + +.. _structure-build-conf-bblayers.conf: + +``build/conf/bblayers.conf`` +---------------------------- + +This configuration file defines +:ref:`layers <dev-manual/dev-manual-common-tasks:understanding and creating layers>`, +which are directory trees, traversed (or walked) by BitBake. The +``bblayers.conf`` file uses the :term:`BBLAYERS` +variable to list the layers BitBake tries to find. + +If ``bblayers.conf`` is not present when you start the build, the +OpenEmbedded build system creates it from ``bblayers.conf.sample`` when +you ``source`` the top-level build environment setup script (i.e. +:ref:`structure-core-script`). + +As with the ``local.conf`` file, the source ``bblayers.conf.sample`` +file used depends on the ``$TEMPLATECONF`` script variable, which +defaults to ``meta-poky/conf/`` when you are building from the Yocto +Project development environment, and to ``meta/conf/`` when you are +building from the OpenEmbedded-Core environment. Because the script +variable points to the source of the ``bblayers.conf.sample`` file, this +implies that you can base your build from any layer by setting the +variable in the top-level build environment setup script as follows: +:: + + TEMPLATECONF=your_layer/conf + +Once the build process gets the sample file, it uses ``sed`` to substitute final +``${``\ :term:`OEROOT`\ ``}`` values for all ``##OEROOT##`` values. + +.. note:: + + You can see how the + TEMPLATECONF + variable + scripts/oe-setup-builddir + script in the + Source Directory + . You can find the Yocto Project version of the + bblayers.conf.sample + file in the + meta-poky/conf/ + directory. + +.. _structure-build-conf-sanity_info: + +``build/cache/sanity_info`` +--------------------------- + +This file indicates the state of the sanity checks and is created during +the build. + +.. _structure-build-downloads: + +``build/downloads/`` +-------------------- + +This directory contains downloaded upstream source tarballs. You can +reuse the directory for multiple builds or move the directory to another +location. You can control the location of this directory through the +``DL_DIR`` variable. + +.. _structure-build-sstate-cache: + +``build/sstate-cache/`` +----------------------- + +This directory contains the shared state cache. You can reuse the +directory for multiple builds or move the directory to another location. +You can control the location of this directory through the +``SSTATE_DIR`` variable. + +.. _structure-build-tmp: + +``build/tmp/`` +-------------- + +The OpenEmbedded build system creates and uses this directory for all +the build system's output. The :term:`TMPDIR` variable +points to this directory. + +BitBake creates this directory if it does not exist. As a last resort, +to clean up a build and start it from scratch (other than the +downloads), you can remove everything in the ``tmp`` directory or get +rid of the directory completely. If you do, you should also completely +remove the ``build/sstate-cache`` directory. + +.. _structure-build-tmp-buildstats: + +``build/tmp/buildstats/`` +------------------------- + +This directory stores the build statistics. + +.. _structure-build-tmp-cache: + +``build/tmp/cache/`` +-------------------- + +When BitBake parses the metadata (recipes and configuration files), it +caches the results in ``build/tmp/cache/`` to speed up future builds. +The results are stored on a per-machine basis. + +During subsequent builds, BitBake checks each recipe (together with, for +example, any files included or appended to it) to see if they have been +modified. Changes can be detected, for example, through file +modification time (mtime) changes and hashing of file contents. If no +changes to the file are detected, then the parsed result stored in the +cache is reused. If the file has changed, it is reparsed. + +.. _structure-build-tmp-deploy: + +``build/tmp/deploy/`` +--------------------- + +This directory contains any "end result" output from the OpenEmbedded +build process. The :term:`DEPLOY_DIR` variable points +to this directory. For more detail on the contents of the ``deploy`` +directory, see the +":ref:`images-dev-environment`" and +":ref:`sdk-dev-environment`" sections in the Yocto +Project Overview and Concepts Manual. + +.. _structure-build-tmp-deploy-deb: + +``build/tmp/deploy/deb/`` +------------------------- + +This directory receives any ``.deb`` packages produced by the build +process. The packages are sorted into feeds for different architecture +types. + +.. _structure-build-tmp-deploy-rpm: + +``build/tmp/deploy/rpm/`` +------------------------- + +This directory receives any ``.rpm`` packages produced by the build +process. The packages are sorted into feeds for different architecture +types. + +.. _structure-build-tmp-deploy-ipk: + +``build/tmp/deploy/ipk/`` +------------------------- + +This directory receives ``.ipk`` packages produced by the build process. + +.. _structure-build-tmp-deploy-licenses: + +``build/tmp/deploy/licenses/`` +------------------------------ + +This directory receives package licensing information. For example, the +directory contains sub-directories for ``bash``, ``busybox``, and +``glibc`` (among others) that in turn contain appropriate ``COPYING`` +license files with other licensing information. For information on +licensing, see the +":ref:`dev-manual/dev-manual-common-tasks:maintaining open source license compliance during your product's lifecycle`" +section in the Yocto Project Development Tasks Manual. + +.. _structure-build-tmp-deploy-images: + +``build/tmp/deploy/images/`` +---------------------------- + +This directory is populated with the basic output objects of the build +(think of them as the "generated artifacts" of the build process), +including things like the boot loader image, kernel, root filesystem and +more. If you want to flash the resulting image from a build onto a +device, look here for the necessary components. + +Be careful when deleting files in this directory. You can safely delete +old images from this directory (e.g. ``core-image-*``). However, the +kernel (``*zImage*``, ``*uImage*``, etc.), bootloader and other +supplementary files might be deployed here prior to building an image. +Because these files are not directly produced from the image, if you +delete them they will not be automatically re-created when you build the +image again. + +If you do accidentally delete files here, you will need to force them to +be re-created. In order to do that, you will need to know the target +that produced them. For example, these commands rebuild and re-create +the kernel files: +:: + + $ bitbake -c clean virtual/kernel + $ bitbake virtual/kernel + +.. _structure-build-tmp-deploy-sdk: + +``build/tmp/deploy/sdk/`` +------------------------- + +The OpenEmbedded build system creates this directory to hold toolchain +installer scripts which, when executed, install the sysroot that matches +your target hardware. You can find out more about these installers in +the ":ref:`sdk-manual/sdk-appendix-obtain:building an sdk installer`" +section in the Yocto Project Application Development and the Extensible +Software Development Kit (eSDK) manual. + +.. _structure-build-tmp-sstate-control: + +``build/tmp/sstate-control/`` +----------------------------- + +The OpenEmbedded build system uses this directory for the shared state +manifest files. The shared state code uses these files to record the +files installed by each sstate task so that the files can be removed +when cleaning the recipe or when a newer version is about to be +installed. The build system also uses the manifests to detect and +produce a warning when files from one task are overwriting those from +another. + +.. _structure-build-tmp-sysroots-components: + +``build/tmp/sysroots-components/`` +---------------------------------- + +This directory is the location of the sysroot contents that the task +:ref:`ref-tasks-prepare_recipe_sysroot` +links or copies into the recipe-specific sysroot for each recipe listed +in :term:`DEPENDS`. Population of this directory is +handled through shared state, while the path is specified by the +:term:`COMPONENTS_DIR` variable. Apart from a few +unusual circumstances, handling of the ``sysroots-components`` directory +should be automatic, and recipes should not directly reference +``build/tmp/sysroots-components``. + +.. _structure-build-tmp-sysroots: + +``build/tmp/sysroots/`` +----------------------- + +Previous versions of the OpenEmbedded build system used to create a +global shared sysroot per machine along with a native sysroot. Beginning +with the DISTRO version of the Yocto Project, sysroots exist in +recipe-specific :term:`WORKDIR` directories. Thus, the +``build/tmp/sysroots/`` directory is unused. + +.. note:: + + The + build/tmp/sysroots/ + directory can still be populated using the + bitbake build-sysroots + command and can be used for compatibility in some cases. However, in + general it is not recommended to populate this directory. Individual + recipe-specific sysroots should be used. + +.. _structure-build-tmp-stamps: + +``build/tmp/stamps/`` +--------------------- + +This directory holds information that BitBake uses for accounting +purposes to track what tasks have run and when they have run. The +directory is sub-divided by architecture, package name, and version. +Following is an example: +stamps/all-poky-linux/distcc-config/1.0-r0.do_build-2fdd....2do Although +the files in the directory are empty of data, BitBake uses the filenames +and timestamps for tracking purposes. + +For information on how BitBake uses stamp files to determine if a task +should be rerun, see the +":ref:`overview-manual/overview-manual-concepts:stamp files and the rerunning of tasks`" +section in the Yocto Project Overview and Concepts Manual. + +.. _structure-build-tmp-log: + +``build/tmp/log/`` +------------------ + +This directory contains general logs that are not otherwise placed using +the package's ``WORKDIR``. Examples of logs are the output from the +``do_check_pkg`` or ``do_distro_check`` tasks. Running a build does not +necessarily mean this directory is created. + +.. _structure-build-tmp-work: + +``build/tmp/work/`` +------------------- + +This directory contains architecture-specific work sub-directories for +packages built by BitBake. All tasks execute from the appropriate work +directory. For example, the source for a particular package is unpacked, +patched, configured and compiled all within its own work directory. +Within the work directory, organization is based on the package group +and version for which the source is being compiled as defined by the +:term:`WORKDIR`. + +It is worth considering the structure of a typical work directory. As an +example, consider ``linux-yocto-kernel-3.0`` on the machine ``qemux86`` +built within the Yocto Project. For this package, a work directory of +``tmp/work/qemux86-poky-linux/linux-yocto/3.0+git1+<.....>``, referred +to as the ``WORKDIR``, is created. Within this directory, the source is +unpacked to ``linux-qemux86-standard-build`` and then patched by Quilt. +(See the ":ref:`using-a-quilt-workflow`" section in +the Yocto Project Development Tasks Manual for more information.) Within +the ``linux-qemux86-standard-build`` directory, standard Quilt +directories ``linux-3.0/patches`` and ``linux-3.0/.pc`` are created, and +standard Quilt commands can be used. + +There are other directories generated within ``WORKDIR``. The most +important directory is ``WORKDIR/temp/``, which has log files for each +task (``log.do_*.pid``) and contains the scripts BitBake runs for each +task (``run.do_*.pid``). The ``WORKDIR/image/`` directory is where "make +install" places its output that is then split into sub-packages within +``WORKDIR/packages-split/``. + +.. _structure-build-tmp-work-tunearch-recipename-version: + +``build/tmp/work/tunearch/recipename/version/`` +----------------------------------------------- + +The recipe work directory - ``${WORKDIR}``. + +As described earlier in the +"```build/tmp/sysroots/`` <#structure-build-tmp-sysroots>`__" section, +beginning with the DISTRO release of the Yocto Project, the OpenEmbedded +build system builds each recipe in its own work directory (i.e. +:term:`WORKDIR`). The path to the work directory is +constructed using the architecture of the given build (e.g. +:term:`TUNE_PKGARCH`, +:term:`MACHINE_ARCH`, or "allarch"), the recipe +name, and the version of the recipe (i.e. +:term:`PE`\ ``:``\ :term:`PV`\ ``-``\ :term:`PR`). + +A number of key subdirectories exist within each recipe work directory: + +- ``${WORKDIR}/temp``: Contains the log files of each task executed for + this recipe, the "run" files for each executed task, which contain + the code run, and a ``log.task_order`` file, which lists the order in + which tasks were executed. + +- ``${WORKDIR}/image``: Contains the output of the + :ref:`ref-tasks-install` task, which corresponds to + the ``${``\ :term:`D`\ ``}`` variable in that task. + +- ``${WORKDIR}/pseudo``: Contains the pseudo database and log for any + tasks executed under pseudo for the recipe. + +- ``${WORKDIR}/sysroot-destdir``: Contains the output of the + :ref:`ref-tasks-populate_sysroot` task. + +- ``${WORKDIR}/package``: Contains the output of the + :ref:`ref-tasks-package` task before the output is + split into individual packages. + +- ``${WORKDIR}/packages-split``: Contains the output of the + ``do_package`` task after the output has been split into individual + packages. Subdirectories exist for each individual package created by + the recipe. + +- ``${WORKDIR}/recipe-sysroot``: A directory populated with the target + dependencies of the recipe. This directory looks like the target + filesystem and contains libraries that the recipe might need to link + against (e.g. the C library). + +- ``${WORKDIR}/recipe-sysroot-native``: A directory populated with the + native dependencies of the recipe. This directory contains the tools + the recipe needs to build (e.g. the compiler, Autoconf, libtool, and + so forth). + +- ``${WORKDIR}/build``: This subdirectory applies only to recipes that + support builds where the source is separate from the build artifacts. + The OpenEmbedded build system uses this directory as a separate build + directory (i.e. ``${``\ :term:`B`\ ``}``). + +.. _structure-build-work-shared: + +``build/tmp/work-shared/`` +-------------------------- + +For efficiency, the OpenEmbedded build system creates and uses this +directory to hold recipes that share a work directory with other +recipes. In practice, this is only used for ``gcc`` and its variants +(e.g. ``gcc-cross``, ``libgcc``, ``gcc-runtime``, and so forth). + +.. _structure-meta: + +The Metadata - ``meta/`` +======================== + +As mentioned previously, :term:`Metadata` is the core of the +Yocto Project. Metadata has several important subdivisions: + +.. _structure-meta-classes: + +``meta/classes/`` +----------------- + +This directory contains the ``*.bbclass`` files. Class files are used to +abstract common code so it can be reused by multiple packages. Every +package inherits the ``base.bbclass`` file. Examples of other important +classes are ``autotools.bbclass``, which in theory allows any +Autotool-enabled package to work with the Yocto Project with minimal +effort. Another example is ``kernel.bbclass`` that contains common code +and functions for working with the Linux kernel. Functions like image +generation or packaging also have their specific class files such as +``image.bbclass``, ``rootfs_*.bbclass`` and ``package*.bbclass``. + +For reference information on classes, see the +":ref:`ref-manual/ref-classes:Classes`" chapter. + +.. _structure-meta-conf: + +``meta/conf/`` +-------------- + +This directory contains the core set of configuration files that start +from ``bitbake.conf`` and from which all other configuration files are +included. See the include statements at the end of the ``bitbake.conf`` +file and you will note that even ``local.conf`` is loaded from there. +While ``bitbake.conf`` sets up the defaults, you can often override +these by using the (``local.conf``) file, machine file or the +distribution configuration file. + +.. _structure-meta-conf-machine: + +``meta/conf/machine/`` +---------------------- + +This directory contains all the machine configuration files. If you set +``MACHINE = "qemux86"``, the OpenEmbedded build system looks for a +``qemux86.conf`` file in this directory. The ``include`` directory +contains various data common to multiple machines. If you want to add +support for a new machine to the Yocto Project, look in this directory. + +.. _structure-meta-conf-distro: + +``meta/conf/distro/`` +--------------------- + +The contents of this directory controls any distribution-specific +configurations. For the Yocto Project, the ``defaultsetup.conf`` is the +main file here. This directory includes the versions and the ``SRCDATE`` +definitions for applications that are configured here. An example of an +alternative configuration might be ``poky-bleeding.conf``. Although this +file mainly inherits its configuration from Poky. + +.. _structure-meta-conf-machine-sdk: + +``meta/conf/machine-sdk/`` +-------------------------- + +The OpenEmbedded build system searches this directory for configuration +files that correspond to the value of +:term:`SDKMACHINE`. By default, 32-bit and 64-bit x86 +files ship with the Yocto Project that support some SDK hosts. However, +it is possible to extend that support to other SDK hosts by adding +additional configuration files in this subdirectory within another +layer. + +.. _structure-meta-files: + +``meta/files/`` +--------------- + +This directory contains common license files and several text files used +by the build system. The text files contain minimal device information +and lists of files and directories with known permissions. + +.. _structure-meta-lib: + +``meta/lib/`` +------------- + +This directory contains OpenEmbedded Python library code used during the +build process. + +.. _structure-meta-recipes-bsp: + +``meta/recipes-bsp/`` +--------------------- + +This directory contains anything linking to specific hardware or +hardware configuration information such as "u-boot" and "grub". + +.. _structure-meta-recipes-connectivity: + +``meta/recipes-connectivity/`` +------------------------------ + +This directory contains libraries and applications related to +communication with other devices. + +.. _structure-meta-recipes-core: + +``meta/recipes-core/`` +---------------------- + +This directory contains what is needed to build a basic working Linux +image including commonly used dependencies. + +.. _structure-meta-recipes-devtools: + +``meta/recipes-devtools/`` +-------------------------- + +This directory contains tools that are primarily used by the build +system. The tools, however, can also be used on targets. + +.. _structure-meta-recipes-extended: + +``meta/recipes-extended/`` +-------------------------- + +This directory contains non-essential applications that add features +compared to the alternatives in core. You might need this directory for +full tool functionality or for Linux Standard Base (LSB) compliance. + +.. _structure-meta-recipes-gnome: + +``meta/recipes-gnome/`` +----------------------- + +This directory contains all things related to the GTK+ application +framework. + +.. _structure-meta-recipes-graphics: + +``meta/recipes-graphics/`` +-------------------------- + +This directory contains X and other graphically related system +libraries. + +.. _structure-meta-recipes-kernel: + +``meta/recipes-kernel/`` +------------------------ + +This directory contains the kernel and generic applications and +libraries that have strong kernel dependencies. + +.. _structure-meta-recipes-lsb4: + +``meta/recipes-lsb4/`` +---------------------- + +This directory contains recipes specifically added to support the Linux +Standard Base (LSB) version 4.x. + +.. _structure-meta-recipes-multimedia: + +``meta/recipes-multimedia/`` +---------------------------- + +This directory contains codecs and support utilities for audio, images +and video. + +.. _structure-meta-recipes-rt: + +``meta/recipes-rt/`` +-------------------- + +This directory contains package and image recipes for using and testing +the ``PREEMPT_RT`` kernel. + +.. _structure-meta-recipes-sato: + +``meta/recipes-sato/`` +---------------------- + +This directory contains the Sato demo/reference UI/UX and its associated +applications and configuration data. + +.. _structure-meta-recipes-support: + +``meta/recipes-support/`` +------------------------- + +This directory contains recipes used by other recipes, but that are not +directly included in images (i.e. dependencies of other recipes). + +.. _structure-meta-site: + +``meta/site/`` +-------------- + +This directory contains a list of cached results for various +architectures. Because certain "autoconf" test results cannot be +determined when cross-compiling due to the tests not able to run on a +live system, the information in this directory is passed to "autoconf" +for the various architectures. + +.. _structure-meta-recipes-txt: + +``meta/recipes.txt`` +-------------------- + +This file is a description of the contents of ``recipes-*``. diff --git a/poky/documentation/ref-manual/ref-structure.xml b/poky/documentation/ref-manual/ref-structure.xml index 27f17dd91..8588e9c2d 100644 --- a/poky/documentation/ref-manual/ref-structure.xml +++ b/poky/documentation/ref-manual/ref-structure.xml @@ -1,6 +1,7 @@ <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > +<!--SPDX-License-Identifier: CC-BY-2.0-UK--> <chapter id='ref-structure'> diff --git a/poky/documentation/ref-manual/ref-style.css b/poky/documentation/ref-manual/ref-style.css index 7077e4b70..622ceb8f7 100644 --- a/poky/documentation/ref-manual/ref-style.css +++ b/poky/documentation/ref-manual/ref-style.css @@ -1,4 +1,7 @@ /* + + SPDX-License-Identifier: CC-BY-2.0-UK + Generic XHTML / DocBook XHTML CSS Stylesheet. Browser wrangling and typographic design by diff --git a/poky/documentation/ref-manual/ref-system-requirements.rst b/poky/documentation/ref-manual/ref-system-requirements.rst new file mode 100644 index 000000000..56218e4eb --- /dev/null +++ b/poky/documentation/ref-manual/ref-system-requirements.rst @@ -0,0 +1,437 @@ +.. SPDX-License-Identifier: CC-BY-2.0-UK + +******************* +System Requirements +******************* + +Welcome to the Yocto Project Reference Manual! This manual provides +reference information for the current release of the Yocto Project, and +is most effectively used after you have an understanding of the basics +of the Yocto Project. The manual is neither meant to be read as a +starting point to the Yocto Project, nor read from start to finish. +Rather, use this manual to find variable definitions, class +descriptions, and so forth as needed during the course of using the +Yocto Project. + +For introductory information on the Yocto Project, see the +:yocto_home:`Yocto Project Website <>` and the +":ref:`overview-manual/overview-manual-development-environment:the yocto project development environment`" +chapter in the Yocto Project Overview and Concepts Manual. + +If you want to use the Yocto Project to quickly build an image without +having to understand concepts, work through the +:doc:`../brief-yoctoprojectqs/brief-yoctoprojectqs` document. You can find "how-to" +information in the :doc:`../dev-manual/dev-manual`. You can find Yocto Project overview +and conceptual information in the :doc:`../overview-manual/overview-manual`. + +.. note:: + + For more information about the Yocto Project Documentation set, see + the " + Links and Related Documentation + " section. + +.. _detailed-supported-distros: + +Supported Linux Distributions +============================= + +Currently, the Yocto Project is supported on the following +distributions: + +- Ubuntu 16.04 (LTS) + +- Ubuntu 18.04 (LTS) + +- Ubuntu 20.04 + +- Fedora 30 + +- Fedora 31 + +- Fedora 32 + +- CentOS 7.x + +- CentOS 8.x + +- Debian GNU/Linux 8.x (Jessie) + +- Debian GNU/Linux 9.x (Stretch) + +- Debian GNU/Linux 10.x (Buster) + +- OpenSUSE Leap 15.1 + + +.. note:: + + - While the Yocto Project Team attempts to ensure all Yocto Project + releases are one hundred percent compatible with each officially + supported Linux distribution, instances might exist where you + encounter a problem while using the Yocto Project on a specific + distribution. + + - Yocto Project releases are tested against the stable Linux + distributions in the above list. The Yocto Project should work + on other distributions but validation is not performed against + them. + + - In particular, the Yocto Project does not support and currently + has no plans to support rolling-releases or development + distributions due to their constantly changing nature. We welcome + patches and bug reports, but keep in mind that our priority is on + the supported platforms listed below. + + - You may use Windows Subsystem For Linux v2 to set up a build host + using Windows 10, but validation is not performed against build + hosts using WSLv2. + + - The Yocto Project is not compatible with WSLv1, it is + compatible but not officially supported nor validated with + WSLv2, if you still decide to use WSL please upgrade to WSLv2. + + - If you encounter problems, please go to `Yocto Project + Bugzilla <http://bugzilla.yoctoproject.org>`__ and submit a bug. We are + interested in hearing about your experience. For information on + how to submit a bug, see the Yocto Project + :yocto_wiki:`Bugzilla wiki page </wiki/Bugzilla_Configuration_and_Bug_Tracking>` + and the ":ref:`dev-manual/dev-manual-common-tasks:submitting a defect against the yocto project`" + section in the Yocto Project Development Tasks Manual. + + +Required Packages for the Build Host +==================================== + +The list of packages you need on the host development system can be +large when covering all build scenarios using the Yocto Project. This +section describes required packages according to Linux distribution and +function. + +.. _ubuntu-packages: + +Ubuntu and Debian +----------------- + +The following list shows the required packages by function given a +supported Ubuntu or Debian Linux distribution: + +.. note:: + + - If your build system has the ``oss4-dev`` package installed, you + might experience QEMU build failures due to the package installing + its own custom ``/usr/include/linux/soundcard.h`` on the Debian + system. If you run into this situation, either of the following + solutions exist: + :: + + $ sudo apt-get build-dep qemu + $ sudo apt-get remove oss4-dev + + - For Debian-8, ``python3-git`` and ``pylint3`` are no longer + available via ``apt-get``. + :: + + $ sudo pip3 install GitPython pylint==1.9.5 + +- *Essentials:* Packages needed to build an image on a headless system: + :: + + $ sudo apt-get install &UBUNTU_HOST_PACKAGES_ESSENTIAL; + +- *Documentation:* Packages needed if you are going to build out the + Yocto Project documentation manuals: + :: + + $ sudo apt-get install make xsltproc docbook-utils fop dblatex xmlto + +Fedora Packages +--------------- + +The following list shows the required packages by function given a +supported Fedora Linux distribution: + +- *Essentials:* Packages needed to build an image for a headless + system: + :: + + $ sudo dnf install &FEDORA_HOST_PACKAGES_ESSENTIAL; + +- *Documentation:* Packages needed if you are going to build out the + Yocto Project documentation manuals: + :: + + $ sudo dnf install docbook-style-dsssl docbook-style-xsl \ + docbook-dtds docbook-utils fop libxslt dblatex xmlto + +openSUSE Packages +----------------- + +The following list shows the required packages by function given a +supported openSUSE Linux distribution: + +- *Essentials:* Packages needed to build an image for a headless + system: + :: + + $ sudo zypper install &OPENSUSE_HOST_PACKAGES_ESSENTIAL; + +- *Documentation:* Packages needed if you are going to build out the + Yocto Project documentation manuals: $ sudo zypper install dblatex + xmlto + +CentOS-7 Packages +----------------- + +The following list shows the required packages by function given a +supported CentOS-7 Linux distribution: + +- *Essentials:* Packages needed to build an image for a headless + system: + :: + + $ sudo yum install &CENTOS7_HOST_PACKAGES_ESSENTIAL; + + .. note:: + + - Extra Packages for Enterprise Linux (i.e. ``epel-release``) is + a collection of packages from Fedora built on RHEL/CentOS for + easy installation of packages not included in enterprise Linux + by default. You need to install these packages separately. + + - The ``makecache`` command consumes additional Metadata from + ``epel-release``. + +- *Documentation:* Packages needed if you are going to build out the + Yocto Project documentation manuals: + :: + + $ sudo yum install docbook-style-dsssl docbook-style-xsl \ + docbook-dtds docbook-utils fop libxslt dblatex xmlto + +CentOS-8 Packages +----------------- + +The following list shows the required packages by function given a +supported CentOS-8 Linux distribution: + +- *Essentials:* Packages needed to build an image for a headless + system: + :: + + $ sudo dnf install &CENTOS8_HOST_PACKAGES_ESSENTIAL; + + .. note:: + + - Extra Packages for Enterprise Linux (i.e. ``epel-release``) is + a collection of packages from Fedora built on RHEL/CentOS for + easy installation of packages not included in enterprise Linux + by default. You need to install these packages separately. + + - The ``PowerTools`` repo provides additional packages such as + ``rpcgen`` and ``texinfo``. + + - The ``makecache`` command consumes additional Metadata from + ``epel-release``. + +- *Documentation:* Packages needed if you are going to build out the + Yocto Project documentation manuals: + :: + + $ sudo dnf install docbook-style-dsssl docbook-style-xsl \\ + docbook-dtds docbook-utils fop libxslt dblatex xmlto + +Required Git, tar, Python and gcc Versions +========================================== + +In order to use the build system, your host development system must meet +the following version requirements for Git, tar, and Python: + +- Git 1.8.3.1 or greater + +- tar 1.28 or greater + +- Python 3.5.0 or greater + +If your host development system does not meet all these requirements, +you can resolve this by installing a ``buildtools`` tarball that +contains these tools. You can get the tarball one of two ways: download +a pre-built tarball or use BitBake to build the tarball. + +In addition, your host development system must meet the following +version requirement for gcc: + +- gcc 5.0 or greater + +If your host development system does not meet this requirement, you can +resolve this by installing a ``buildtools-extended`` tarball that +contains additional tools, the equivalent of ``buildtools-essential``. + +Installing a Pre-Built ``buildtools`` Tarball with ``install-buildtools`` script +-------------------------------------------------------------------------------- + +The ``install-buildtools`` script is the easiest of the three methods by +which you can get these tools. It downloads a pre-built buildtools +installer and automatically installs the tools for you: + +1. Execute the ``install-buildtools`` script. Here is an example: + :: + + $ cd poky + $ scripts/install-buildtools --without-extended-buildtools \ + --base-url https://downloads.yoctoproject.org/releases/yocto \ + --release yocto-&DISTRO; \ + --installer-version &DISTRO; + + During execution, the buildtools tarball will be downloaded, the + checksum of the download will be verified, the installer will be run + for you, and some basic checks will be run to to make sure the + installation is functional. + + To avoid the need of ``sudo`` privileges, the ``install-buildtools`` + script will by default tell the installer to install in: + :: + + /path/to/poky/buildtools + + If your host development system needs the additional tools provided + in the ``buildtools-extended`` tarball, you can instead execute the + ``install-buildtools`` script with the default parameters: + :: + + $ cd poky + $ scripts/install-buildtools + +2. Source the tools environment setup script by using a command like the + following: + :: + + $ source /path/to/poky/buildtools/environment-setup-x86_64-pokysdk-linux + + Of course, you need to supply your installation directory and be sure to + use the right file (i.e. i586 or x86_64). + + After you have sourced the setup script, the tools are added to + ``PATH`` and any other environment variables required to run the + tools are initialized. The results are working versions versions of + Git, tar, Python and ``chrpath``. And in the case of the + ``buildtools-extended`` tarball, additional working versions of tools + including ``gcc``, ``make`` and the other tools included in + ``packagegroup-core-buildessential``. + +Downloading a Pre-Built ``buildtools`` Tarball +---------------------------------------------- + +Downloading and running a pre-built buildtools installer is the easiest +of the two methods by which you can get these tools: + +1. Locate and download the ``*.sh`` at &YOCTO_RELEASE_DL_URL;/buildtools/ + +2. Execute the installation script. Here is an example for the + traditional installer: + :: + + $ sh ~/Downloads/x86_64-buildtools-nativesdk-standalone-DISTRO.sh + + Here is an example for the extended installer: + :: + + $ sh ~/Downloads/x86_64-buildtools-extended-nativesdk-standalone-DISTRO.sh + + During execution, a prompt appears that allows you to choose the + installation directory. For example, you could choose the following: + /home/your-username/buildtools + +3. Source the tools environment setup script by using a command like the + following: + :: + + $ source /home/your_username/buildtools/environment-setup-i586-poky-linux + + Of + course, you need to supply your installation directory and be sure to + use the right file (i.e. i585 or x86-64). + + After you have sourced the setup script, the tools are added to + ``PATH`` and any other environment variables required to run the + tools are initialized. The results are working versions versions of + Git, tar, Python and ``chrpath``. And in the case of the + ``buildtools-extended`` tarball, additional working versions of tools + including ``gcc``, ``make`` and the other tools included in + ``packagegroup-core-buildessential``. + +Building Your Own ``buildtools`` Tarball +---------------------------------------- + +Building and running your own buildtools installer applies only when you +have a build host that can already run BitBake. In this case, you use +that machine to build the ``.sh`` file and then take steps to transfer +and run it on a machine that does not meet the minimal Git, tar, and +Python (or gcc) requirements. + +Here are the steps to take to build and run your own buildtools +installer: + +1. On the machine that is able to run BitBake, be sure you have set up + your build environment with the setup script + (:ref:`structure-core-script`). + +2. Run the BitBake command to build the tarball: + :: + + $ bitbake buildtools-tarball + + or run the BitBake command to build the extended tarball: + :: + + $ bitbake buildtools-extended-tarball + + .. note:: + + The + SDKMACHINE + variable in your + local.conf + file determines whether you build tools for a 32-bit or 64-bit + system. + + Once the build completes, you can find the ``.sh`` file that installs + the tools in the ``tmp/deploy/sdk`` subdirectory of the + :term:`Build Directory`. The installer file has the string + "buildtools" (or "buildtools-extended") in the name. + +3. Transfer the ``.sh`` file from the build host to the machine that + does not meet the Git, tar, or Python (or gcc) requirements. + +4. On the machine that does not meet the requirements, run the ``.sh`` + file to install the tools. Here is an example for the traditional + installer: + :: + + $ sh ~/Downloads/x86_64-buildtools-nativesdk-standalone-&DISTRO;.sh + + Here is an example for the extended installer: + :: + + $ sh ~/Downloads/x86_64-buildtools-extended-nativesdk-standalone-&DISTRO;.sh + + During execution, a prompt appears that allows you to choose the + installation directory. For example, you could choose the following: + /home/your_username/buildtools + +5. Source the tools environment setup script by using a command like the + following: + :: + + $ source /home/your_username/buildtools/environment-setup-x86_64-poky-linux + + Of course, you need to supply your installation directory and be sure to + use the right file (i.e. i586 or x86_64). + + After you have sourced the setup script, the tools are added to + ``PATH`` and any other environment variables required to run the + tools are initialized. The results are working versions versions of + Git, tar, Python and ``chrpath``. And in the case of the + ``buildtools-extended`` tarball, additional working versions of tools + including ``gcc``, ``make`` and the other tools included in + ``packagegroup-core-buildessential``. diff --git a/poky/documentation/ref-manual/ref-system-requirements.xml b/poky/documentation/ref-manual/ref-system-requirements.xml index 7a11ec2cf..ac8b0032d 100644 --- a/poky/documentation/ref-manual/ref-system-requirements.xml +++ b/poky/documentation/ref-manual/ref-system-requirements.xml @@ -1,6 +1,7 @@ <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > +<!--SPDX-License-Identifier: CC-BY-2.0-UK--> <chapter id='ref-manual-system-requirements'> <title>System Requirements</title> @@ -93,11 +94,12 @@ <itemizedlist> <listitem><para>Ubuntu 16.04 (LTS)</para></listitem> <listitem><para>Ubuntu 18.04 (LTS)</para></listitem> - <listitem><para>Ubuntu 19.04</para></listitem> - <listitem><para>Fedora 28</para></listitem> - <listitem><para>Fedora 29</para></listitem> + <listitem><para>Ubuntu 20.04</para></listitem> <listitem><para>Fedora 30</para></listitem> + <listitem><para>Fedora 31</para></listitem> + <listitem><para>Fedora 32</para></listitem> <listitem><para>CentOS 7.x</para></listitem> + <listitem><para>CentOS 8.x</para></listitem> <listitem><para>Debian GNU/Linux 8.x (Jessie)</para></listitem> <listitem><para>Debian GNU/Linux 9.x (Stretch)</para></listitem> <listitem><para>Debian GNU/Linux 10.x (Buster)</para></listitem> diff --git a/poky/documentation/ref-manual/ref-tasks.rst b/poky/documentation/ref-manual/ref-tasks.rst new file mode 100644 index 000000000..dcdff05dc --- /dev/null +++ b/poky/documentation/ref-manual/ref-tasks.rst @@ -0,0 +1,875 @@ +.. SPDX-License-Identifier: CC-BY-2.0-UK + +***** +Tasks +***** + +Tasks are units of execution for BitBake. Recipes (``.bb`` files) use +tasks to complete configuring, compiling, and packaging software. This +chapter provides a reference of the tasks defined in the OpenEmbedded +build system. + +Normal Recipe Build Tasks +========================= + +The following sections describe normal tasks associated with building a +recipe. For more information on tasks and dependencies, see the +":ref:`Tasks <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:tasks>`" and +":ref:`Dependencies <bitbake:bitbake-user-manual/bitbake-user-manual-execution:dependencies>`" sections in the +BitBake User Manual. + +.. _ref-tasks-build: + +``do_build`` +------------ + +The default task for all recipes. This task depends on all other normal +tasks required to build a recipe. + +.. _ref-tasks-compile: + +``do_compile`` +-------------- + +Compiles the source code. This task runs with the current working +directory set to ``${``\ :term:`B`\ ``}``. + +The default behavior of this task is to run the ``oe_runmake`` function +if a makefile (``Makefile``, ``makefile``, or ``GNUmakefile``) is found. +If no such file is found, the ``do_compile`` task does nothing. + +.. _ref-tasks-compile_ptest_base: + +``do_compile_ptest_base`` +------------------------- + +Compiles the runtime test suite included in the software being built. + +.. _ref-tasks-configure: + +``do_configure`` +---------------- + +Configures the source by enabling and disabling any build-time and +configuration options for the software being built. The task runs with +the current working directory set to ``${``\ :term:`B`\ ``}``. + +The default behavior of this task is to run ``oe_runmake clean`` if a +makefile (``Makefile``, ``makefile``, or ``GNUmakefile``) is found and +:term:`CLEANBROKEN` is not set to "1". If no such +file is found or the ``CLEANBROKEN`` variable is set to "1", the +``do_configure`` task does nothing. + +.. _ref-tasks-configure_ptest_base: + +``do_configure_ptest_base`` +--------------------------- + +Configures the runtime test suite included in the software being built. + +.. _ref-tasks-deploy: + +``do_deploy`` +------------- + +Writes output files that are to be deployed to +``${``\ :term:`DEPLOY_DIR_IMAGE`\ ``}``. The +task runs with the current working directory set to +``${``\ :term:`B`\ ``}``. + +Recipes implementing this task should inherit the +:ref:`deploy <ref-classes-deploy>` class and should write the output +to ``${``\ :term:`DEPLOYDIR`\ ``}``, which is not to be +confused with ``${DEPLOY_DIR}``. The ``deploy`` class sets up +``do_deploy`` as a shared state (sstate) task that can be accelerated +through sstate use. The sstate mechanism takes care of copying the +output from ``${DEPLOYDIR}`` to ``${DEPLOY_DIR_IMAGE}``. + +.. note:: + + Do not write the output directly to + ${DEPLOY_DIR_IMAGE} + , as this causes the sstate mechanism to malfunction. + +The ``do_deploy`` task is not added as a task by default and +consequently needs to be added manually. If you want the task to run +after :ref:`ref-tasks-compile`, you can add it by doing +the following: addtask deploy after do_compile Adding ``do_deploy`` +after other tasks works the same way. + +.. note:: + + You do not need to add + before do_build + to the + addtask + command (though it is harmless), because the + base + class contains the following: + :: + + do_build[recrdeptask] += "do_deploy" + + + See the " + Dependencies + " section in the BitBake User Manual for more information. + +If the ``do_deploy`` task re-executes, any previous output is removed +(i.e. "cleaned"). + +.. _ref-tasks-fetch: + +``do_fetch`` +------------ + +Fetches the source code. This task uses the +:term:`SRC_URI` variable and the argument's prefix to +determine the correct :ref:`fetcher <bitbake:bb-fetchers>` +module. + +.. _ref-tasks-image: + +``do_image`` +------------ + +Starts the image generation process. The ``do_image`` task runs after +the OpenEmbedded build system has run the +:ref:`ref-tasks-rootfs` task during which packages are +identified for installation into the image and the root filesystem is +created, complete with post-processing. + +The ``do_image`` task performs pre-processing on the image through the +:term:`IMAGE_PREPROCESS_COMMAND` and +dynamically generates supporting ``do_image_*`` tasks as needed. + +For more information on image creation, see the ":ref:`image-generation-dev-environment`" +section in the Yocto Project Overview and Concepts Manual. + +.. _ref-tasks-image-complete: + +``do_image_complete`` +--------------------- + +Completes the image generation process. The ``do_image_complete`` task +runs after the OpenEmbedded build system has run the +:ref:`ref-tasks-image` task during which image +pre-processing occurs and through dynamically generated ``do_image_*`` +tasks the image is constructed. + +The ``do_image_complete`` task performs post-processing on the image +through the +:term:`IMAGE_POSTPROCESS_COMMAND`. + +For more information on image creation, see the +":ref:`image-generation-dev-environment`" +section in the Yocto Project Overview and Concepts Manual. + +.. _ref-tasks-install: + +``do_install`` +-------------- + +Copies files that are to be packaged into the holding area +``${``\ :term:`D`\ ``}``. This task runs with the current +working directory set to ``${``\ :term:`B`\ ``}``, which is the +compilation directory. The ``do_install`` task, as well as other tasks +that either directly or indirectly depend on the installed files (e.g. +:ref:`ref-tasks-package`, ``do_package_write_*``, and +:ref:`ref-tasks-rootfs`), run under +:ref:`fakeroot <overview-manual/overview-manual-concepts:fakeroot and pseudo>`. + +.. note:: + + When installing files, be careful not to set the owner and group IDs + of the installed files to unintended values. Some methods of copying + files, notably when using the recursive ``cp`` command, can preserve + the UID and/or GID of the original file, which is usually not what + you want. The ``host-user-contaminated`` QA check checks for files + that probably have the wrong ownership. + + Safe methods for installing files include the following: + + - The ``install`` utility. This utility is the preferred method. + + - The ``cp`` command with the "--no-preserve=ownership" option. + + - The ``tar`` command with the "--no-same-owner" option. See the + ``bin_package.bbclass`` file in the ``meta/classes`` directory of + the :term:`Source Directory` for an example. + +.. _ref-tasks-install_ptest_base: + +``do_install_ptest_base`` +------------------------- + +Copies the runtime test suite files from the compilation directory to a +holding area. + +.. _ref-tasks-package: + +``do_package`` +-------------- + +Analyzes the content of the holding area +``${``\ :term:`D`\ ``}`` and splits the content into subsets +based on available packages and files. This task makes use of the +:term:`PACKAGES` and :term:`FILES` +variables. + +The ``do_package`` task, in conjunction with the +:ref:`ref-tasks-packagedata` task, also saves some +important package metadata. For additional information, see the +:term:`PKGDESTWORK` variable and the +":ref:`overview-manual/overview-manual-concepts:automatically added runtime dependencies`" +section in the Yocto Project Overview and Concepts Manual. + +.. _ref-tasks-package_qa: + +``do_package_qa`` +----------------- + +Runs QA checks on packaged files. For more information on these checks, +see the :ref:`insane <ref-classes-insane>` class. + +.. _ref-tasks-package_write_deb: + +``do_package_write_deb`` +------------------------ + +Creates Debian packages (i.e. ``*.deb`` files) and places them in the +``${``\ :term:`DEPLOY_DIR_DEB`\ ``}`` directory in +the package feeds area. For more information, see the +":ref:`package-feeds-dev-environment`" section in +the Yocto Project Overview and Concepts Manual. + +.. _ref-tasks-package_write_ipk: + +``do_package_write_ipk`` +------------------------ + +Creates IPK packages (i.e. ``*.ipk`` files) and places them in the +``${``\ :term:`DEPLOY_DIR_IPK`\ ``}`` directory in +the package feeds area. For more information, see the +":ref:`package-feeds-dev-environment`" section in +the Yocto Project Overview and Concepts Manual. + +.. _ref-tasks-package_write_rpm: + +``do_package_write_rpm`` +------------------------ + +Creates RPM packages (i.e. ``*.rpm`` files) and places them in the +``${``\ :term:`DEPLOY_DIR_RPM`\ ``}`` directory in +the package feeds area. For more information, see the +":ref:`package-feeds-dev-environment`" section in +the Yocto Project Overview and Concepts Manual. + +.. _ref-tasks-package_write_tar: + +``do_package_write_tar`` +------------------------ + +Creates tarballs and places them in the +``${``\ :term:`DEPLOY_DIR_TAR`\ ``}`` directory in +the package feeds area. For more information, see the +":ref:`package-feeds-dev-environment`" section in +the Yocto Project Overview and Concepts Manual. + +.. _ref-tasks-packagedata: + +``do_packagedata`` +------------------ + +Saves package metadata generated by the +:ref:`ref-tasks-package` task in +:term:`PKGDATA_DIR` to make it available globally. + +.. _ref-tasks-patch: + +``do_patch`` +------------ + +Locates patch files and applies them to the source code. + +After fetching and unpacking source files, the build system uses the +recipe's :term:`SRC_URI` statements +to locate and apply patch files to the source code. + +.. note:: + + The build system uses the + FILESPATH + variable to determine the default set of directories when searching + for patches. + +Patch files, by default, are ``*.patch`` and ``*.diff`` files created +and kept in a subdirectory of the directory holding the recipe file. For +example, consider the +:yocto_git:`bluez5 </cgit/cgit.cgi/poky/tree/meta/recipes-connectivity/bluez5>` +recipe from the OE-Core layer (i.e. ``poky/meta``): +:: + + poky/meta/recipes-connectivity/bluez5 + +This recipe has two patch files located here: +:: + + poky/meta/recipes-connectivity/bluez5/bluez5 + +In the ``bluez5`` recipe, the ``SRC_URI`` statements point to the source +and patch files needed to build the package. + +.. note:: + + In the case for the + bluez5_5.48.bb + recipe, the + SRC_URI + statements are from an include file + bluez5.inc + . + +As mentioned earlier, the build system treats files whose file types are +``.patch`` and ``.diff`` as patch files. However, you can use the +"apply=yes" parameter with the ``SRC_URI`` statement to indicate any +file as a patch file: +:: + + SRC_URI = " \\ + git://path_to_repo/some_package \\ + file://file;apply=yes \\ + " + +Conversely, if you have a directory full of patch files and you want to +exclude some so that the ``do_patch`` task does not apply them during +the patch phase, you can use the "apply=no" parameter with the +``SRC_URI`` statement: +:: + + SRC_URI = " \ + git://path_to_repo/some_package \ + file://path_to_lots_of_patch_files \ + file://path_to_lots_of_patch_files/patch_file5;apply=no \ + " + +In the +previous example, assuming all the files in the directory holding the +patch files end with either ``.patch`` or ``.diff``, every file would be +applied as a patch by default except for the patch_file5 patch. + +You can find out more about the patching process in the +":ref:`patching-dev-environment`" section in +the Yocto Project Overview and Concepts Manual and the +":ref:`new-recipe-patching-code`" section in the +Yocto Project Development Tasks Manual. + +.. _ref-tasks-populate_lic: + +``do_populate_lic`` +------------------- + +Writes license information for the recipe that is collected later when +the image is constructed. + +.. _ref-tasks-populate_sdk: + +``do_populate_sdk`` +------------------- + +Creates the file and directory structure for an installable SDK. See the +":ref:`sdk-generation-dev-environment`" +section in the Yocto Project Overview and Concepts Manual for more +information. + +.. _ref-tasks-populate_sdk_ext: + +``do_populate_sdk_ext`` +----------------------- + +Creates the file and directory structure for an installable extensible +SDK (eSDK). See the ":ref:`sdk-generation-dev-environment`" +section in the Yocto Project Overview and Concepts Manual for more +information. + + +.. _ref-tasks-populate_sysroot: + +``do_populate_sysroot`` +----------------------- + +Stages (copies) a subset of the files installed by the +:ref:`ref-tasks-install` task into the appropriate +sysroot. For information on how to access these files from other +recipes, see the :term:`STAGING_DIR* <STAGING_DIR_HOST>` variables. +Directories that would typically not be needed by other recipes at build +time (e.g. ``/etc``) are not copied by default. + +For information on what directories are copied by default, see the +:term:`SYSROOT_DIRS* <SYSROOT_DIRS>` variables. You can change +these variables inside your recipe if you need to make additional (or +fewer) directories available to other recipes at build time. + +The ``do_populate_sysroot`` task is a shared state (sstate) task, which +means that the task can be accelerated through sstate use. Realize also +that if the task is re-executed, any previous output is removed (i.e. +"cleaned"). + +.. _ref-tasks-prepare_recipe_sysroot: + +``do_prepare_recipe_sysroot`` +----------------------------- + +Installs the files into the individual recipe specific sysroots (i.e. +``recipe-sysroot`` and ``recipe-sysroot-native`` under +``${``\ :term:`WORKDIR`\ ``}`` based upon the +dependencies specified by :term:`DEPENDS`). See the +":ref:`staging <ref-classes-staging>`" class for more information. + +.. _ref-tasks-rm_work: + +``do_rm_work`` +-------------- + +Removes work files after the OpenEmbedded build system has finished with +them. You can learn more by looking at the +":ref:`rm_work.bbclass <ref-classes-rm-work>`" section. + +.. _ref-tasks-unpack: + +``do_unpack`` +------------- + +Unpacks the source code into a working directory pointed to by +``${``\ :term:`WORKDIR`\ ``}``. The :term:`S` +variable also plays a role in where unpacked source files ultimately +reside. For more information on how source files are unpacked, see the +":ref:`source-fetching-dev-environment`" +section in the Yocto Project Overview and Concepts Manual and also see +the ``WORKDIR`` and ``S`` variable descriptions. + +Manually Called Tasks +===================== + +These tasks are typically manually triggered (e.g. by using the +``bitbake -c`` command-line option): + +.. _ref-tasks-checkpkg: + +``do_checkpkg`` +--------------- + +Provides information about the recipe including its upstream version and +status. The upstream version and status reveals whether or not a version +of the recipe exists upstream and a status of not updated, updated, or +unknown. + +To check the upstream version and status of a recipe, use the following +devtool commands: +:: + + $ devtool latest-version + $ devtool check-upgrade-status + +See the ":ref:`ref-manual/ref-devtool-reference:\`\`devtool\`\` quick reference`" +chapter for more information on +``devtool``. See the ":ref:`devtool-checking-on-the-upgrade-status-of-a-recipe`" +section for information on checking the upgrade status of a recipe. + +To build the ``checkpkg`` task, use the ``bitbake`` command with the +"-c" option and task name: +:: + + $ bitbake core-image-minimal -c checkpkg + +By default, the results are stored in :term:`$LOG_DIR <LOG_DIR>` (e.g. +``$BUILD_DIR/tmp/log``). + +.. _ref-tasks-checkuri: + +``do_checkuri`` +--------------- + +Validates the :term:`SRC_URI` value. + +.. _ref-tasks-clean: + +``do_clean`` +------------ + +Removes all output files for a target from the +:ref:`ref-tasks-unpack` task forward (i.e. ``do_unpack``, +:ref:`ref-tasks-configure`, +:ref:`ref-tasks-compile`, +:ref:`ref-tasks-install`, and +:ref:`ref-tasks-package`). + +You can run this task using BitBake as follows: +:: + + $ bitbake -c clean recipe + +Running this task does not remove the +:ref:`sstate <overview-manual/overview-manual-concepts:shared state cache>` cache files. +Consequently, if no changes have been made and the recipe is rebuilt +after cleaning, output files are simply restored from the sstate cache. +If you want to remove the sstate cache files for the recipe, you need to +use the :ref:`ref-tasks-cleansstate` task instead +(i.e. ``bitbake -c cleansstate`` recipe). + +.. _ref-tasks-cleanall: + +``do_cleanall`` +--------------- + +Removes all output files, shared state +(:ref:`sstate <overview-manual/overview-manual-concepts:shared state cache>`) cache, and +downloaded source files for a target (i.e. the contents of +:term:`DL_DIR`). Essentially, the ``do_cleanall`` task is +identical to the :ref:`ref-tasks-cleansstate` task +with the added removal of downloaded source files. + +You can run this task using BitBake as follows: +:: + + $ bitbake -c cleanall recipe + +Typically, you would not normally use the ``cleanall`` task. Do so only +if you want to start fresh with the :ref:`ref-tasks-fetch` +task. + +.. _ref-tasks-cleansstate: + +``do_cleansstate`` +------------------ + +Removes all output files and shared state +(:ref:`sstate <overview-manual/overview-manual-concepts:shared state cache>`) cache for a +target. Essentially, the ``do_cleansstate`` task is identical to the +:ref:`ref-tasks-clean` task with the added removal of +shared state (`:ref:`sstate <overview-manual/overview-manual-concepts:shared state cache>`) +cache. + +You can run this task using BitBake as follows: +:: + + $ bitbake -c cleansstate recipe + +When you run the ``do_cleansstate`` task, the OpenEmbedded build system +no longer uses any sstate. Consequently, building the recipe from +scratch is guaranteed. + +.. note:: + + The + do_cleansstate + task cannot remove sstate from a remote sstate mirror. If you need to + build a target from scratch using remote mirrors, use the "-f" option + as follows: + :: + + $ bitbake -f -c do_cleansstate target + + +.. _ref-tasks-devpyshell: + +``do_devpyshell`` +----------------- + +Starts a shell in which an interactive Python interpreter allows you to +interact with the BitBake build environment. From within this shell, you +can directly examine and set bits from the data store and execute +functions as if within the BitBake environment. See the ":ref:`platdev-appdev-devpyshell`" section in +the Yocto Project Development Tasks Manual for more information about +using ``devpyshell``. + +.. _ref-tasks-devshell: + +``do_devshell`` +--------------- + +Starts a shell whose environment is set up for development, debugging, +or both. See the ":ref:`platdev-appdev-devshell`" section in the +Yocto Project Development Tasks Manual for more information about using +``devshell``. + +.. _ref-tasks-listtasks: + +``do_listtasks`` +---------------- + +Lists all defined tasks for a target. + +.. _ref-tasks-package_index: + +``do_package_index`` +-------------------- + +Creates or updates the index in the `:ref:`package-feeds-dev-environment` area. + +.. note:: + + This task is not triggered with the + bitbake -c + command-line option as are the other tasks in this section. Because + this task is specifically for the + package-index + recipe, you run it using + bitbake package-index + . + +Image-Related Tasks +=================== + +The following tasks are applicable to image recipes. + +.. _ref-tasks-bootimg: + +``do_bootimg`` +-------------- + +Creates a bootable live image. See the +:term:`IMAGE_FSTYPES` variable for additional +information on live image types. + +.. _ref-tasks-bundle_initramfs: + +``do_bundle_initramfs`` +----------------------- + +Combines an initial RAM disk (initramfs) image and kernel together to +form a single image. The +:term:`CONFIG_INITRAMFS_SOURCE` variable +has some more information about these types of images. + +.. _ref-tasks-rootfs: + +``do_rootfs`` +------------- + +Creates the root filesystem (file and directory structure) for an image. +See the ":ref:`image-generation-dev-environment`" +section in the Yocto Project Overview and Concepts Manual for more +information on how the root filesystem is created. + +.. _ref-tasks-testimage: + +``do_testimage`` +---------------- + +Boots an image and performs runtime tests within the image. For +information on automatically testing images, see the +":ref:`dev-manual/dev-manual-common-tasks:performing automated runtime testing`" +section in the Yocto Project Development Tasks Manual. + +.. _ref-tasks-testimage_auto: + +``do_testimage_auto`` +--------------------- + +Boots an image and performs runtime tests within the image immediately +after it has been built. This task is enabled when you set +:term:`TESTIMAGE_AUTO` equal to "1". + +For information on automatically testing images, see the +":ref:`dev-manual/dev-manual-common-tasks:performing automated runtime testing`" +section in the Yocto Project Development Tasks Manual. + +Kernel-Related Tasks +==================== + +The following tasks are applicable to kernel recipes. Some of these +tasks (e.g. the :ref:`ref-tasks-menuconfig` task) are +also applicable to recipes that use Linux kernel style configuration +such as the BusyBox recipe. + +.. _ref-tasks-compile_kernelmodules: + +``do_compile_kernelmodules`` +---------------------------- + +Runs the step that builds the kernel modules (if needed). Building a +kernel consists of two steps: 1) the kernel (``vmlinux``) is built, and +2) the modules are built (i.e. ``make modules``). + +.. _ref-tasks-diffconfig: + +``do_diffconfig`` +----------------- + +When invoked by the user, this task creates a file containing the +differences between the original config as produced by +:ref:`ref-tasks-kernel_configme` task and the +changes made by the user with other methods (i.e. using +(:ref:`ref-tasks-kernel_menuconfig`). Once the +file of differences is created, it can be used to create a config +fragment that only contains the differences. You can invoke this task +from the command line as follows: +:: + + $ bitbake linux-yocto -c diffconfig + +For more information, see the +":ref:`kernel-dev/kernel-dev-common:creating configuration fragments`" +section in the Yocto Project Linux Kernel Development Manual. + +.. _ref-tasks-kernel_checkout: + +``do_kernel_checkout`` +---------------------- + +Converts the newly unpacked kernel source into a form with which the +OpenEmbedded build system can work. Because the kernel source can be +fetched in several different ways, the ``do_kernel_checkout`` task makes +sure that subsequent tasks are given a clean working tree copy of the +kernel with the correct branches checked out. + +.. _ref-tasks-kernel_configcheck: + +``do_kernel_configcheck`` +------------------------- + +Validates the configuration produced by the +:ref:`ref-tasks-kernel_menuconfig` task. The +``do_kernel_configcheck`` task produces warnings when a requested +configuration does not appear in the final ``.config`` file or when you +override a policy configuration in a hardware configuration fragment. +You can run this task explicitly and view the output by using the +following command: +:: + + $ bitbake linux-yocto -c kernel_configcheck -f + +For more information, see the +":ref:`kernel-dev/kernel-dev-common:validating configuration`" +section in the Yocto Project Linux Kernel Development Manual. + +.. _ref-tasks-kernel_configme: + +``do_kernel_configme`` +---------------------- + +After the kernel is patched by the :ref:`ref-tasks-patch` +task, the ``do_kernel_configme`` task assembles and merges all the +kernel config fragments into a merged configuration that can then be +passed to the kernel configuration phase proper. This is also the time +during which user-specified defconfigs are applied if present, and where +configuration modes such as ``--allnoconfig`` are applied. + +.. _ref-tasks-kernel_menuconfig: + +``do_kernel_menuconfig`` +------------------------ + +Invoked by the user to manipulate the ``.config`` file used to build a +linux-yocto recipe. This task starts the Linux kernel configuration +tool, which you then use to modify the kernel configuration. + +.. note:: + + You can also invoke this tool from the command line as follows: + :: + + $ bitbake linux-yocto -c menuconfig + + +See the ":ref:`kernel-dev/kernel-dev-common:using \`\`menuconfig\`\``" +section in the Yocto Project Linux Kernel Development Manual for more +information on this configuration tool. + +.. _ref-tasks-kernel_metadata: + +``do_kernel_metadata`` +---------------------- + +Collects all the features required for a given kernel build, whether the +features come from :term:`SRC_URI` or from Git +repositories. After collection, the ``do_kernel_metadata`` task +processes the features into a series of config fragments and patches, +which can then be applied by subsequent tasks such as +:ref:`ref-tasks-patch` and +:ref:`ref-tasks-kernel_configme`. + +.. _ref-tasks-menuconfig: + +``do_menuconfig`` +----------------- + +Runs ``make menuconfig`` for the kernel. For information on +``menuconfig``, see the +":ref:`kernel-dev/kernel-dev-common:using \`\`menuconfig\`\``" +section in the Yocto Project Linux Kernel Development Manual. + +.. _ref-tasks-savedefconfig: + +``do_savedefconfig`` +-------------------- + +When invoked by the user, creates a defconfig file that can be used +instead of the default defconfig. The saved defconfig contains the +differences between the default defconfig and the changes made by the +user using other methods (i.e. the +:ref:`ref-tasks-kernel_menuconfig` task. You +can invoke the task using the following command: +:: + + $ bitbake linux-yocto -c savedefconfig + +.. _ref-tasks-shared_workdir: + +``do_shared_workdir`` +--------------------- + +After the kernel has been compiled but before the kernel modules have +been compiled, this task copies files required for module builds and +which are generated from the kernel build into the shared work +directory. With these copies successfully copied, the +:ref:`ref-tasks-compile_kernelmodules` task +can successfully build the kernel modules in the next step of the build. + +.. _ref-tasks-sizecheck: + +``do_sizecheck`` +---------------- + +After the kernel has been built, this task checks the size of the +stripped kernel image against +:term:`KERNEL_IMAGE_MAXSIZE`. If that +variable was set and the size of the stripped kernel exceeds that size, +the kernel build produces a warning to that effect. + +.. _ref-tasks-strip: + +``do_strip`` +------------ + +If ``KERNEL_IMAGE_STRIP_EXTRA_SECTIONS`` is defined, this task strips +the sections named in that variable from ``vmlinux``. This stripping is +typically used to remove nonessential sections such as ``.comment`` +sections from a size-sensitive configuration. + +.. _ref-tasks-validate_branches: + +``do_validate_branches`` +------------------------ + +After the kernel is unpacked but before it is patched, this task makes +sure that the machine and metadata branches as specified by the +:term:`SRCREV` variables actually exist on the specified +branches. If these branches do not exist and +:term:`AUTOREV` is not being used, the +``do_validate_branches`` task fails during the build. + +Miscellaneous Tasks +=================== + +The following sections describe miscellaneous tasks. + +.. _ref-tasks-spdx: + +``do_spdx`` +----------- + +A build stage that takes the source code and scans it on a remote +FOSSOLOGY server in order to produce an SPDX document. This task applies +only to the :ref:`spdx <ref-classes-spdx>` class. diff --git a/poky/documentation/ref-manual/ref-tasks.xml b/poky/documentation/ref-manual/ref-tasks.xml index 011e0d749..5b09b3f2e 100644 --- a/poky/documentation/ref-manual/ref-tasks.xml +++ b/poky/documentation/ref-manual/ref-tasks.xml @@ -1,6 +1,7 @@ <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > +<!--SPDX-License-Identifier: CC-BY-2.0-UK--> <chapter id='ref-tasks'> <title>Tasks</title> diff --git a/poky/documentation/ref-manual/ref-terms.rst b/poky/documentation/ref-manual/ref-terms.rst new file mode 100644 index 000000000..600cc23c3 --- /dev/null +++ b/poky/documentation/ref-manual/ref-terms.rst @@ -0,0 +1,397 @@ +.. SPDX-License-Identifier: CC-BY-2.0-UK + +******************* +Yocto Project Terms +******************* + +Following is a list of terms and definitions users new to the Yocto Project +development environment might find helpful. While some of these terms are +universal, the list includes them just in case: + +.. glossary:: + + Append Files + Files that append build information to a recipe file. Append files are + known as BitBake append files and ``.bbappend`` files. The OpenEmbedded + build system expects every append file to have a corresponding recipe + (``.bb``) file. Furthermore, the append file and corresponding recipe file + must use the same root filename. The filenames can differ only in the + file type suffix used (e.g. ``formfactor_0.0.bb`` and + ``formfactor_0.0.bbappend``). + + Information in append files extends or overrides the information in the + similarly-named recipe file. For an example of an append file in use, see + the ":ref:`dev-manual/dev-manual-common-tasks:Using .bbappend Files in + Your Layer`" section in the Yocto Project Development Tasks Manual. + + When you name an append file, you can use the "``%``" wildcard character + to allow for matching recipe names. For example, suppose you have an + append file named as follows: + :: + + busybox_1.21.%.bbappend + + That append file + would match any ``busybox_1.21.``\ x\ ``.bb`` version of the recipe. So, + the append file would match any of the following recipe names: + + .. code-block:: shell + + busybox_1.21.1.bb + busybox_1.21.2.bb + busybox_1.21.3.bb + busybox_1.21.10.bb + busybox_1.21.25.bb + + .. note:: + + The use of the " % " character is limited in that it only works + directly in front of the .bbappend portion of the append file's + name. You cannot use the wildcard character in any other location of + the name. + + BitBake + The task executor and scheduler used by the OpenEmbedded build system to + build images. For more information on BitBake, see the :doc:`BitBake User + Manual <bitbake:index>`. + + Board Support Package (BSP) + A group of drivers, definitions, and other components that provide support + for a specific hardware configuration. For more information on BSPs, see + the :ref:`bsp-guide/bsp-guide:Yocto Project Board Support Package + Developer's Guide`. + + Build Directory + This term refers to the area used by the OpenEmbedded build system for + builds. The area is created when you ``source`` the setup environment + script that is found in the Source Directory + (i.e. :ref:`ref-manual/ref-structure:\`\`oe-init-build-env\`\``). The + :term:`TOPDIR` variable points to the Build Directory. + + You have a lot of flexibility when creating the Build Directory. + Following are some examples that show how to create the directory. The + examples assume your :term:`Source Directory` is named ``poky``: + + - Create the Build Directory inside your Source Directory and let + the name of the Build Directory default to ``build``: + + .. code-block:: shell + + $ cd $HOME/poky + $ source oe-init-build-env + + - Create the Build Directory inside your home directory and + specifically name it ``test-builds``: + + .. code-block:: shell + + $ cd $HOME + $ source poky/oe-init-build-env test-builds + + - Provide a directory path and specifically name the Build + Directory. Any intermediate folders in the pathname must exist. + This next example creates a Build Directory named + ``YP-POKYVERSION`` in your home directory within the existing + directory ``mybuilds``: + + .. code-block:: shell + + $ cd $HOME + $ source $HOME/poky/oe-init-build-env $HOME/mybuilds/YP-POKYVERSION + + .. note:: + + By default, the Build Directory contains :term:`TMPDIR` , which is a + temporary directory the build system uses for its work. TMPDIR cannot + be under NFS. Thus, by default, the Build Directory cannot be under + NFS. However, if you need the Build Directory to be under NFS, you can + set this up by setting TMPDIR in your local.conf file to use a local + drive. Doing so effectively separates TMPDIR from TOPDIR , which is the + Build Directory. + + Build Host + The system used to build images in a Yocto Project Development + environment. The build system is sometimes referred to as the development + host. + + Classes + Files that provide for logic encapsulation and inheritance so that + commonly used patterns can be defined once and then easily used in + multiple recipes. For reference information on the Yocto Project classes, + see the ":ref:`ref-manual/ref-classes:Classes`" chapter. Class files end with the + ``.bbclass`` filename extension. + + Configuration File + Files that hold global definitions of variables, user-defined variables, + and hardware configuration information. These files tell the OpenEmbedded + build system what to build and what to put into the image to support a + particular platform. + + Configuration files end with a ``.conf`` filename extension. The + :file:`conf/local.conf` configuration file in the :term:`Build Directory` + contains user-defined variables that affect every build. The + :file:`meta-poky/conf/distro/poky.conf` configuration file defines Yocto + "distro" configuration variables used only when building with this + policy. Machine configuration files, which are located throughout the + :term:`Source Directory`, define variables for specific hardware and are + only used when building for that target (e.g. the + :file:`machine/beaglebone.conf` configuration file defines variables for + the Texas Instruments ARM Cortex-A8 development board). + + Container Layer + Layers that hold other layers. An example of a container layer is + OpenEmbedded's `meta-openembedded + <https://github.com/openembedded/meta-openembedded>`_ layer. The + ``meta-openembedded`` layer contains many ``meta-*`` layers. + + Cross-Development Toolchain + In general, a cross-development toolchain is a collection of software + development tools and utilities that run on one architecture and allow you + to develop software for a different, or targeted, architecture. These + toolchains contain cross-compilers, linkers, and debuggers that are + specific to the target architecture. + + The Yocto Project supports two different cross-development toolchains: + + - A toolchain only used by and within BitBake when building an image for a + target architecture. + + - A relocatable toolchain used outside of BitBake by developers when + developing applications that will run on a targeted device. + + Creation of these toolchains is simple and automated. For information on + toolchain concepts as they apply to the Yocto Project, see the + ":ref:`overview-manual/overview-manual-concepts:Cross-Development + Toolchain Generation`" section in the Yocto Project Overview and Concepts + Manual. You can also find more information on using the relocatable + toolchain in the :ref:`sdk-manual/sdk-manual:Yocto Project Application + Development and the Extensible Software Development Kit (eSDK)` manual. + + Extensible Software Development Kit (eSDK) + A custom SDK for application developers. This eSDK allows developers to + incorporate their library and programming changes back into the image to + make their code available to other application developers. + + For information on the eSDK, see the :ref:`sdk-manual/sdk-manual:Yocto + Project Application Development and the Extensible Software Development + Kit (eSDK)` manual. + + Image + An image is an artifact of the BitBake build process given a collection of + recipes and related Metadata. Images are the binary output that run on + specific hardware or QEMU and are used for specific use-cases. For a list + of the supported image types that the Yocto Project provides, see the + ":ref:`ref-manual/ref-images:Images`" chapter. + + Layer + A collection of related recipes. Layers allow you to consolidate related + metadata to customize your build. Layers also isolate information used + when building for multiple architectures. Layers are hierarchical in + their ability to override previous specifications. You can include any + number of available layers from the Yocto Project and customize the build + by adding your layers after them. You can search the Layer Index for + layers used within Yocto Project. + + For introductory information on layers, see the + ":ref:`overview-manual/overview-manual-yp-intro:The Yocto Project Layer + Model`" section in the Yocto Project Overview and Concepts Manual. For + more detailed information on layers, see the + ":ref:`dev-manual/dev-manual-common-tasks:Understanding and Creating + Layers`" section in the Yocto Project Development Tasks Manual. For a + discussion specifically on BSP Layers, see the ":ref:`bsp-guide/bsp:BSP + Layers`" section in the Yocto Project Board Support Packages (BSP) + Developer's Guide. + + Metadata + A key element of the Yocto Project is the Metadata that + is used to construct a Linux distribution and is contained in the + files that the :term:`OpenEmbedded Build System` + parses when building an image. In general, Metadata includes recipes, + configuration files, and other information that refers to the build + instructions themselves, as well as the data used to control what + things get built and the effects of the build. Metadata also includes + commands and data used to indicate what versions of software are + used, from where they are obtained, and changes or additions to the + software itself (patches or auxiliary files) that are used to fix + bugs or customize the software for use in a particular situation. + OpenEmbedded-Core is an important set of validated metadata. + + In the context of the kernel ("kernel Metadata"), the term refers to + the kernel config fragments and features contained in the + :yocto_git:`yocto-kernel-cache </cgit/cgit.cgi/yocto-kernel-cache>` + Git repository. + + OpenEmbedded-Core (OE-Core) + OE-Core is metadata comprised of + foundational recipes, classes, and associated files that are meant to + be common among many different OpenEmbedded-derived systems, + including the Yocto Project. OE-Core is a curated subset of an + original repository developed by the OpenEmbedded community that has + been pared down into a smaller, core set of continuously validated + recipes. The result is a tightly controlled and an quality-assured + core set of recipes. + + You can see the Metadata in the ``meta`` directory of the Yocto + Project :yocto_git:`Source Repositories <>`. + + OpenEmbedded Build System + The build system specific to the Yocto + Project. The OpenEmbedded build system is based on another project + known as "Poky", which uses :term:`BitBake` as the task + executor. Throughout the Yocto Project documentation set, the + OpenEmbedded build system is sometimes referred to simply as "the + build system". If other build systems, such as a host or target build + system are referenced, the documentation clearly states the + difference. + + .. note:: + + For some historical information about Poky, see the + Poky + term. + + Package + In the context of the Yocto Project, this term refers to a + recipe's packaged output produced by BitBake (i.e. a "baked recipe"). + A package is generally the compiled binaries produced from the + recipe's sources. You "bake" something by running it through BitBake. + + It is worth noting that the term "package" can, in general, have + subtle meanings. For example, the packages referred to in the + "`Required Packages for the Build + Host <#required-packages-for-the-build-host>`__" section are compiled + binaries that, when installed, add functionality to your Linux + distribution. + + Another point worth noting is that historically within the Yocto + Project, recipes were referred to as packages - thus, the existence + of several BitBake variables that are seemingly mis-named, (e.g. + :term:`PR`, :term:`PV`, and + :term:`PE`). + + Package Groups + Arbitrary groups of software Recipes. You use + package groups to hold recipes that, when built, usually accomplish a + single task. For example, a package group could contain the recipes + for a company's proprietary or value-add software. Or, the package + group could contain the recipes that enable graphics. A package group + is really just another recipe. Because package group files are + recipes, they end with the ``.bb`` filename extension. + + Poky + Poky, which is pronounced *Pock*-ee, is a reference embedded + distribution and a reference test configuration. Poky provides the + following: + + - A base-level functional distro used to illustrate how to customize + a distribution. + + - A means by which to test the Yocto Project components (i.e. Poky + is used to validate the Yocto Project). + + - A vehicle through which you can download the Yocto Project. + + Poky is not a product level distro. Rather, it is a good starting + point for customization. + + .. note:: + + Poky began as an open-source project initially developed by + OpenedHand. OpenedHand developed Poky from the existing + OpenEmbedded build system to create a commercially supportable + build system for embedded Linux. After Intel Corporation acquired + OpenedHand, the poky project became the basis for the Yocto + Project's build system. + + Recipe + A set of instructions for building packages. A recipe + describes where you get source code, which patches to apply, how to + configure the source, how to compile it and so on. Recipes also + describe dependencies for libraries or for other recipes. Recipes + represent the logical unit of execution, the software to build, the + images to build, and use the ``.bb`` file extension. + + Reference Kit + A working example of a system, which includes a + :term:`BSP<Board Support Package (BSP)>` as well as a + :term:`build host<Build Host>` and other components, that can + work on specific hardware. + + Source Directory + This term refers to the directory structure + created as a result of creating a local copy of the ``poky`` Git + repository ``git://git.yoctoproject.org/poky`` or expanding a + released ``poky`` tarball. + + .. note:: + + Creating a local copy of the + poky + Git repository is the recommended method for setting up your + Source Directory. + + Sometimes you might hear the term "poky directory" used to refer to + this directory structure. + + .. note:: + + The OpenEmbedded build system does not support file or directory + names that contain spaces. Be sure that the Source Directory you + use does not contain these types of names. + + The Source Directory contains BitBake, Documentation, Metadata and + other files that all support the Yocto Project. Consequently, you + must have the Source Directory in place on your development system in + order to do any development using the Yocto Project. + + When you create a local copy of the Git repository, you can name the + repository anything you like. Throughout much of the documentation, + "poky" is used as the name of the top-level folder of the local copy + of the poky Git repository. So, for example, cloning the ``poky`` Git + repository results in a local Git repository whose top-level folder + is also named "poky". + + While it is not recommended that you use tarball expansion to set up + the Source Directory, if you do, the top-level directory name of the + Source Directory is derived from the Yocto Project release tarball. + For example, downloading and unpacking + :yocto_dl:`/releases/yocto/&DISTRO_REL_TAG;/&YOCTO_POKY;.tar.bz2` + results in a Source Directory whose root folder is named ``poky``. + + It is important to understand the differences between the Source + Directory created by unpacking a released tarball as compared to + cloning ``git://git.yoctoproject.org/poky``. When you unpack a + tarball, you have an exact copy of the files based on the time of + release - a fixed release point. Any changes you make to your local + files in the Source Directory are on top of the release and will + remain local only. On the other hand, when you clone the ``poky`` Git + repository, you have an active development repository with access to + the upstream repository's branches and tags. In this case, any local + changes you make to the local Source Directory can be later applied + to active development branches of the upstream ``poky`` Git + repository. + + For more information on concepts related to Git repositories, + branches, and tags, see the + ":ref:`overview-manual/overview-manual-development-environment:repositories, tags, and branches`" + section in the Yocto Project Overview and Concepts Manual. + + Task + A unit of execution for BitBake (e.g. + :ref:`ref-tasks-compile`, + :ref:`ref-tasks-fetch`, + :ref:`ref-tasks-patch`, and so forth). + + Toaster + A web interface to the Yocto Project's :term:`OpenEmbedded Build System`. + The interface enables you to + configure and run your builds. Information about builds is collected + and stored in a database. For information on Toaster, see the + :doc:`../toaster-manual/toaster-manual`. + + Upstream + A reference to source code or repositories that are not + local to the development system but located in a master area that is + controlled by the maintainer of the source code. For example, in + order for a developer to work on a particular piece of code, they + need to first get a copy of it from an "upstream" source. diff --git a/poky/documentation/ref-manual/ref-terms.xml b/poky/documentation/ref-manual/ref-terms.xml index 722fa7ee2..2a0452bd7 100644 --- a/poky/documentation/ref-manual/ref-terms.xml +++ b/poky/documentation/ref-manual/ref-terms.xml @@ -1,6 +1,7 @@ <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > +<!--SPDX-License-Identifier: CC-BY-2.0-UK--> <chapter id='ref-terms'> <title>Yocto Project Terms</title> @@ -364,7 +365,7 @@ You use package groups to hold recipes that, when built, usually accomplish a single task. For example, a package group could contain the recipes for a - company’s proprietary or value-add software. + company's proprietary or value-add software. Or, the package group could contain the recipes that enable graphics. A package group is really just another recipe. diff --git a/poky/documentation/ref-manual/ref-variables.rst b/poky/documentation/ref-manual/ref-variables.rst new file mode 100644 index 000000000..2d6719df1 --- /dev/null +++ b/poky/documentation/ref-manual/ref-variables.rst @@ -0,0 +1,8958 @@ +.. SPDX-License-Identifier: CC-BY-2.0-UK + +****************** +Variables Glossary +****************** + +This chapter lists common variables used in the OpenEmbedded build +system and gives an overview of their function and contents. + +`A <#var-ABIEXTENSION>`__ :term:`B` `C <#var-CACHE>`__ +:term:`D` `E <#var-EFI_PROVIDER>`__ `F <#var-FEATURE_PACKAGES>`__ +`G <#var-GCCPIE>`__ `H <#var-HOMEPAGE>`__ `I <#var-ICECC_DISABLED>`__ +`K <#var-KARCH>`__ `L <#var-LABELS>`__ `M <#var-MACHINE>`__ +`N <#var-NATIVELSBSTRING>`__ `O <#var-OBJCOPY>`__ :term:`P` +`R <#var-RANLIB>`__ :term:`S` :term:`T` +`U <#var-UBOOT_CONFIG>`__ `V <#var-VOLATILE_LOG_DIR>`__ +`W <#var-WARN_QA>`__ `X <#var-XSERVER>`__ + +.. glossary:: + + ABIEXTENSION + Extension to the Application Binary Interface (ABI) field of the GNU + canonical architecture name (e.g. "eabi"). + + ABI extensions are set in the machine include files. For example, the + ``meta/conf/machine/include/arm/arch-arm.inc`` file sets the + following extension: + :: + + ABIEXTENSION = "eabi" + + ALLOW_EMPTY + Specifies whether to produce an output package even if it is empty. + By default, BitBake does not produce empty packages. This default + behavior can cause issues when there is an + :term:`RDEPENDS` or some other hard runtime + requirement on the existence of the package. + + Like all package-controlling variables, you must always use them in + conjunction with a package name override, as in: + :: + + ALLOW_EMPTY_${PN} = "1" + ALLOW_EMPTY_${PN}-dev = "1" + ALLOW_EMPTY_${PN}-staticdev = "1" + + ALTERNATIVE + Lists commands in a package that need an alternative binary naming + scheme. Sometimes the same command is provided in multiple packages. + When this occurs, the OpenEmbedded build system needs to use the + alternatives system to create a different binary naming scheme so the + commands can co-exist. + + To use the variable, list out the package's commands that also exist + as part of another package. For example, if the ``busybox`` package + has four commands that also exist as part of another package, you + identify them as follows: + :: + + ALTERNATIVE_busybox = "sh sed test bracket" + + For more information on the alternatives system, see the + ":ref:`update-alternatives.bbclass <ref-classes-update-alternatives>`" + section. + + ALTERNATIVE_LINK_NAME + Used by the alternatives system to map duplicated commands to actual + locations. For example, if the ``bracket`` command provided by the + ``busybox`` package is duplicated through another package, you must + use the ``ALTERNATIVE_LINK_NAME`` variable to specify the actual + location: + :: + + ALTERNATIVE_LINK_NAME[bracket] = "/usr/bin/[" + + In this example, the binary for the ``bracket`` command (i.e. ``[``) + from the ``busybox`` package resides in ``/usr/bin/``. + + .. note:: + + If ALTERNATIVE_LINK_NAME is not defined, it defaults to ${bindir}/ name. + + For more information on the alternatives system, see the + ":ref:`update-alternatives.bbclass <ref-classes-update-alternatives>`" + section. + + ALTERNATIVE_PRIORITY + Used by the alternatives system to create default priorities for + duplicated commands. You can use the variable to create a single + default regardless of the command name or package, a default for + specific duplicated commands regardless of the package, or a default + for specific commands tied to particular packages. Here are the + available syntax forms: + :: + + ALTERNATIVE_PRIORITY = "priority" + ALTERNATIVE_PRIORITY[name] = "priority" + ALTERNATIVE_PRIORITY_pkg[name] = "priority" + + For more information on the alternatives system, see the + ":ref:`update-alternatives.bbclass <ref-classes-update-alternatives>`" + section. + + ALTERNATIVE_TARGET + Used by the alternatives system to create default link locations for + duplicated commands. You can use the variable to create a single + default location for all duplicated commands regardless of the + command name or package, a default for specific duplicated commands + regardless of the package, or a default for specific commands tied to + particular packages. Here are the available syntax forms: + :: + + ALTERNATIVE_TARGET = "target" + ALTERNATIVE_TARGET[name] = "target" + ALTERNATIVE_TARGET_pkg[name] = "target" + + .. note:: + + If ``ALTERNATIVE_TARGET`` is not defined, it inherits the value + from the :term:`ALTERNATIVE_LINK_NAME` variable. + + If ``ALTERNATIVE_LINK_NAME`` and ``ALTERNATIVE_TARGET`` are the + same, the target for ``ALTERNATIVE_TARGET`` has "``.{BPN}``" + appended to it. + + Finally, if the file referenced has not been renamed, the + alternatives system will rename it to avoid the need to rename + alternative files in the :ref:`ref-tasks-install` + task while retaining support for the command if necessary. + + For more information on the alternatives system, see the + ":ref:`update-alternatives.bbclass <ref-classes-update-alternatives>`" + section. + + APPEND + An override list of append strings for each target specified with + :term:`LABELS`. + + See the :ref:`grub-efi <ref-classes-grub-efi>` class for more + information on how this variable is used. + + AR + The minimal command and arguments used to run ``ar``. + + ARCHIVER_MODE + When used with the :ref:`archiver <ref-classes-archiver>` class, + determines the type of information used to create a released archive. + You can use this variable to create archives of patched source, + original source, configured source, and so forth by employing the + following variable flags (varflags): + :: + + ARCHIVER_MODE[src] = "original" # Uses original (unpacked) source files. + ARCHIVER_MODE[src] = "patched" # Uses patched source files. This is the default. + ARCHIVER_MODE[src] = "configured" # Uses configured source files. + ARCHIVER_MODE[diff] = "1" # Uses patches between do_unpack and do_patch. + ARCHIVER_MODE[diff-exclude] ?= "file file ..." # Lists files and directories to exclude from diff. + ARCHIVER_MODE[dumpdata] = "1" # Uses environment data. + ARCHIVER_MODE[recipe] = "1" # Uses recipe and include files. + ARCHIVER_MODE[srpm] = "1" # Uses RPM package files. + + For information on how the variable works, see the + ``meta/classes/archiver.bbclass`` file in the :term:`Source Directory`. + + AS + Minimal command and arguments needed to run the assembler. + + ASSUME_PROVIDED + Lists recipe names (:term:`PN` values) BitBake does not + attempt to build. Instead, BitBake assumes these recipes have already + been built. + + In OpenEmbedded-Core, ``ASSUME_PROVIDED`` mostly specifies native + tools that should not be built. An example is ``git-native``, which + when specified, allows for the Git binary from the host to be used + rather than building ``git-native``. + + ASSUME_SHLIBS + Provides additional ``shlibs`` provider mapping information, which + adds to or overwrites the information provided automatically by the + system. Separate multiple entries using spaces. + + As an example, use the following form to add an ``shlib`` provider of + shlibname in packagename with the optional version: + :: + + shlibname:packagename[_version] + + Here is an example that adds a shared library named ``libEGL.so.1`` + as being provided by the ``libegl-implementation`` package: + :: + + ASSUME_SHLIBS = "libEGL.so.1:libegl-implementation" + + AUTHOR + The email address used to contact the original author or authors in + order to send patches and forward bugs. + + AUTO_LIBNAME_PKGS + When the :ref:`debian <ref-classes-debian>` class is inherited, + which is the default behavior, ``AUTO_LIBNAME_PKGS`` specifies which + packages should be checked for libraries and renamed according to + Debian library package naming. + + The default value is "${PACKAGES}", which causes the debian class to + act on all packages that are explicitly generated by the recipe. + + AUTO_SYSLINUXMENU + Enables creating an automatic menu for the syslinux bootloader. You + must set this variable in your recipe. The + :ref:`syslinux <ref-classes-syslinux>` class checks this variable. + + AUTOREV + When ``SRCREV`` is set to the value of this variable, it specifies to + use the latest source revision in the repository. Here is an example: + :: + + SRCREV = "${AUTOREV}" + + If you use the previous statement to retrieve the latest version of + software, you need to be sure :term:`PV` contains + ``${``\ :term:`SRCPV`\ ``}``. For example, suppose you + have a kernel recipe that inherits the + :ref:`kernel <ref-classes-kernel>` class and you use the previous + statement. In this example, ``${SRCPV}`` does not automatically get + into ``PV``. Consequently, you need to change ``PV`` in your recipe + so that it does contain ``${SRCPV}``. + + For more information see the + ":ref:`dev-manual/dev-manual-common-tasks:automatically incrementing a package version number`" + section in the Yocto Project Development Tasks Manual. + + AVAILABLE_LICENSES + List of licenses found in the directories specified by + :term:`COMMON_LICENSE_DIR` and + :term:`LICENSE_PATH`. + + .. note:: + + It is assumed that all changes to + COMMON_LICENSE_DIR + and + LICENSE_PATH + have been done before + AVAILABLE_LICENSES + is defined (in + license.bbclass + ). + + AVAILTUNES + The list of defined CPU and Application Binary Interface (ABI) + tunings (i.e. "tunes") available for use by the OpenEmbedded build + system. + + The list simply presents the tunes that are available. Not all tunes + may be compatible with a particular machine configuration, or with + each other in a + :ref:`Multilib <dev-manual/dev-manual-common-tasks:combining multiple versions of library files into one image>` + configuration. + + To add a tune to the list, be sure to append it with spaces using the + "+=" BitBake operator. Do not simply replace the list by using the + "=" operator. See the + ":ref:`Basic Syntax <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:basic syntax>`" section in the BitBake + User Manual for more information. + + B + The directory within the :term:`Build Directory` in + which the OpenEmbedded build system places generated objects during a + recipe's build process. By default, this directory is the same as the + :term:`S` directory, which is defined as: + :: + + S = "${WORKDIR}/${BP}" + + You can separate the (``S``) directory and the directory pointed to + by the ``B`` variable. Most Autotools-based recipes support + separating these directories. The build system defaults to using + separate directories for ``gcc`` and some kernel recipes. + + BAD_RECOMMENDATIONS + Lists "recommended-only" packages to not install. Recommended-only + packages are packages installed only through the + :term:`RRECOMMENDS` variable. You can prevent any + of these "recommended" packages from being installed by listing them + with the ``BAD_RECOMMENDATIONS`` variable: + :: + + BAD_RECOMMENDATIONS = "package_name package_name package_name ..." + + You can set this variable globally in your ``local.conf`` file or you + can attach it to a specific image recipe by using the recipe name + override: + :: + + BAD_RECOMMENDATIONS_pn-target_image = "package_name" + + It is important to realize that if you choose to not install packages + using this variable and some other packages are dependent on them + (i.e. listed in a recipe's :term:`RDEPENDS` + variable), the OpenEmbedded build system ignores your request and + will install the packages to avoid dependency errors. + + Support for this variable exists only when using the IPK and RPM + packaging backend. Support does not exist for DEB. + + See the :term:`NO_RECOMMENDATIONS` and the + :term:`PACKAGE_EXCLUDE` variables for related + information. + + BASE_LIB + The library directory name for the CPU or Application Binary + Interface (ABI) tune. The ``BASE_LIB`` applies only in the Multilib + context. See the ":ref:`dev-manual/dev-manual-common-tasks:combining multiple versions of library files into one image`" + section in the Yocto Project Development Tasks Manual for information + on Multilib. + + The ``BASE_LIB`` variable is defined in the machine include files in + the :term:`Source Directory`. If Multilib is not + being used, the value defaults to "lib". + + BASE_WORKDIR + Points to the base of the work directory for all recipes. The default + value is "${TMPDIR}/work". + + BB_ALLOWED_NETWORKS + Specifies a space-delimited list of hosts that the fetcher is allowed + to use to obtain the required source code. Following are + considerations surrounding this variable: + + - This host list is only used if ``BB_NO_NETWORK`` is either not set + or set to "0". + + - Limited support for wildcard matching against the beginning of + host names exists. For example, the following setting matches + ``git.gnu.org``, ``ftp.gnu.org``, and ``foo.git.gnu.org``. + :: + + BB_ALLOWED_NETWORKS = "*.gnu.org" + + .. note:: + + The use of the "``*``" character only works at the beginning of + a host name and it must be isolated from the remainder of the + host name. You cannot use the wildcard character in any other + location of the name or combined with the front part of the + name. + + For example, ``*.foo.bar`` is supported, while ``*aa.foo.bar`` + is not. + + - Mirrors not in the host list are skipped and logged in debug. + + - Attempts to access networks not in the host list cause a failure. + + Using ``BB_ALLOWED_NETWORKS`` in conjunction with + :term:`PREMIRRORS` is very useful. Adding the host + you want to use to ``PREMIRRORS`` results in the source code being + fetched from an allowed location and avoids raising an error when a + host that is not allowed is in a :term:`SRC_URI` + statement. This is because the fetcher does not attempt to use the + host listed in ``SRC_URI`` after a successful fetch from the + ``PREMIRRORS`` occurs. + + BB_DANGLINGAPPENDS_WARNONLY + Defines how BitBake handles situations where an append file + (``.bbappend``) has no corresponding recipe file (``.bb``). This + condition often occurs when layers get out of sync (e.g. ``oe-core`` + bumps a recipe version and the old recipe no longer exists and the + other layer has not been updated to the new version of the recipe + yet). + + The default fatal behavior is safest because it is the sane reaction + given something is out of sync. It is important to realize when your + changes are no longer being applied. + + You can change the default behavior by setting this variable to "1", + "yes", or "true" in your ``local.conf`` file, which is located in the + :term:`Build Directory`: Here is an example: + :: + + BB_DANGLINGAPPENDS_WARNONLY = "1" + + BB_DISKMON_DIRS + Monitors disk space and available inodes during the build and allows + you to control the build based on these parameters. + + Disk space monitoring is disabled by default. To enable monitoring, + add the ``BB_DISKMON_DIRS`` variable to your ``conf/local.conf`` file + found in the :term:`Build Directory`. Use the + following form: + :: + + BB_DISKMON_DIRS = "action,dir,threshold [...]" + + where: + + action is: + ABORT: Immediately abort the build when + a threshold is broken. + STOPTASKS: Stop the build after the currently + executing tasks have finished when + a threshold is broken. + WARN: Issue a warning but continue the + build when a threshold is broken. + Subsequent warnings are issued as + defined by the BB_DISKMON_WARNINTERVAL + variable, which must be defined in + the conf/local.conf file. + + dir is: + Any directory you choose. You can specify one or + more directories to monitor by separating the + groupings with a space. If two directories are + on the same device, only the first directory + is monitored. + + threshold is: + Either the minimum available disk space, + the minimum number of free inodes, or + both. You must specify at least one. To + omit one or the other, simply omit the value. + Specify the threshold using G, M, K for Gbytes, + Mbytes, and Kbytes, respectively. If you do + not specify G, M, or K, Kbytes is assumed by + default. Do not use GB, MB, or KB. + + Here are some examples: + :: + + BB_DISKMON_DIRS = "ABORT,${TMPDIR},1G,100K WARN,${SSTATE_DIR},1G,100K" + BB_DISKMON_DIRS = "STOPTASKS,${TMPDIR},1G" + BB_DISKMON_DIRS = "ABORT,${TMPDIR},,100K" + + The first example works only if you also provide the + :term:`BB_DISKMON_WARNINTERVAL` + variable in the ``conf/local.conf``. This example causes the build + system to immediately abort when either the disk space in + ``${TMPDIR}`` drops below 1 Gbyte or the available free inodes drops + below 100 Kbytes. Because two directories are provided with the + variable, the build system also issue a warning when the disk space + in the ``${SSTATE_DIR}`` directory drops below 1 Gbyte or the number + of free inodes drops below 100 Kbytes. Subsequent warnings are issued + during intervals as defined by the ``BB_DISKMON_WARNINTERVAL`` + variable. + + The second example stops the build after all currently executing + tasks complete when the minimum disk space in the ``${TMPDIR}`` + directory drops below 1 Gbyte. No disk monitoring occurs for the free + inodes in this case. + + The final example immediately aborts the build when the number of + free inodes in the ``${TMPDIR}`` directory drops below 100 Kbytes. No + disk space monitoring for the directory itself occurs in this case. + + BB_DISKMON_WARNINTERVAL + Defines the disk space and free inode warning intervals. To set these + intervals, define the variable in your ``conf/local.conf`` file in + the :term:`Build Directory`. + + If you are going to use the ``BB_DISKMON_WARNINTERVAL`` variable, you + must also use the :term:`BB_DISKMON_DIRS` + variable and define its action as "WARN". During the build, + subsequent warnings are issued each time disk space or number of free + inodes further reduces by the respective interval. + + If you do not provide a ``BB_DISKMON_WARNINTERVAL`` variable and you + do use ``BB_DISKMON_DIRS`` with the "WARN" action, the disk + monitoring interval defaults to the following: + :: + + BB_DISKMON_WARNINTERVAL = "50M,5K" + + When specifying the variable in your configuration file, use the + following form: + :: + + BB_DISKMON_WARNINTERVAL = "disk_space_interval,disk_inode_interval" + + where: + + disk_space_interval is: + An interval of memory expressed in either + G, M, or K for Gbytes, Mbytes, or Kbytes, + respectively. You cannot use GB, MB, or KB. + + disk_inode_interval is: + An interval of free inodes expressed in either + G, M, or K for Gbytes, Mbytes, or Kbytes, + respectively. You cannot use GB, MB, or KB. + + Here is an example: + :: + + BB_DISKMON_DIRS = "WARN,${SSTATE_DIR},1G,100K" + BB_DISKMON_WARNINTERVAL = "50M,5K" + + These variables cause the + OpenEmbedded build system to issue subsequent warnings each time the + available disk space further reduces by 50 Mbytes or the number of + free inodes further reduces by 5 Kbytes in the ``${SSTATE_DIR}`` + directory. Subsequent warnings based on the interval occur each time + a respective interval is reached beyond the initial warning (i.e. 1 + Gbytes and 100 Kbytes). + + BB_GENERATE_MIRROR_TARBALLS + Causes tarballs of the source control repositories (e.g. Git + repositories), including metadata, to be placed in the + :term:`DL_DIR` directory. + + For performance reasons, creating and placing tarballs of these + repositories is not the default action by the OpenEmbedded build + system. + :: + + BB_GENERATE_MIRROR_TARBALLS = "1" + + Set this variable in your + ``local.conf`` file in the :term:`Build Directory`. + + Once you have the tarballs containing your source files, you can + clean up your ``DL_DIR`` directory by deleting any Git or other + source control work directories. + + BB_NUMBER_THREADS + The maximum number of tasks BitBake should run in parallel at any one + time. The OpenEmbedded build system automatically configures this + variable to be equal to the number of cores on the build system. For + example, a system with a dual core processor that also uses + hyper-threading causes the ``BB_NUMBER_THREADS`` variable to default + to "4". + + For single socket systems (i.e. one CPU), you should not have to + override this variable to gain optimal parallelism during builds. + However, if you have very large systems that employ multiple physical + CPUs, you might want to make sure the ``BB_NUMBER_THREADS`` variable + is not set higher than "20". + + For more information on speeding up builds, see the + ":ref:`dev-manual/dev-manual-common-tasks:speeding up a build`" + section in the Yocto Project Development Tasks Manual. + + BB_SERVER_TIMEOUT + Specifies the time (in seconds) after which to unload the BitBake + server due to inactivity. Set ``BB_SERVER_TIMEOUT`` to determine how + long the BitBake server stays resident between invocations. + + For example, the following statement in your ``local.conf`` file + instructs the server to be unloaded after 20 seconds of inactivity: + :: + + BB_SERVER_TIMEOUT = "20" + + If you want the server to never be unloaded, + set ``BB_SERVER_TIMEOUT`` to "-1". + + BBCLASSEXTEND + Allows you to extend a recipe so that it builds variants of the + software. Common variants for recipes exist such as "natives" like + ``quilt-native``, which is a copy of Quilt built to run on the build + system; "crosses" such as ``gcc-cross``, which is a compiler built to + run on the build machine but produces binaries that run on the target + :term:`MACHINE`; "nativesdk", which targets the SDK + machine instead of ``MACHINE``; and "mulitlibs" in the form + "``multilib:``\ multilib_name". + + To build a different variant of the recipe with a minimal amount of + code, it usually is as simple as adding the following to your recipe: + :: + + BBCLASSEXTEND =+ "native nativesdk" + BBCLASSEXTEND =+ "multilib:multilib_name" + + .. note:: + + Internally, the ``BBCLASSEXTEND`` mechanism generates recipe + variants by rewriting variable values and applying overrides such + as ``_class-native``. For example, to generate a native version of + a recipe, a :term:`DEPENDS` on "foo" is rewritten + to a ``DEPENDS`` on "foo-native". + + Even when using ``BBCLASSEXTEND``, the recipe is only parsed once. + Parsing once adds some limitations. For example, it is not + possible to include a different file depending on the variant, + since ``include`` statements are processed when the recipe is + parsed. + + BBFILE_COLLECTIONS + Lists the names of configured layers. These names are used to find + the other ``BBFILE_*`` variables. Typically, each layer will append + its name to this variable in its ``conf/layer.conf`` file. + + BBFILE_PATTERN + Variable that expands to match files from + :term:`BBFILES` in a particular layer. This variable + is used in the ``conf/layer.conf`` file and must be suffixed with the + name of the specific layer (e.g. ``BBFILE_PATTERN_emenlow``). + + BBFILE_PRIORITY + Assigns the priority for recipe files in each layer. + + This variable is useful in situations where the same recipe appears + in more than one layer. Setting this variable allows you to + prioritize a layer against other layers that contain the same recipe + - effectively letting you control the precedence for the multiple + layers. The precedence established through this variable stands + regardless of a recipe's version (:term:`PV` variable). For + example, a layer that has a recipe with a higher ``PV`` value but for + which the ``BBFILE_PRIORITY`` is set to have a lower precedence still + has a lower precedence. + + A larger value for the ``BBFILE_PRIORITY`` variable results in a + higher precedence. For example, the value 6 has a higher precedence + than the value 5. If not specified, the ``BBFILE_PRIORITY`` variable + is set based on layer dependencies (see the ``LAYERDEPENDS`` variable + for more information. The default priority, if unspecified for a + layer with no dependencies, is the lowest defined priority + 1 (or 1 + if no priorities are defined). + + .. tip:: + + You can use the command + bitbake-layers show-layers + to list all configured layers along with their priorities. + + BBFILES + A space-separated list of recipe files BitBake uses to build + software. + + When specifying recipe files, you can pattern match using Python's + `glob <https://docs.python.org/3/library/glob.html>`_ syntax. + For details on the syntax, see the documentation by following the + previous link. + + BBFILES_DYNAMIC + Activates content when identified layers are present. You identify + the layers by the collections that the layers define. + + Use the ``BBFILES_DYNAMIC`` variable to avoid ``.bbappend`` files + whose corresponding ``.bb`` file is in a layer that attempts to + modify other layers through ``.bbappend`` but does not want to + introduce a hard dependency on those other layers. + + Use the following form for ``BBFILES_DYNAMIC``: + collection_name:filename_pattern The following example identifies two + collection names and two filename patterns: + :: + + BBFILES_DYNAMIC += " \ + clang-layer:${LAYERDIR}/bbappends/meta-clang/*/*/*.bbappend \ + core:${LAYERDIR}/bbappends/openembedded-core/meta/*/*/*.bbappend \ + " + + This next example shows an error message that occurs because invalid + entries are found, which cause parsing to abort: + :: + + ERROR: BBFILES_DYNAMIC entries must be of the form <collection name>:<filename pattern>, not: + /work/my-layer/bbappends/meta-security-isafw/*/*/*.bbappend + /work/my-layer/bbappends/openembedded-core/meta/*/*/*.bbappend + + BBINCLUDELOGS + Variable that controls how BitBake displays logs on build failure. + + BBINCLUDELOGS_LINES + If :term:`BBINCLUDELOGS` is set, specifies the + maximum number of lines from the task log file to print when + reporting a failed task. If you do not set ``BBINCLUDELOGS_LINES``, + the entire log is printed. + + BBLAYERS + Lists the layers to enable during the build. This variable is defined + in the ``bblayers.conf`` configuration file in the :term:`Build Directory`. + Here is an example: + :: + + BBLAYERS = " \ + /home/scottrif/poky/meta \ /home/scottrif/poky/meta-poky \ + /home/scottrif/poky/meta-yocto-bsp \ + /home/scottrif/poky/meta-mykernel \ + " + + This example enables four layers, one of which is a custom, + user-defined layer named ``meta-mykernel``. + + BBMASK + Prevents BitBake from processing recipes and recipe append files. + + You can use the ``BBMASK`` variable to "hide" these ``.bb`` and + ``.bbappend`` files. BitBake ignores any recipe or recipe append + files that match any of the expressions. It is as if BitBake does not + see them at all. Consequently, matching files are not parsed or + otherwise used by BitBake. + + The values you provide are passed to Python's regular expression + compiler. Consequently, the syntax follows Python's Regular + Expression (re) syntax. The expressions are compared against the full + paths to the files. For complete syntax information, see Python's + documentation at https://docs.python.org/3/library/re.html#regular-expression-syntax. + + The following example uses a complete regular expression to tell + BitBake to ignore all recipe and recipe append files in the + ``meta-ti/recipes-misc/`` directory: + :: + + BBMASK = "meta-ti/recipes-misc/" + + If you want to mask out multiple directories or recipes, you can + specify multiple regular expression fragments. This next example + masks out multiple directories and individual recipes: :: + + BBMASK += "/meta-ti/recipes-misc/ meta-ti/recipes-ti/packagegroup/" + BBMASK += "/meta-oe/recipes-support/" + BBMASK += "/meta-foo/.*/openldap" + BBMASK += "opencv.*\.bbappend" + BBMASK += "lzma" + + .. note:: + + When specifying a directory name, use the trailing slash character + to ensure you match just that directory name. + + BBMULTICONFIG + Specifies each additional separate configuration when you are + building targets with multiple configurations. Use this variable in + your ``conf/local.conf`` configuration file. Specify a + multiconfigname for each configuration file you are using. For + example, the following line specifies three configuration files: + :: + + BBMULTICONFIG = "configA configB configC" + + Each configuration file you + use must reside in the :term:`Build Directory` + ``conf/multiconfig`` directory (e.g. + build_directory\ ``/conf/multiconfig/configA.conf``). + + For information on how to use ``BBMULTICONFIG`` in an environment + that supports building targets with multiple configurations, see the + ":ref:`dev-building-images-for-multiple-targets-using-multiple-configurations`" + section in the Yocto Project Development Tasks Manual. + + BBPATH + Used by BitBake to locate ``.bbclass`` and configuration files. This + variable is analogous to the ``PATH`` variable. + + .. note:: + + If you run BitBake from a directory outside of the + Build Directory + , you must be sure to set + BBPATH + to point to the Build Directory. Set the variable as you would any + environment variable and then run BitBake: + :: + + $ BBPATH = "build_directory" + $ export BBPATH + $ bitbake target + + + BBSERVER + If defined in the BitBake environment, ``BBSERVER`` points to the + BitBake remote server. + + Use the following format to export the variable to the BitBake + environment: + :: + + export BBSERVER=localhost:$port + + By default, ``BBSERVER`` also appears in + :term:`bitbake:BB_HASHBASE_WHITELIST`. + Consequently, ``BBSERVER`` is excluded from checksum and dependency + data. + + BINCONFIG + When inheriting the + :ref:`binconfig-disabled <ref-classes-binconfig-disabled>` class, + this variable specifies binary configuration scripts to disable in + favor of using ``pkg-config`` to query the information. The + ``binconfig-disabled`` class will modify the specified scripts to + return an error so that calls to them can be easily found and + replaced. + + To add multiple scripts, separate them by spaces. Here is an example + from the ``libpng`` recipe: + :: + + BINCONFIG = "${bindir}/libpng-config ${bindir}/libpng16-config" + + BINCONFIG_GLOB + When inheriting the :ref:`binconfig <ref-classes-binconfig>` class, + this variable specifies a wildcard for configuration scripts that + need editing. The scripts are edited to correct any paths that have + been set up during compilation so that they are correct for use when + installed into the sysroot and called by the build processes of other + recipes. + + .. note:: + + The + BINCONFIG_GLOB + variable uses + shell globbing + , which is recognition and expansion of wildcards during pattern + matching. Shell globbing is very similar to + fnmatch + and + glob + . + + For more information on how this variable works, see + ``meta/classes/binconfig.bbclass`` in the :term:`Source Directory`. + You can also find general + information on the class in the + ":ref:`binconfig.bbclass <ref-classes-binconfig>`" section. + + BP + The base recipe name and version but without any special recipe name + suffix (i.e. ``-native``, ``lib64-``, and so forth). ``BP`` is + comprised of the following: + :: + + ${BPN}-${PV} + + BPN + This variable is a version of the :term:`PN` variable with + common prefixes and suffixes removed, such as ``nativesdk-``, + ``-cross``, ``-native``, and multilib's ``lib64-`` and ``lib32-``. + The exact lists of prefixes and suffixes removed are specified by the + :term:`MLPREFIX` and + :term:`SPECIAL_PKGSUFFIX` variables, + respectively. + + BUGTRACKER + Specifies a URL for an upstream bug tracking website for a recipe. + The OpenEmbedded build system does not use this variable. Rather, the + variable is a useful pointer in case a bug in the software being + built needs to be manually reported. + + BUILD_ARCH + Specifies the architecture of the build host (e.g. ``i686``). The + OpenEmbedded build system sets the value of ``BUILD_ARCH`` from the + machine name reported by the ``uname`` command. + + BUILD_AS_ARCH + Specifies the architecture-specific assembler flags for the build + host. By default, the value of ``BUILD_AS_ARCH`` is empty. + + BUILD_CC_ARCH + Specifies the architecture-specific C compiler flags for the build + host. By default, the value of ``BUILD_CC_ARCH`` is empty. + + BUILD_CCLD + Specifies the linker command to be used for the build host when the C + compiler is being used as the linker. By default, ``BUILD_CCLD`` + points to GCC and passes as arguments the value of + :term:`BUILD_CC_ARCH`, assuming + ``BUILD_CC_ARCH`` is set. + + BUILD_CFLAGS + Specifies the flags to pass to the C compiler when building for the + build host. When building in the ``-native`` context, + :term:`CFLAGS` is set to the value of this variable by + default. + + BUILD_CPPFLAGS + Specifies the flags to pass to the C preprocessor (i.e. to both the C + and the C++ compilers) when building for the build host. When + building in the ``-native`` context, :term:`CPPFLAGS` + is set to the value of this variable by default. + + BUILD_CXXFLAGS + Specifies the flags to pass to the C++ compiler when building for the + build host. When building in the ``-native`` context, + :term:`CXXFLAGS` is set to the value of this variable + by default. + + BUILD_FC + Specifies the Fortran compiler command for the build host. By + default, ``BUILD_FC`` points to Gfortran and passes as arguments the + value of :term:`BUILD_CC_ARCH`, assuming + ``BUILD_CC_ARCH`` is set. + + BUILD_LD + Specifies the linker command for the build host. By default, + ``BUILD_LD`` points to the GNU linker (ld) and passes as arguments + the value of :term:`BUILD_LD_ARCH`, assuming + ``BUILD_LD_ARCH`` is set. + + BUILD_LD_ARCH + Specifies architecture-specific linker flags for the build host. By + default, the value of ``BUILD_LD_ARCH`` is empty. + + BUILD_LDFLAGS + Specifies the flags to pass to the linker when building for the build + host. When building in the ``-native`` context, + :term:`LDFLAGS` is set to the value of this variable + by default. + + BUILD_OPTIMIZATION + Specifies the optimization flags passed to the C compiler when + building for the build host or the SDK. The flags are passed through + the :term:`BUILD_CFLAGS` and + :term:`BUILDSDK_CFLAGS` default values. + + The default value of the ``BUILD_OPTIMIZATION`` variable is "-O2 + -pipe". + + BUILD_OS + Specifies the operating system in use on the build host (e.g. + "linux"). The OpenEmbedded build system sets the value of + ``BUILD_OS`` from the OS reported by the ``uname`` command - the + first word, converted to lower-case characters. + + BUILD_PREFIX + The toolchain binary prefix used for native recipes. The OpenEmbedded + build system uses the ``BUILD_PREFIX`` value to set the + :term:`TARGET_PREFIX` when building for + ``native`` recipes. + + BUILD_STRIP + Specifies the command to be used to strip debugging symbols from + binaries produced for the build host. By default, ``BUILD_STRIP`` + points to + ``${``\ :term:`BUILD_PREFIX`\ ``}strip``. + + BUILD_SYS + Specifies the system, including the architecture and the operating + system, to use when building for the build host (i.e. when building + ``native`` recipes). + + The OpenEmbedded build system automatically sets this variable based + on :term:`BUILD_ARCH`, + :term:`BUILD_VENDOR`, and + :term:`BUILD_OS`. You do not need to set the + ``BUILD_SYS`` variable yourself. + + BUILD_VENDOR + Specifies the vendor name to use when building for the build host. + The default value is an empty string (""). + + BUILDDIR + Points to the location of the :term:`Build Directory`. + You can define this directory indirectly through the + ````` <#structure-core-script>`__ script by passing in a Build + Directory path when you run the script. If you run the script and do + not provide a Build Directory path, the ``BUILDDIR`` defaults to + ``build`` in the current directory. + + BUILDHISTORY_COMMIT + When inheriting the :ref:`buildhistory <ref-classes-buildhistory>` + class, this variable specifies whether or not to commit the build + history output in a local Git repository. If set to "1", this local + repository will be maintained automatically by the ``buildhistory`` + class and a commit will be created on every build for changes to each + top-level subdirectory of the build history output (images, packages, + and sdk). If you want to track changes to build history over time, + you should set this value to "1". + + By default, the ``buildhistory`` class does not commit the build + history output in a local Git repository: + :: + + BUILDHISTORY_COMMIT ?= "0" + + BUILDHISTORY_COMMIT_AUTHOR + When inheriting the :ref:`buildhistory <ref-classes-buildhistory>` + class, this variable specifies the author to use for each Git commit. + In order for the ``BUILDHISTORY_COMMIT_AUTHOR`` variable to work, the + :term:`BUILDHISTORY_COMMIT` variable must + be set to "1". + + Git requires that the value you provide for the + ``BUILDHISTORY_COMMIT_AUTHOR`` variable takes the form of "name + email@host". Providing an email address or host that is not valid + does not produce an error. + + By default, the ``buildhistory`` class sets the variable as follows: + :: + + BUILDHISTORY_COMMIT_AUTHOR ?= "buildhistory <buildhistory@${DISTRO}>" + + BUILDHISTORY_DIR + When inheriting the :ref:`buildhistory <ref-classes-buildhistory>` + class, this variable specifies the directory in which build history + information is kept. For more information on how the variable works, + see the ``buildhistory.class``. + + By default, the ``buildhistory`` class sets the directory as follows: + :: + + BUILDHISTORY_DIR ?= "${TOPDIR}/buildhistory" + + BUILDHISTORY_FEATURES + When inheriting the :ref:`buildhistory <ref-classes-buildhistory>` + class, this variable specifies the build history features to be + enabled. For more information on how build history works, see the + ":ref:`dev-manual/dev-manual-common-tasks:maintaining build output quality`" + section in the Yocto Project Development Tasks Manual. + + You can specify these features in the form of a space-separated list: + + - *image:* Analysis of the contents of images, which includes the + list of installed packages among other things. + + - *package:* Analysis of the contents of individual packages. + + - *sdk:* Analysis of the contents of the software development kit + (SDK). + + - *task:* Save output file signatures for + :ref:`shared state <overview-manual/overview-manual-concepts:shared state cache>` + (sstate) tasks. + This saves one file per task and lists the SHA-256 checksums for + each file staged (i.e. the output of the task). + + By default, the ``buildhistory`` class enables the following + features: + :: + + BUILDHISTORY_FEATURES ?= "image package sdk" + + BUILDHISTORY_IMAGE_FILES + When inheriting the :ref:`buildhistory <ref-classes-buildhistory>` + class, this variable specifies a list of paths to files copied from + the image contents into the build history directory under an + "image-files" directory in the directory for the image, so that you + can track the contents of each file. The default is to copy + ``/etc/passwd`` and ``/etc/group``, which allows you to monitor for + changes in user and group entries. You can modify the list to include + any file. Specifying an invalid path does not produce an error. + Consequently, you can include files that might not always be present. + + By default, the ``buildhistory`` class provides paths to the + following files: + :: + + BUILDHISTORY_IMAGE_FILES ?= "/etc/passwd /etc/group" + + BUILDHISTORY_PUSH_REPO + When inheriting the :ref:`buildhistory <ref-classes-buildhistory>` + class, this variable optionally specifies a remote repository to + which build history pushes Git changes. In order for + ``BUILDHISTORY_PUSH_REPO`` to work, + :term:`BUILDHISTORY_COMMIT` must be set to + "1". + + The repository should correspond to a remote address that specifies a + repository as understood by Git, or alternatively to a remote name + that you have set up manually using ``git remote`` within the local + repository. + + By default, the ``buildhistory`` class sets the variable as follows: + :: + + BUILDHISTORY_PUSH_REPO ?= "" + + BUILDSDK_CFLAGS + Specifies the flags to pass to the C compiler when building for the + SDK. When building in the ``nativesdk-`` context, + :term:`CFLAGS` is set to the value of this variable by + default. + + BUILDSDK_CPPFLAGS + Specifies the flags to pass to the C pre-processor (i.e. to both the + C and the C++ compilers) when building for the SDK. When building in + the ``nativesdk-`` context, :term:`CPPFLAGS` is set + to the value of this variable by default. + + BUILDSDK_CXXFLAGS + Specifies the flags to pass to the C++ compiler when building for the + SDK. When building in the ``nativesdk-`` context, + :term:`CXXFLAGS` is set to the value of this variable + by default. + + BUILDSDK_LDFLAGS + Specifies the flags to pass to the linker when building for the SDK. + When building in the ``nativesdk-`` context, + :term:`LDFLAGS` is set to the value of this variable + by default. + + BUILDSTATS_BASE + Points to the location of the directory that holds build statistics + when you use and enable the + :ref:`buildstats <ref-classes-buildstats>` class. The + ``BUILDSTATS_BASE`` directory defaults to + ``${``\ :term:`TMPDIR`\ ``}/buildstats/``. + + BUSYBOX_SPLIT_SUID + For the BusyBox recipe, specifies whether to split the output + executable file into two parts: one for features that require + ``setuid root``, and one for the remaining features (i.e. those that + do not require ``setuid root``). + + The ``BUSYBOX_SPLIT_SUID`` variable defaults to "1", which results in + splitting the output executable file. Set the variable to "0" to get + a single output executable file. + + CACHE + Specifies the directory BitBake uses to store a cache of the + :term:`Metadata` so it does not need to be parsed every time + BitBake is started. + + CC + The minimal command and arguments used to run the C compiler. + + CFLAGS + Specifies the flags to pass to the C compiler. This variable is + exported to an environment variable and thus made visible to the + software being built during the compilation step. + + Default initialization for ``CFLAGS`` varies depending on what is + being built: + + - :term:`TARGET_CFLAGS` when building for the + target + + - :term:`BUILD_CFLAGS` when building for the + build host (i.e. ``-native``) + + - :term:`BUILDSDK_CFLAGS` when building for + an SDK (i.e. ``nativesdk-``) + + CLASSOVERRIDE + An internal variable specifying the special class override that + should currently apply (e.g. "class-target", "class-native", and so + forth). The classes that use this variable (e.g. + :ref:`native <ref-classes-native>`, + :ref:`nativesdk <ref-classes-nativesdk>`, and so forth) set the + variable to appropriate values. + + .. note:: + + CLASSOVERRIDE + gets its default "class-target" value from the + bitbake.conf + file. + + As an example, the following override allows you to install extra + files, but only when building for the target: + :: + + do_install_append_class-target() { + install my-extra-file ${D}${sysconfdir} + } + + Here is an example where ``FOO`` is set to + "native" when building for the build host, and to "other" when not + building for the build host: + :: + + FOO_class-native = "native" + FOO = "other" + + The underlying mechanism behind ``CLASSOVERRIDE`` is simply + that it is included in the default value of + :term:`OVERRIDES`. + + CLEANBROKEN + If set to "1" within a recipe, ``CLEANBROKEN`` specifies that the + ``make clean`` command does not work for the software being built. + Consequently, the OpenEmbedded build system will not try to run + ``make clean`` during the :ref:`ref-tasks-configure` + task, which is the default behavior. + + COMBINED_FEATURES + Provides a list of hardware features that are enabled in both + :term:`MACHINE_FEATURES` and + :term:`DISTRO_FEATURES`. This select list of + features contains features that make sense to be controlled both at + the machine and distribution configuration level. For example, the + "bluetooth" feature requires hardware support but should also be + optional at the distribution level, in case the hardware supports + Bluetooth but you do not ever intend to use it. + + COMMON_LICENSE_DIR + Points to ``meta/files/common-licenses`` in the + :term:`Source Directory`, which is where generic license + files reside. + + COMPATIBLE_HOST + A regular expression that resolves to one or more hosts (when the + recipe is native) or one or more targets (when the recipe is + non-native) with which a recipe is compatible. The regular expression + is matched against :term:`HOST_SYS`. You can use the + variable to stop recipes from being built for classes of systems with + which the recipes are not compatible. Stopping these builds is + particularly useful with kernels. The variable also helps to increase + parsing speed since the build system skips parsing recipes not + compatible with the current system. + + COMPATIBLE_MACHINE + A regular expression that resolves to one or more target machines + with which a recipe is compatible. The regular expression is matched + against :term:`MACHINEOVERRIDES`. You can use + the variable to stop recipes from being built for machines with which + the recipes are not compatible. Stopping these builds is particularly + useful with kernels. The variable also helps to increase parsing + speed since the build system skips parsing recipes not compatible + with the current machine. + + COMPLEMENTARY_GLOB + Defines wildcards to match when installing a list of complementary + packages for all the packages explicitly (or implicitly) installed in + an image. + + .. note:: + + The + COMPLEMENTARY_GLOB + variable uses Unix filename pattern matching ( + fnmatch + ), which is similar to the Unix style pathname pattern expansion ( + glob + ). + + The resulting list of complementary packages is associated with an + item that can be added to + :term:`IMAGE_FEATURES`. An example usage of + this is the "dev-pkgs" item that when added to ``IMAGE_FEATURES`` + will install -dev packages (containing headers and other development + files) for every package in the image. + + To add a new feature item pointing to a wildcard, use a variable flag + to specify the feature item name and use the value to specify the + wildcard. Here is an example: + :: + + COMPLEMENTARY_GLOB[dev-pkgs] = '*-dev' + + COMPONENTS_DIR + Stores sysroot components for each recipe. The OpenEmbedded build + system uses ``COMPONENTS_DIR`` when constructing recipe-specific + sysroots for other recipes. + + The default is + "``${``\ :term:`STAGING_DIR`\ ``}-components``." + (i.e. + "``${``\ :term:`TMPDIR`\ ``}/sysroots-components``"). + + CONF_VERSION + Tracks the version of the local configuration file (i.e. + ``local.conf``). The value for ``CONF_VERSION`` increments each time + ``build/conf/`` compatibility changes. + + CONFFILES + Identifies editable or configurable files that are part of a package. + If the Package Management System (PMS) is being used to update + packages on the target system, it is possible that configuration + files you have changed after the original installation and that you + now want to remain unchanged are overwritten. In other words, + editable files might exist in the package that you do not want reset + as part of the package update process. You can use the ``CONFFILES`` + variable to list the files in the package that you wish to prevent + the PMS from overwriting during this update process. + + To use the ``CONFFILES`` variable, provide a package name override + that identifies the resulting package. Then, provide a + space-separated list of files. Here is an example: + :: + + CONFFILES_${PN} += "${sysconfdir}/file1 \ + ${sysconfdir}/file2 ${sysconfdir}/file3" + + A relationship exists between the ``CONFFILES`` and ``FILES`` + variables. The files listed within ``CONFFILES`` must be a subset of + the files listed within ``FILES``. Because the configuration files + you provide with ``CONFFILES`` are simply being identified so that + the PMS will not overwrite them, it makes sense that the files must + already be included as part of the package through the ``FILES`` + variable. + + .. note:: + + When specifying paths as part of the + CONFFILES + variable, it is good practice to use appropriate path variables. + For example, + ${sysconfdir} + rather than + /etc + or + ${bindir} + rather than + /usr/bin + . You can find a list of these variables at the top of the + meta/conf/bitbake.conf + file in the + Source Directory + . + + CONFIG_INITRAMFS_SOURCE + Identifies the initial RAM filesystem (initramfs) source files. The + OpenEmbedded build system receives and uses this kernel Kconfig + variable as an environment variable. By default, the variable is set + to null (""). + + The ``CONFIG_INITRAMFS_SOURCE`` can be either a single cpio archive + with a ``.cpio`` suffix or a space-separated list of directories and + files for building the initramfs image. A cpio archive should contain + a filesystem archive to be used as an initramfs image. Directories + should contain a filesystem layout to be included in the initramfs + image. Files should contain entries according to the format described + by the ``usr/gen_init_cpio`` program in the kernel tree. + + If you specify multiple directories and files, the initramfs image + will be the aggregate of all of them. + + For information on creating an initramfs, see the + ":ref:`building-an-initramfs-image`" section + in the Yocto Project Development Tasks Manual. + + CONFIG_SITE + A list of files that contains ``autoconf`` test results relevant to + the current build. This variable is used by the Autotools utilities + when running ``configure``. + + CONFIGURE_FLAGS + The minimal arguments for GNU configure. + + CONFLICT_DISTRO_FEATURES + When inheriting the + :ref:`distro_features_check <ref-classes-distro_features_check>` + class, this variable identifies distribution features that would be + in conflict should the recipe be built. In other words, if the + ``CONFLICT_DISTRO_FEATURES`` variable lists a feature that also + appears in ``DISTRO_FEATURES`` within the current configuration, an + error occurs and the build stops. + + COPYLEFT_LICENSE_EXCLUDE + A space-separated list of licenses to exclude from the source + archived by the :ref:`archiver <ref-classes-archiver>` class. In + other words, if a license in a recipe's + :term:`LICENSE` value is in the value of + ``COPYLEFT_LICENSE_EXCLUDE``, then its source is not archived by the + class. + + .. note:: + + The + COPYLEFT_LICENSE_EXCLUDE + variable takes precedence over the + COPYLEFT_LICENSE_INCLUDE + variable. + + The default value, which is "CLOSED Proprietary", for + ``COPYLEFT_LICENSE_EXCLUDE`` is set by the + :ref:`copyleft_filter <ref-classes-copyleft_filter>` class, which + is inherited by the ``archiver`` class. + + COPYLEFT_LICENSE_INCLUDE + A space-separated list of licenses to include in the source archived + by the :ref:`archiver <ref-classes-archiver>` class. In other + words, if a license in a recipe's :term:`LICENSE` + value is in the value of ``COPYLEFT_LICENSE_INCLUDE``, then its + source is archived by the class. + + The default value is set by the + :ref:`copyleft_filter <ref-classes-copyleft_filter>` class, which + is inherited by the ``archiver`` class. The default value includes + "GPL*", "LGPL*", and "AGPL*". + + COPYLEFT_PN_EXCLUDE + A list of recipes to exclude in the source archived by the + :ref:`archiver <ref-classes-archiver>` class. The + ``COPYLEFT_PN_EXCLUDE`` variable overrides the license inclusion and + exclusion caused through the + :term:`COPYLEFT_LICENSE_INCLUDE` and + :term:`COPYLEFT_LICENSE_EXCLUDE` + variables, respectively. + + The default value, which is "" indicating to not explicitly exclude + any recipes by name, for ``COPYLEFT_PN_EXCLUDE`` is set by the + :ref:`copyleft_filter <ref-classes-copyleft_filter>` class, which + is inherited by the ``archiver`` class. + + COPYLEFT_PN_INCLUDE + A list of recipes to include in the source archived by the + :ref:`archiver <ref-classes-archiver>` class. The + ``COPYLEFT_PN_INCLUDE`` variable overrides the license inclusion and + exclusion caused through the + :term:`COPYLEFT_LICENSE_INCLUDE` and + :term:`COPYLEFT_LICENSE_EXCLUDE` + variables, respectively. + + The default value, which is "" indicating to not explicitly include + any recipes by name, for ``COPYLEFT_PN_INCLUDE`` is set by the + :ref:`copyleft_filter <ref-classes-copyleft_filter>` class, which + is inherited by the ``archiver`` class. + + COPYLEFT_RECIPE_TYPES + A space-separated list of recipe types to include in the source + archived by the :ref:`archiver <ref-classes-archiver>` class. + Recipe types are ``target``, ``native``, ``nativesdk``, ``cross``, + ``crosssdk``, and ``cross-canadian``. + + The default value, which is "target*", for ``COPYLEFT_RECIPE_TYPES`` + is set by the :ref:`copyleft_filter <ref-classes-copyleft_filter>` + class, which is inherited by the ``archiver`` class. + + COPY_LIC_DIRS + If set to "1" along with the + :term:`COPY_LIC_MANIFEST` variable, the + OpenEmbedded build system copies into the image the license files, + which are located in ``/usr/share/common-licenses``, for each + package. The license files are placed in directories within the image + itself during build time. + + .. note:: + + The + COPY_LIC_DIRS + does not offer a path for adding licenses for newly installed + packages to an image, which might be most suitable for read-only + filesystems that cannot be upgraded. See the + LICENSE_CREATE_PACKAGE + variable for additional information. You can also reference the " + Providing License Text + " section in the Yocto Project Development Tasks Manual for + information on providing license text. + + COPY_LIC_MANIFEST + If set to "1", the OpenEmbedded build system copies the license + manifest for the image to + ``/usr/share/common-licenses/license.manifest`` within the image + itself during build time. + + .. note:: + + The + COPY_LIC_MANIFEST + does not offer a path for adding licenses for newly installed + packages to an image, which might be most suitable for read-only + filesystems that cannot be upgraded. See the + LICENSE_CREATE_PACKAGE + variable for additional information. You can also reference the " + Providing License Text + " section in the Yocto Project Development Tasks Manual for + information on providing license text. + + CORE_IMAGE_EXTRA_INSTALL + Specifies the list of packages to be added to the image. You should + only set this variable in the ``local.conf`` configuration file found + in the :term:`Build Directory`. + + This variable replaces ``POKY_EXTRA_INSTALL``, which is no longer + supported. + + COREBASE + Specifies the parent directory of the OpenEmbedded-Core Metadata + layer (i.e. ``meta``). + + It is an important distinction that ``COREBASE`` points to the parent + of this layer and not the layer itself. Consider an example where you + have cloned the Poky Git repository and retained the ``poky`` name + for your local copy of the repository. In this case, ``COREBASE`` + points to the ``poky`` folder because it is the parent directory of + the ``poky/meta`` layer. + + COREBASE_FILES + Lists files from the :term:`COREBASE` directory that + should be copied other than the layers listed in the + ``bblayers.conf`` file. The ``COREBASE_FILES`` variable exists for + the purpose of copying metadata from the OpenEmbedded build system + into the extensible SDK. + + Explicitly listing files in ``COREBASE`` is needed because it + typically contains build directories and other files that should not + normally be copied into the extensible SDK. Consequently, the value + of ``COREBASE_FILES`` is used in order to only copy the files that + are actually needed. + + CPP + The minimal command and arguments used to run the C preprocessor. + + CPPFLAGS + Specifies the flags to pass to the C pre-processor (i.e. to both the + C and the C++ compilers). This variable is exported to an environment + variable and thus made visible to the software being built during the + compilation step. + + Default initialization for ``CPPFLAGS`` varies depending on what is + being built: + + - :term:`TARGET_CPPFLAGS` when building for + the target + + - :term:`BUILD_CPPFLAGS` when building for the + build host (i.e. ``-native``) + + - :term:`BUILDSDK_CPPFLAGS` when building + for an SDK (i.e. ``nativesdk-``) + + CROSS_COMPILE + The toolchain binary prefix for the target tools. The + ``CROSS_COMPILE`` variable is the same as the + :term:`TARGET_PREFIX` variable. + + .. note:: + + The OpenEmbedded build system sets the + CROSS_COMPILE + variable only in certain contexts (e.g. when building for kernel + and kernel module recipes). + + CVSDIR + The directory in which files checked out under the CVS system are + stored. + + CXX + The minimal command and arguments used to run the C++ compiler. + + CXXFLAGS + Specifies the flags to pass to the C++ compiler. This variable is + exported to an environment variable and thus made visible to the + software being built during the compilation step. + + Default initialization for ``CXXFLAGS`` varies depending on what is + being built: + + - :term:`TARGET_CXXFLAGS` when building for + the target + + - :term:`BUILD_CXXFLAGS` when building for the + build host (i.e. ``-native``) + + - :term:`BUILDSDK_CXXFLAGS` when building + for an SDK (i.e. ``nativesdk-``) + + D + The destination directory. The location in the :term:`Build Directory` + where components are installed by the + :ref:`ref-tasks-install` task. This location defaults + to: + :: + + ${WORKDIR}/image + + .. note:: + + Tasks that read from or write to this directory should run under + fakeroot + . + + DATE + The date the build was started. Dates appear using the year, month, + and day (YMD) format (e.g. "20150209" for February 9th, 2015). + + DATETIME + The date and time on which the current build started. The format is + suitable for timestamps. + + DEBIAN_NOAUTONAME + When the :ref:`debian <ref-classes-debian>` class is inherited, + which is the default behavior, ``DEBIAN_NOAUTONAME`` specifies a + particular package should not be renamed according to Debian library + package naming. You must use the package name as an override when you + set this variable. Here is an example from the ``fontconfig`` recipe: + :: + + DEBIAN_NOAUTONAME_fontconfig-utils = "1" + + DEBIANNAME + When the :ref:`debian <ref-classes-debian>` class is inherited, + which is the default behavior, ``DEBIANNAME`` allows you to override + the library name for an individual package. Overriding the library + name in these cases is rare. You must use the package name as an + override when you set this variable. Here is an example from the + ``dbus`` recipe: + :: + + DEBIANNAME_${PN} = "dbus-1" + + DEBUG_BUILD + Specifies to build packages with debugging information. This + influences the value of the ``SELECTED_OPTIMIZATION`` variable. + + DEBUG_OPTIMIZATION + The options to pass in ``TARGET_CFLAGS`` and ``CFLAGS`` when + compiling a system for debugging. This variable defaults to "-O + -fno-omit-frame-pointer ${DEBUG_FLAGS} -pipe". + + DEFAULT_PREFERENCE + Specifies a weak bias for recipe selection priority. + + The most common usage of this is variable is to set it to "-1" within + a recipe for a development version of a piece of software. Using the + variable in this way causes the stable version of the recipe to build + by default in the absence of ``PREFERRED_VERSION`` being used to + build the development version. + + .. note:: + + The bias provided by + DEFAULT_PREFERENCE + is weak and is overridden by + BBFILE_PRIORITY + if that variable is different between two layers that contain + different versions of the same recipe. + + DEFAULTTUNE + The default CPU and Application Binary Interface (ABI) tunings (i.e. + the "tune") used by the OpenEmbedded build system. The + ``DEFAULTTUNE`` helps define + :term:`TUNE_FEATURES`. + + The default tune is either implicitly or explicitly set by the + machine (:term:`MACHINE`). However, you can override + the setting using available tunes as defined with + :term:`AVAILTUNES`. + + DEPENDS + Lists a recipe's build-time dependencies. These are dependencies on + other recipes whose contents (e.g. headers and shared libraries) are + needed by the recipe at build time. + + As an example, consider a recipe ``foo`` that contains the following + assignment: + :: + + DEPENDS = "bar" + + The practical effect of the previous + assignment is that all files installed by bar will be available in + the appropriate staging sysroot, given by the + :term:`STAGING_DIR* <STAGING_DIR>` variables, by the time the + :ref:`ref-tasks-configure` task for ``foo`` runs. + This mechanism is implemented by having ``do_configure`` depend on + the :ref:`ref-tasks-populate_sysroot` task of + each recipe listed in ``DEPENDS``, through a + ``[``\ :ref:`deptask <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:variable flags>`\ ``]`` + declaration in the :ref:`base <ref-classes-base>` class. + + .. note:: + + It seldom is necessary to reference, for example, + STAGING_DIR_HOST + explicitly. The standard classes and build-related variables are + configured to automatically use the appropriate staging sysroots. + + As another example, ``DEPENDS`` can also be used to add utilities + that run on the build machine during the build. For example, a recipe + that makes use of a code generator built by the recipe ``codegen`` + might have the following: + :: + + DEPENDS = "codegen-native" + + For more + information, see the :ref:`native <ref-classes-native>` class and + the :term:`EXTRANATIVEPATH` variable. + + .. note:: + + - ``DEPENDS`` is a list of recipe names. Or, to be more precise, + it is a list of :term:`PROVIDES` names, which + usually match recipe names. Putting a package name such as + "foo-dev" in ``DEPENDS`` does not make sense. Use "foo" + instead, as this will put files from all the packages that make + up ``foo``, which includes those from ``foo-dev``, into the + sysroot. + + - One recipe having another recipe in ``DEPENDS`` does not by + itself add any runtime dependencies between the packages + produced by the two recipes. However, as explained in the + ":ref:`overview-manual/overview-manual-concepts:automatically added runtime dependencies`" + section in the Yocto Project Overview and Concepts Manual, + runtime dependencies will often be added automatically, meaning + ``DEPENDS`` alone is sufficient for most recipes. + + - Counterintuitively, ``DEPENDS`` is often necessary even for + recipes that install precompiled components. For example, if + ``libfoo`` is a precompiled library that links against + ``libbar``, then linking against ``libfoo`` requires both + ``libfoo`` and ``libbar`` to be available in the sysroot. + Without a ``DEPENDS`` from the recipe that installs ``libfoo`` + to the recipe that installs ``libbar``, other recipes might + fail to link against ``libfoo``. + + For information on runtime dependencies, see the + :term:`RDEPENDS` variable. You can also see the + ":ref:`Tasks <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:tasks>`" and + ":ref:`Dependencies <bitbake:bitbake-user-manual/bitbake-user-manual-execution:dependencies>`" sections in the + BitBake User Manual for additional information on tasks and + dependencies. + + DEPLOY_DIR + Points to the general area that the OpenEmbedded build system uses to + place images, packages, SDKs, and other output files that are ready + to be used outside of the build system. By default, this directory + resides within the :term:`Build Directory` as + ``${TMPDIR}/deploy``. + + For more information on the structure of the Build Directory, see + ":ref:`ref-manual/ref-structure:the build directory - \`\`build/\`\``" section. + For more detail on the contents of the ``deploy`` directory, see the + ":ref:`Images <images-dev-environment>`", ":ref:`Package + Feeds <package-feeds-dev-environment>`", and + ":ref:`sdk-dev-environment`" sections all in the + Yocto Project Overview and Concepts Manual. + + DEPLOY_DIR_DEB + Points to the area that the OpenEmbedded build system uses to place + Debian packages that are ready to be used outside of the build + system. This variable applies only when + :term:`PACKAGE_CLASSES` contains + "package_deb". + + The BitBake configuration file initially defines the + ``DEPLOY_DIR_DEB`` variable as a sub-folder of + :term:`DEPLOY_DIR`: + :: + + DEPLOY_DIR_DEB = "${DEPLOY_DIR}/deb" + + The :ref:`package_deb <ref-classes-package_deb>` class uses the + ``DEPLOY_DIR_DEB`` variable to make sure the + :ref:`ref-tasks-package_write_deb` task + writes Debian packages into the appropriate folder. For more + information on how packaging works, see the ":ref:`Package + Feeds <package-feeds-dev-environment>`" section + in the Yocto Project Overview and Concepts Manual. + + DEPLOY_DIR_IMAGE + Points to the area that the OpenEmbedded build system uses to place + images and other associated output files that are ready to be + deployed onto the target machine. The directory is machine-specific + as it contains the ``${MACHINE}`` name. By default, this directory + resides within the :term:`Build Directory` as + ``${DEPLOY_DIR}/images/${MACHINE}/``. + + For more information on the structure of the Build Directory, see + ":ref:`ref-manual/ref-structure:the build directory - \`\`build/\`\``" section. + For more detail on the contents of the ``deploy`` directory, see the + ":ref:`Images <images-dev-environment>`" and + ":ref:`sdk-dev-environment`" sections both in + the Yocto Project Overview and Concepts Manual. + + DEPLOY_DIR_IPK + Points to the area that the OpenEmbedded build system uses to place + IPK packages that are ready to be used outside of the build system. + This variable applies only when + :term:`PACKAGE_CLASSES` contains + "package_ipk". + + The BitBake configuration file initially defines this variable as a + sub-folder of :term:`DEPLOY_DIR`: + :: + + DEPLOY_DIR_IPK = "${DEPLOY_DIR}/ipk" + + The :ref:`package_ipk <ref-classes-package_ipk>` class uses the + ``DEPLOY_DIR_IPK`` variable to make sure the + :ref:`ref-tasks-package_write_ipk` task + writes IPK packages into the appropriate folder. For more information + on how packaging works, see the ":ref:`Package + Feeds <package-feeds-dev-environment>`" section + in the Yocto Project Overview and Concepts Manual. + + DEPLOY_DIR_RPM + Points to the area that the OpenEmbedded build system uses to place + RPM packages that are ready to be used outside of the build system. + This variable applies only when + :term:`PACKAGE_CLASSES` contains + "package_rpm". + + The BitBake configuration file initially defines this variable as a + sub-folder of :term:`DEPLOY_DIR`: + :: + + DEPLOY_DIR_RPM = "${DEPLOY_DIR}/rpm" + + The :ref:`package_rpm <ref-classes-package_rpm>` class uses the + ``DEPLOY_DIR_RPM`` variable to make sure the + :ref:`ref-tasks-package_write_rpm` task + writes RPM packages into the appropriate folder. For more information + on how packaging works, see the ":ref:`Package + Feeds <package-feeds-dev-environment>`" section + in the Yocto Project Overview and Concepts Manual. + + DEPLOY_DIR_TAR + Points to the area that the OpenEmbedded build system uses to place + tarballs that are ready to be used outside of the build system. This + variable applies only when + :term:`PACKAGE_CLASSES` contains + "package_tar". + + The BitBake configuration file initially defines this variable as a + sub-folder of :term:`DEPLOY_DIR`: + :: + + DEPLOY_DIR_TAR = "${DEPLOY_DIR}/tar" + + The :ref:`package_tar <ref-classes-package_tar>` class uses the + ``DEPLOY_DIR_TAR`` variable to make sure the + :ref:`ref-tasks-package_write_tar` task + writes TAR packages into the appropriate folder. For more information + on how packaging works, see the ":ref:`Package + Feeds <package-feeds-dev-environment>`" section + in the Yocto Project Overview and Concepts Manual. + + DEPLOYDIR + When inheriting the :ref:`deploy <ref-classes-deploy>` class, the + ``DEPLOYDIR`` points to a temporary work area for deployed files that + is set in the ``deploy`` class as follows: + :: + + DEPLOYDIR = "${WORKDIR}/deploy-${:term:`PN`}" + + Recipes inheriting the ``deploy`` class should copy files to be + deployed into ``DEPLOYDIR``, and the class will take care of copying + them into :term:`DEPLOY_DIR_IMAGE` + afterwards. + + DESCRIPTION + The package description used by package managers. If not set, + ``DESCRIPTION`` takes the value of the :term:`SUMMARY` + variable. + + DISTRO + The short name of the distribution. For information on the long name + of the distribution, see the :term:`DISTRO_NAME` + variable. + + The ``DISTRO`` variable corresponds to a distribution configuration + file whose root name is the same as the variable's argument and whose + filename extension is ``.conf``. For example, the distribution + configuration file for the Poky distribution is named ``poky.conf`` + and resides in the ``meta-poky/conf/distro`` directory of the + :term:`Source Directory`. + + Within that ``poky.conf`` file, the ``DISTRO`` variable is set as + follows: + :: + + DISTRO = "poky" + + Distribution configuration files are located in a ``conf/distro`` + directory within the :term:`Metadata` that contains the + distribution configuration. The value for ``DISTRO`` must not contain + spaces, and is typically all lower-case. + + .. note:: + + If the + DISTRO + variable is blank, a set of default configurations are used, which + are specified within + meta/conf/distro/defaultsetup.conf + also in the Source Directory. + + DISTRO_CODENAME + Specifies a codename for the distribution being built. + + DISTRO_EXTRA_RDEPENDS + Specifies a list of distro-specific packages to add to all images. + This variable takes affect through ``packagegroup-base`` so the + variable only really applies to the more full-featured images that + include ``packagegroup-base``. You can use this variable to keep + distro policy out of generic images. As with all other distro + variables, you set this variable in the distro ``.conf`` file. + + DISTRO_EXTRA_RRECOMMENDS + Specifies a list of distro-specific packages to add to all images if + the packages exist. The packages might not exist or be empty (e.g. + kernel modules). The list of packages are automatically installed but + you can remove them. + + DISTRO_FEATURES + The software support you want in your distribution for various + features. You define your distribution features in the distribution + configuration file. + + In most cases, the presence or absence of a feature in + ``DISTRO_FEATURES`` is translated to the appropriate option supplied + to the configure script during the + :ref:`ref-tasks-configure` task for recipes that + optionally support the feature. For example, specifying "x11" in + ``DISTRO_FEATURES``, causes every piece of software built for the + target that can optionally support X11 to have its X11 support + enabled. + + Two more examples are Bluetooth and NFS support. For a more complete + list of features that ships with the Yocto Project and that you can + provide with this variable, see the "`Distro + Features <#ref-features-distro>`__" section. + + DISTRO_FEATURES_BACKFILL + Features to be added to ``DISTRO_FEATURES`` if not also present in + ``DISTRO_FEATURES_BACKFILL_CONSIDERED``. + + This variable is set in the ``meta/conf/bitbake.conf`` file. It is + not intended to be user-configurable. It is best to just reference + the variable to see which distro features are being backfilled for + all distro configurations. See the "`Feature + Backfilling <#ref-features-backfill>`__" section for more + information. + + DISTRO_FEATURES_BACKFILL_CONSIDERED + Features from ``DISTRO_FEATURES_BACKFILL`` that should not be + backfilled (i.e. added to ``DISTRO_FEATURES``) during the build. See + the "`Feature Backfilling <#ref-features-backfill>`__" section for + more information. + + DISTRO_FEATURES_DEFAULT + A convenience variable that gives you the default list of distro + features with the exception of any features specific to the C library + (``libc``). + + When creating a custom distribution, you might find it useful to be + able to reuse the default + :term:`DISTRO_FEATURES` options without the + need to write out the full set. Here is an example that uses + ``DISTRO_FEATURES_DEFAULT`` from a custom distro configuration file: + :: + + DISTRO_FEATURES ?= "${DISTRO_FEATURES_DEFAULT} myfeature" + + DISTRO_FEATURES_FILTER_NATIVE + Specifies a list of features that if present in the target + :term:`DISTRO_FEATURES` value should be + included in ``DISTRO_FEATURES`` when building native recipes. This + variable is used in addition to the features filtered using the + :term:`DISTRO_FEATURES_NATIVE` + variable. + + DISTRO_FEATURES_FILTER_NATIVESDK + Specifies a list of features that if present in the target + :term:`DISTRO_FEATURES` value should be + included in ``DISTRO_FEATURES`` when building nativesdk recipes. This + variable is used in addition to the features filtered using the + :term:`DISTRO_FEATURES_NATIVESDK` + variable. + + DISTRO_FEATURES_NATIVE + Specifies a list of features that should be included in + :term:`DISTRO_FEATURES` when building native + recipes. This variable is used in addition to the features filtered + using the + :term:`DISTRO_FEATURES_FILTER_NATIVE` + variable. + + DISTRO_FEATURES_NATIVESDK + Specifies a list of features that should be included in + :term:`DISTRO_FEATURES` when building + nativesdk recipes. This variable is used in addition to the features + filtered using the + :term:`DISTRO_FEATURES_FILTER_NATIVESDK` + variable. + + DISTRO_NAME + The long name of the distribution. For information on the short name + of the distribution, see the :term:`DISTRO` variable. + + The ``DISTRO_NAME`` variable corresponds to a distribution + configuration file whose root name is the same as the variable's + argument and whose filename extension is ``.conf``. For example, the + distribution configuration file for the Poky distribution is named + ``poky.conf`` and resides in the ``meta-poky/conf/distro`` directory + of the :term:`Source Directory`. + + Within that ``poky.conf`` file, the ``DISTRO_NAME`` variable is set + as follows: + :: + + DISTRO_NAME = "Poky (Yocto Project Reference Distro)" + + Distribution configuration files are located in a ``conf/distro`` + directory within the :term:`Metadata` that contains the + distribution configuration. + + .. note:: + + If the + DISTRO_NAME + variable is blank, a set of default configurations are used, which + are specified within + meta/conf/distro/defaultsetup.conf + also in the Source Directory. + + DISTRO_VERSION + The version of the distribution. + + DISTROOVERRIDES + A colon-separated list of overrides specific to the current + distribution. By default, this list includes the value of + :term:`DISTRO`. + + You can extend ``DISTROOVERRIDES`` to add extra overrides that should + apply to the distribution. + + The underlying mechanism behind ``DISTROOVERRIDES`` is simply that it + is included in the default value of + :term:`OVERRIDES`. + + DL_DIR + The central download directory used by the build process to store + downloads. By default, ``DL_DIR`` gets files suitable for mirroring + for everything except Git repositories. If you want tarballs of Git + repositories, use the + :term:`BB_GENERATE_MIRROR_TARBALLS` + variable. + + You can set this directory by defining the ``DL_DIR`` variable in the + ``conf/local.conf`` file. This directory is self-maintaining and you + should not have to touch it. By default, the directory is + ``downloads`` in the :term:`Build Directory`. + :: + + #DL_DIR ?= "${TOPDIR}/downloads" + + To specify a different download directory, + simply remove the comment from the line and provide your directory. + + During a first build, the system downloads many different source code + tarballs from various upstream projects. Downloading can take a + while, particularly if your network connection is slow. Tarballs are + all stored in the directory defined by ``DL_DIR`` and the build + system looks there first to find source tarballs. + + .. note:: + + When wiping and rebuilding, you can preserve this directory to + speed up this part of subsequent builds. + + You can safely share this directory between multiple builds on the + same development machine. For additional information on how the build + process gets source files when working behind a firewall or proxy + server, see this specific question in the + "`FAQ <#how-does-the-yocto-project-obtain-source-code-and-will-it-work-behind-my-firewall-or-proxy-server>`__" + chapter. You can also refer to the + ":yocto_wiki:`Working Behind a Network Proxy </wiki/Working_Behind_a_Network_Proxy>`" + Wiki page. + + DOC_COMPRESS + When inheriting the :ref:`compress_doc <ref-classes-compress_doc>` + class, this variable sets the compression policy used when the + OpenEmbedded build system compresses man pages and info pages. By + default, the compression method used is gz (gzip). Other policies + available are xz and bz2. + + For information on policies and on how to use this variable, see the + comments in the ``meta/classes/compress_doc.bbclass`` file. + + EFI_PROVIDER + When building bootable images (i.e. where ``hddimg``, ``iso``, or + ``wic.vmdk`` is in :term:`IMAGE_FSTYPES`), the + ``EFI_PROVIDER`` variable specifies the EFI bootloader to use. The + default is "grub-efi", but "systemd-boot" can be used instead. + + See the :ref:`systemd-boot <ref-classes-systemd-boot>` and + :ref:`image-live <ref-classes-image-live>` classes for more + information. + + ENABLE_BINARY_LOCALE_GENERATION + Variable that controls which locales for ``glibc`` are generated + during the build (useful if the target device has 64Mbytes of RAM or + less). + + ERR_REPORT_DIR + When used with the :ref:`report-error <ref-classes-report-error>` + class, specifies the path used for storing the debug files created by + the :ref:`error reporting + tool <dev-manual/dev-manual-common-tasks:using the error reporting tool>`, which + allows you to submit build errors you encounter to a central + database. By default, the value of this variable is + ``${``\ :term:`LOG_DIR`\ ``}/error-report``. + + You can set ``ERR_REPORT_DIR`` to the path you want the error + reporting tool to store the debug files as follows in your + ``local.conf`` file: + :: + + ERR_REPORT_DIR = "path" + + ERROR_QA + Specifies the quality assurance checks whose failures are reported as + errors by the OpenEmbedded build system. You set this variable in + your distribution configuration file. For a list of the checks you + can control with this variable, see the + ":ref:`insane.bbclass <ref-classes-insane>`" section. + + EXCLUDE_FROM_SHLIBS + Triggers the OpenEmbedded build system's shared libraries resolver to + exclude an entire package when scanning for shared libraries. + + .. note:: + + The shared libraries resolver's functionality results in part from + the internal function + package_do_shlibs + , which is part of the + do_package + task. You should be aware that the shared libraries resolver might + implicitly define some dependencies between packages. + + The ``EXCLUDE_FROM_SHLIBS`` variable is similar to the + :term:`PRIVATE_LIBS` variable, which excludes a + package's particular libraries only and not the whole package. + + Use the ``EXCLUDE_FROM_SHLIBS`` variable by setting it to "1" for a + particular package: + :: + + EXCLUDE_FROM_SHLIBS = "1" + + EXCLUDE_FROM_WORLD + Directs BitBake to exclude a recipe from world builds (i.e. + ``bitbake world``). During world builds, BitBake locates, parses and + builds all recipes found in every layer exposed in the + ``bblayers.conf`` configuration file. + + To exclude a recipe from a world build using this variable, set the + variable to "1" in the recipe. + + .. note:: + + Recipes added to + EXCLUDE_FROM_WORLD + may still be built during a world build in order to satisfy + dependencies of other recipes. Adding a recipe to + EXCLUDE_FROM_WORLD + only ensures that the recipe is not explicitly added to the list + of build targets in a world build. + + EXTENDPE + Used with file and pathnames to create a prefix for a recipe's + version based on the recipe's :term:`PE` value. If ``PE`` + is set and greater than zero for a recipe, ``EXTENDPE`` becomes that + value (e.g if ``PE`` is equal to "1" then ``EXTENDPE`` becomes "1"). + If a recipe's ``PE`` is not set (the default) or is equal to zero, + ``EXTENDPE`` becomes "". + + See the :term:`STAMP` variable for an example. + + EXTENDPKGV + The full package version specification as it appears on the final + packages produced by a recipe. The variable's value is normally used + to fix a runtime dependency to the exact same version of another + package in the same recipe: + :: + + RDEPENDS_${PN}-additional-module = "${PN} (= ${EXTENDPKGV})" + + The dependency relationships are intended to force the package + manager to upgrade these types of packages in lock-step. + + EXTERNAL_KERNEL_TOOLS + When set, the ``EXTERNAL_KERNEL_TOOLS`` variable indicates that these + tools are not in the source tree. + + When kernel tools are available in the tree, they are preferred over + any externally installed tools. Setting the ``EXTERNAL_KERNEL_TOOLS`` + variable tells the OpenEmbedded build system to prefer the installed + external tools. See the + :ref:`kernel-yocto <ref-classes-kernel-yocto>` class in + ``meta/classes`` to see how the variable is used. + + EXTERNALSRC + When inheriting the :ref:`externalsrc <ref-classes-externalsrc>` + class, this variable points to the source tree, which is outside of + the OpenEmbedded build system. When set, this variable sets the + :term:`S` variable, which is what the OpenEmbedded build + system uses to locate unpacked recipe source code. + + For more information on ``externalsrc.bbclass``, see the + ":ref:`externalsrc.bbclass <ref-classes-externalsrc>`" section. You + can also find information on how to use this variable in the + ":ref:`dev-manual/dev-manual-common-tasks:building software from an external source`" + section in the Yocto Project Development Tasks Manual. + + EXTERNALSRC_BUILD + When inheriting the :ref:`externalsrc <ref-classes-externalsrc>` + class, this variable points to the directory in which the recipe's + source code is built, which is outside of the OpenEmbedded build + system. When set, this variable sets the :term:`B` variable, + which is what the OpenEmbedded build system uses to locate the Build + Directory. + + For more information on ``externalsrc.bbclass``, see the + ":ref:`externalsrc.bbclass <ref-classes-externalsrc>`" section. You + can also find information on how to use this variable in the + ":ref:`dev-manual/dev-manual-common-tasks:building software from an external source`" + section in the Yocto Project Development Tasks Manual. + + EXTRA_AUTORECONF + For recipes inheriting the :ref:`autotools <ref-classes-autotools>` + class, you can use ``EXTRA_AUTORECONF`` to specify extra options to + pass to the ``autoreconf`` command that is executed during the + :ref:`ref-tasks-configure` task. + + The default value is "--exclude=autopoint". + + EXTRA_IMAGE_FEATURES + A list of additional features to include in an image. When listing + more than one feature, separate them with a space. + + Typically, you configure this variable in your ``local.conf`` file, + which is found in the :term:`Build Directory`. + Although you can use this variable from within a recipe, best + practices dictate that you do not. + + .. note:: + + To enable primary features from within the image recipe, use the + IMAGE_FEATURES + variable. + + Here are some examples of features you can add: + + - "dbg-pkgs" - Adds -dbg packages for all installed packages including + symbol information for debugging and profiling. + + - "debug-tweaks" - Makes an image suitable for debugging. For example, allows root logins without passwords and + enables post-installation logging. See the 'allow-empty-password' and + 'post-install-logging' features in the "`Image + Features <#ref-features-image>`__" section for more information. + - "dev-pkgs" - Adds -dev packages for all installed packages. This is + useful if you want to develop against the libraries in the image. + - "read-only-rootfs" - Creates an image whose root filesystem is + read-only. See the + ":ref:`dev-manual/dev-manual-common-tasks:creating a read-only root filesystem`" + section in the Yocto Project Development Tasks Manual for more + information + - "tools-debug" - Adds debugging tools such as gdb and strace. + - "tools-sdk" - Adds development tools such as gcc, make, + pkgconfig and so forth. + - "tools-testapps" - Adds useful testing tools + such as ts_print, aplay, arecord and so forth. + + For a complete list of image features that ships with the Yocto + Project, see the "`Image Features <#ref-features-image>`__" section. + + For an example that shows how to customize your image by using this + variable, see the ":ref:`usingpoky-extend-customimage-imagefeatures`" + section in the Yocto Project Development Tasks Manual. + + EXTRA_IMAGECMD + Specifies additional options for the image creation command that has + been specified in :term:`IMAGE_CMD`. When setting + this variable, use an override for the associated image type. Here is + an example: + :: + + EXTRA_IMAGECMD_ext3 ?= "-i 4096" + + EXTRA_IMAGEDEPENDS + A list of recipes to build that do not provide packages for + installing into the root filesystem. + + Sometimes a recipe is required to build the final image but is not + needed in the root filesystem. You can use the ``EXTRA_IMAGEDEPENDS`` + variable to list these recipes and thus specify the dependencies. A + typical example is a required bootloader in a machine configuration. + + .. note:: + + To add packages to the root filesystem, see the various + \*RDEPENDS and \*RRECOMMENDS + variables. + + EXTRANATIVEPATH + A list of subdirectories of + ``${``\ :term:`STAGING_BINDIR_NATIVE`\ ``}`` + added to the beginning of the environment variable ``PATH``. As an + example, the following prepends + "${STAGING_BINDIR_NATIVE}/foo:${STAGING_BINDIR_NATIVE}/bar:" to + ``PATH``: + :: + + EXTRANATIVEPATH = "foo bar" + + EXTRA_OECMAKE + Additional `CMake <https://cmake.org/overview/>`__ options. See the + :ref:`cmake <ref-classes-cmake>` class for additional information. + + EXTRA_OECONF + Additional ``configure`` script options. See + :term:`PACKAGECONFIG_CONFARGS` for + additional information on passing configure script options. + + EXTRA_OEMAKE + Additional GNU ``make`` options. + + Because the ``EXTRA_OEMAKE`` defaults to "", you need to set the + variable to specify any required GNU options. + + :term:`PARALLEL_MAKE` and + :term:`PARALLEL_MAKEINST` also make use of + ``EXTRA_OEMAKE`` to pass the required flags. + + EXTRA_OESCONS + When inheriting the :ref:`scons <ref-classes-scons>` class, this + variable specifies additional configuration options you want to pass + to the ``scons`` command line. + + EXTRA_USERS_PARAMS + When inheriting the :ref:`extrausers <ref-classes-extrausers>` + class, this variable provides image level user and group operations. + This is a more global method of providing user and group + configuration as compared to using the + :ref:`useradd <ref-classes-useradd>` class, which ties user and + group configurations to a specific recipe. + + The set list of commands you can configure using the + ``EXTRA_USERS_PARAMS`` is shown in the ``extrausers`` class. These + commands map to the normal Unix commands of the same names: + :: + + # EXTRA_USERS_PARAMS = "\ + # useradd -p '' tester; \ + # groupadd developers; \ + # userdel nobody; \ + # groupdel -g video; \ + # groupmod -g 1020 developers; \ + # usermod -s /bin/sh tester; \ + # " + + FEATURE_PACKAGES + Defines one or more packages to include in an image when a specific + item is included in :term:`IMAGE_FEATURES`. + When setting the value, ``FEATURE_PACKAGES`` should have the name of + the feature item as an override. Here is an example: + :: + + FEATURE_PACKAGES_widget = "package1 package2" + + In this example, if "widget" were added to ``IMAGE_FEATURES``, + package1 and package2 would be included in the image. + + .. note:: + + Packages installed by features defined through + FEATURE_PACKAGES + are often package groups. While similarly named, you should not + confuse the + FEATURE_PACKAGES + variable with package groups, which are discussed elsewhere in the + documentation. + + FEED_DEPLOYDIR_BASE_URI + Points to the base URL of the server and location within the + document-root that provides the metadata and packages required by + OPKG to support runtime package management of IPK packages. You set + this variable in your ``local.conf`` file. + + Consider the following example: + :: + + FEED_DEPLOYDIR_BASE_URI = "http://192.168.7.1/BOARD-dir" + + This example assumes you are serving + your packages over HTTP and your databases are located in a directory + named ``BOARD-dir``, which is underneath your HTTP server's + document-root. In this case, the OpenEmbedded build system generates + a set of configuration files for you in your target that work with + the feed. + + FILES + The list of files and directories that are placed in a package. The + :term:`PACKAGES` variable lists the packages + generated by a recipe. + + To use the ``FILES`` variable, provide a package name override that + identifies the resulting package. Then, provide a space-separated + list of files or paths that identify the files you want included as + part of the resulting package. Here is an example: + :: + + FILES_${PN} += "${bindir}/mydir1 ${bindir}/mydir2/myfile" + + .. note:: + + - When specifying files or paths, you can pattern match using + Python's + `glob <https://docs.python.org/3/library/glob.html>`_ + syntax. For details on the syntax, see the documentation by + following the previous link. + + - When specifying paths as part of the ``FILES`` variable, it is + good practice to use appropriate path variables. For example, + use ``${sysconfdir}`` rather than ``/etc``, or ``${bindir}`` + rather than ``/usr/bin``. You can find a list of these + variables at the top of the ``meta/conf/bitbake.conf`` file in + the :term:`Source Directory`. You will also + find the default values of the various ``FILES_*`` variables in + this file. + + If some of the files you provide with the ``FILES`` variable are + editable and you know they should not be overwritten during the + package update process by the Package Management System (PMS), you + can identify these files so that the PMS will not overwrite them. See + the :term:`CONFFILES` variable for information on + how to identify these files to the PMS. + + FILES_SOLIBSDEV + Defines the file specification to match + :term:`SOLIBSDEV`. In other words, + ``FILES_SOLIBSDEV`` defines the full path name of the development + symbolic link (symlink) for shared libraries on the target platform. + + The following statement from the ``bitbake.conf`` shows how it is + set: + :: + + FILES_SOLIBSDEV ?= "${base_libdir}/lib*${SOLIBSDEV} ${libdir}/lib*${SOLIBSDEV}" + + FILESEXTRAPATHS + Extends the search path the OpenEmbedded build system uses when + looking for files and patches as it processes recipes and append + files. The default directories BitBake uses when it processes recipes + are initially defined by the :term:`FILESPATH` + variable. You can extend ``FILESPATH`` variable by using + ``FILESEXTRAPATHS``. + + Best practices dictate that you accomplish this by using + ``FILESEXTRAPATHS`` from within a ``.bbappend`` file and that you + prepend paths as follows: + :: + + FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" + + In the above example, the build system first + looks for files in a directory that has the same name as the + corresponding append file. + + .. note:: + + When extending ``FILESEXTRAPATHS``, be sure to use the immediate + expansion (``:=``) operator. Immediate expansion makes sure that + BitBake evaluates :term:`THISDIR` at the time the + directive is encountered rather than at some later time when + expansion might result in a directory that does not contain the + files you need. + + Also, include the trailing separating colon character if you are + prepending. The trailing colon character is necessary because you + are directing BitBake to extend the path by prepending directories + to the search path. + + Here is another common use: + :: + + FILESEXTRAPATHS_prepend := "${THISDIR}/files:" + + In this example, the build system extends the + ``FILESPATH`` variable to include a directory named ``files`` that is + in the same directory as the corresponding append file. + + This next example specifically adds three paths: + :: + + FILESEXTRAPATHS_prepend := "path_1:path_2:path_3:" + + A final example shows how you can extend the search path and include + a :term:`MACHINE`-specific override, which is useful + in a BSP layer: + :: + + FILESEXTRAPATHS_prepend_intel-x86-common := "${THISDIR}/${PN}:" + + The previous statement appears in the + ``linux-yocto-dev.bbappend`` file, which is found in the + :ref:`overview-manual/overview-manual-development-environment:yocto project source repositories` in + ``meta-intel/common/recipes-kernel/linux``. Here, the machine + override is a special :term:`PACKAGE_ARCH` + definition for multiple ``meta-intel`` machines. + + .. note:: + + For a layer that supports a single BSP, the override could just be + the value of + MACHINE + . + + By prepending paths in ``.bbappend`` files, you allow multiple append + files that reside in different layers but are used for the same + recipe to correctly extend the path. + + FILESOVERRIDES + A subset of :term:`OVERRIDES` used by the + OpenEmbedded build system for creating + :term:`FILESPATH`. The ``FILESOVERRIDES`` variable + uses overrides to automatically extend the + :term:`FILESPATH` variable. For an example of how + that works, see the :term:`FILESPATH` variable + description. Additionally, you find more information on how overrides + are handled in the + ":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata:conditional syntax (overrides)`" + section of the BitBake User Manual. + + By default, the ``FILESOVERRIDES`` variable is defined as: + :: + + FILESOVERRIDES = "${TRANSLATED_TARGET_ARCH}:${MACHINEOVERRIDES}:${DISTROOVERRIDES}" + + .. note:: + + Do not hand-edit the + FILESOVERRIDES + variable. The values match up with expected overrides and are used + in an expected manner by the build system. + + FILESPATH + The default set of directories the OpenEmbedded build system uses + when searching for patches and files. + + During the build process, BitBake searches each directory in + ``FILESPATH`` in the specified order when looking for files and + patches specified by each ``file://`` URI in a recipe's + :term:`SRC_URI` statements. + + The default value for the ``FILESPATH`` variable is defined in the + ``base.bbclass`` class found in ``meta/classes`` in the + :term:`Source Directory`: + :: + + FILESPATH = "${@base_set_filespath(["${FILE_DIRNAME}/${BP}", \ + "${FILE_DIRNAME}/${BPN}", "${FILE_DIRNAME}/files"], d)}" + + The + ``FILESPATH`` variable is automatically extended using the overrides + from the :term:`FILESOVERRIDES` variable. + + .. note:: + + - Do not hand-edit the ``FILESPATH`` variable. If you want the + build system to look in directories other than the defaults, + extend the ``FILESPATH`` variable by using the + :term:`FILESEXTRAPATHS` variable. + + - Be aware that the default ``FILESPATH`` directories do not map + to directories in custom layers where append files + (``.bbappend``) are used. If you want the build system to find + patches or files that reside with your append files, you need + to extend the ``FILESPATH`` variable by using the + ``FILESEXTRAPATHS`` variable. + + You can take advantage of this searching behavior in useful ways. For + example, consider a case where the following directory structure + exists for general and machine-specific configurations: + :: + + files/defconfig + files/MACHINEA/defconfig + files/MACHINEB/defconfig + + Also in the example, the ``SRC_URI`` statement contains + "file://defconfig". Given this scenario, you can set + :term:`MACHINE` to "MACHINEA" and cause the build + system to use files from ``files/MACHINEA``. Set ``MACHINE`` to + "MACHINEB" and the build system uses files from ``files/MACHINEB``. + Finally, for any machine other than "MACHINEA" and "MACHINEB", the + build system uses files from ``files/defconfig``. + + You can find out more about the patching process in the + ":ref:`patching-dev-environment`" section + in the Yocto Project Overview and Concepts Manual and the + ":ref:`new-recipe-patching-code`" section in + the Yocto Project Development Tasks Manual. See the + :ref:`ref-tasks-patch` task as well. + + FILESYSTEM_PERMS_TABLES + Allows you to define your own file permissions settings table as part + of your configuration for the packaging process. For example, suppose + you need a consistent set of custom permissions for a set of groups + and users across an entire work project. It is best to do this in the + packages themselves but this is not always possible. + + By default, the OpenEmbedded build system uses the ``fs-perms.txt``, + which is located in the ``meta/files`` folder in the :term:`Source Directory`. + If you create your own file + permissions setting table, you should place it in your layer or the + distro's layer. + + You define the ``FILESYSTEM_PERMS_TABLES`` variable in the + ``conf/local.conf`` file, which is found in the :term:`Build Directory`, + to point to your custom + ``fs-perms.txt``. You can specify more than a single file permissions + setting table. The paths you specify to these files must be defined + within the :term:`BBPATH` variable. + + For guidance on how to create your own file permissions settings + table file, examine the existing ``fs-perms.txt``. + + FIT_GENERATE_KEYS + Decides whether to generate the keys for signing fitImage if they + don't already exist. The keys are created in ``UBOOT_SIGN_KEYDIR``. + The default value is 0. + + FIT_HASH_ALG + Specifies the hash algorithm used in creating the FIT Image. For e.g. sha256. + + FIT_KEY_GENRSA_ARGS + Arguments to openssl genrsa for generating RSA private key for signing + fitImage. The default value is "-F4". i.e. the public exponent 65537 to + use. + + FIT_KEY_REQ_ARGS + Arguments to openssl req for generating certificate for signing fitImage. + The default value is "-batch -new". batch for non interactive mode + and new for generating new keys. + + FIT_KEY_SIGN_PKCS + Format for public key ceritifcate used in signing fitImage. + The default value is "x509". + + FIT_SIGN_ALG + Specifies the signature algorithm used in creating the FIT Image. + For e.g. rsa2048. + + FIT_SIGN_NUMBITS + Size of private key in number of bits used in fitImage. The default + value is "2048". + + FONT_EXTRA_RDEPENDS + When inheriting the :ref:`fontcache <ref-classes-fontcache>` class, + this variable specifies the runtime dependencies for font packages. + By default, the ``FONT_EXTRA_RDEPENDS`` is set to "fontconfig-utils". + + FONT_PACKAGES + When inheriting the :ref:`fontcache <ref-classes-fontcache>` class, + this variable identifies packages containing font files that need to + be cached by Fontconfig. By default, the ``fontcache`` class assumes + that fonts are in the recipe's main package (i.e. + ``${``\ :term:`PN`\ ``}``). Use this variable if fonts you + need are in a package other than that main package. + + FORCE_RO_REMOVE + Forces the removal of the packages listed in ``ROOTFS_RO_UNNEEDED`` + during the generation of the root filesystem. + + Set the variable to "1" to force the removal of these packages. + + FULL_OPTIMIZATION + The options to pass in ``TARGET_CFLAGS`` and ``CFLAGS`` when + compiling an optimized system. This variable defaults to "-O2 -pipe + ${DEBUG_FLAGS}". + + GCCPIE + Enables Position Independent Executables (PIE) within the GNU C + Compiler (GCC). Enabling PIE in the GCC makes Return Oriented + Programming (ROP) attacks much more difficult to execute. + + By default the ``security_flags.inc`` file enables PIE by setting the + variable as follows: + :: + + GCCPIE ?= "--enable-default-pie" + + GCCVERSION + Specifies the default version of the GNU C Compiler (GCC) used for + compilation. By default, ``GCCVERSION`` is set to "8.x" in the + ``meta/conf/distro/include/tcmode-default.inc`` include file: + :: + + GCCVERSION ?= "8.%" + + You can override this value by setting it in a + configuration file such as the ``local.conf``. + + GDB + The minimal command and arguments to run the GNU Debugger. + + GITDIR + The directory in which a local copy of a Git repository is stored + when it is cloned. + + GLIBC_GENERATE_LOCALES + Specifies the list of GLIBC locales to generate should you not wish + to generate all LIBC locals, which can be time consuming. + + .. note:: + + If you specifically remove the locale + en_US.UTF-8 + , you must set + IMAGE_LINGUAS + appropriately. + + You can set ``GLIBC_GENERATE_LOCALES`` in your ``local.conf`` file. + By default, all locales are generated. + :: + + GLIBC_GENERATE_LOCALES = "en_GB.UTF-8 en_US.UTF-8" + + GROUPADD_PARAM + When inheriting the :ref:`useradd <ref-classes-useradd>` class, + this variable specifies for a package what parameters should be + passed to the ``groupadd`` command if you wish to add a group to the + system when the package is installed. + + Here is an example from the ``dbus`` recipe: + :: + + GROUPADD_PARAM_${PN} = "-r netdev" + + For information on the standard Linux shell command + ``groupadd``, see http://linux.die.net/man/8/groupadd. + + GROUPMEMS_PARAM + When inheriting the :ref:`useradd <ref-classes-useradd>` class, + this variable specifies for a package what parameters should be + passed to the ``groupmems`` command if you wish to modify the members + of a group when the package is installed. + + For information on the standard Linux shell command ``groupmems``, + see http://linux.die.net/man/8/groupmems. + + GRUB_GFXSERIAL + Configures the GNU GRand Unified Bootloader (GRUB) to have graphics + and serial in the boot menu. Set this variable to "1" in your + ``local.conf`` or distribution configuration file to enable graphics + and serial in the menu. + + See the :ref:`grub-efi <ref-classes-grub-efi>` class for more + information on how this variable is used. + + GRUB_OPTS + Additional options to add to the GNU GRand Unified Bootloader (GRUB) + configuration. Use a semi-colon character (``;``) to separate + multiple options. + + The ``GRUB_OPTS`` variable is optional. See the + :ref:`grub-efi <ref-classes-grub-efi>` class for more information + on how this variable is used. + + GRUB_TIMEOUT + Specifies the timeout before executing the default ``LABEL`` in the + GNU GRand Unified Bootloader (GRUB). + + The ``GRUB_TIMEOUT`` variable is optional. See the + :ref:`grub-efi <ref-classes-grub-efi>` class for more information + on how this variable is used. + + GTKIMMODULES_PACKAGES + When inheriting the + :ref:`gtk-immodules-cache <ref-classes-gtk-immodules-cache>` class, + this variable specifies the packages that contain the GTK+ input + method modules being installed when the modules are in packages other + than the main package. + + HOMEPAGE + Website where more information about the software the recipe is + building can be found. + + HOST_ARCH + The name of the target architecture, which is normally the same as + :term:`TARGET_ARCH`. The OpenEmbedded build system + supports many architectures. Here is an example list of architectures + supported. This list is by no means complete as the architecture is + configurable: + + - arm + - i586 + - x86_64 + - powerpc + - powerpc64 + - mips + - mipsel + + HOST_CC_ARCH + Specifies architecture-specific compiler flags that are passed to the + C compiler. + + Default initialization for ``HOST_CC_ARCH`` varies depending on what + is being built: + + - :term:`TARGET_CC_ARCH` when building for the + target + + - ``BUILD_CC_ARCH`` when building for the build host (i.e. + ``-native``) + + - ``BUILDSDK_CC_ARCH`` when building for an SDK (i.e. + ``nativesdk-``) + + HOST_OS + Specifies the name of the target operating system, which is normally + the same as the :term:`TARGET_OS`. The variable can + be set to "linux" for ``glibc``-based systems and to "linux-musl" for + ``musl``. For ARM/EABI targets, there are also "linux-gnueabi" and + "linux-musleabi" values possible. + + HOST_PREFIX + Specifies the prefix for the cross-compile toolchain. ``HOST_PREFIX`` + is normally the same as :term:`TARGET_PREFIX`. + + HOST_SYS + Specifies the system, including the architecture and the operating + system, for which the build is occurring in the context of the + current recipe. + + The OpenEmbedded build system automatically sets this variable based + on :term:`HOST_ARCH`, + :term:`HOST_VENDOR`, and + :term:`HOST_OS` variables. + + .. note:: + + You do not need to set the variable yourself. + + Consider these two examples: + + - Given a native recipe on a 32-bit x86 machine running Linux, the + value is "i686-linux". + + - Given a recipe being built for a little-endian MIPS target running + Linux, the value might be "mipsel-linux". + + HOSTTOOLS + A space-separated list (filter) of tools on the build host that + should be allowed to be called from within build tasks. Using this + filter helps reduce the possibility of host contamination. If a tool + specified in the value of ``HOSTTOOLS`` is not found on the build + host, the OpenEmbedded build system produces an error and the build + is not started. + + For additional information, see + :term:`HOSTTOOLS_NONFATAL`. + + HOSTTOOLS_NONFATAL + A space-separated list (filter) of tools on the build host that + should be allowed to be called from within build tasks. Using this + filter helps reduce the possibility of host contamination. Unlike + :term:`HOSTTOOLS`, the OpenEmbedded build system + does not produce an error if a tool specified in the value of + ``HOSTTOOLS_NONFATAL`` is not found on the build host. Thus, you can + use ``HOSTTOOLS_NONFATAL`` to filter optional host tools. + + HOST_VENDOR + Specifies the name of the vendor. ``HOST_VENDOR`` is normally the + same as :term:`TARGET_VENDOR`. + + ICECC_DISABLED + Disables or enables the ``icecc`` (Icecream) function. For more + information on this function and best practices for using this + variable, see the ":ref:`icecc.bbclass <ref-classes-icecc>`" + section. + + Setting this variable to "1" in your ``local.conf`` disables the + function: + :: + + ICECC_DISABLED ??= "1" + + To enable the function, set the variable as follows: + :: + + ICECC_DISABLED = "" + + ICECC_ENV_EXEC + Points to the ``icecc-create-env`` script that you provide. This + variable is used by the :ref:`icecc <ref-classes-icecc>` class. You + set this variable in your ``local.conf`` file. + + If you do not point to a script that you provide, the OpenEmbedded + build system uses the default script provided by the + ``icecc-create-env.bb`` recipe, which is a modified version and not + the one that comes with ``icecc``. + + ICECC_PARALLEL_MAKE + Extra options passed to the ``make`` command during the + :ref:`ref-tasks-compile` task that specify parallel + compilation. This variable usually takes the form of "-j x", where x + represents the maximum number of parallel threads ``make`` can run. + + .. note:: + + The options passed affect builds on all enabled machines on the + network, which are machines running the + iceccd + daemon. + + If your enabled machines support multiple cores, coming up with the + maximum number of parallel threads that gives you the best + performance could take some experimentation since machine speed, + network lag, available memory, and existing machine loads can all + affect build time. Consequently, unlike the + :term:`PARALLEL_MAKE` variable, there is no + rule-of-thumb for setting ``ICECC_PARALLEL_MAKE`` to achieve optimal + performance. + + If you do not set ``ICECC_PARALLEL_MAKE``, the build system does not + use it (i.e. the system does not detect and assign the number of + cores as is done with ``PARALLEL_MAKE``). + + ICECC_PATH + The location of the ``icecc`` binary. You can set this variable in + your ``local.conf`` file. If your ``local.conf`` file does not define + this variable, the :ref:`icecc <ref-classes-icecc>` class attempts + to define it by locating ``icecc`` using ``which``. + + ICECC_USER_CLASS_BL + Identifies user classes that you do not want the Icecream distributed + compile support to consider. This variable is used by the + :ref:`icecc <ref-classes-icecc>` class. You set this variable in + your ``local.conf`` file. + + When you list classes using this variable, you are "blacklisting" + them from distributed compilation across remote hosts. Any classes + you list will be distributed and compiled locally. + + ICECC_USER_PACKAGE_BL + Identifies user recipes that you do not want the Icecream distributed + compile support to consider. This variable is used by the + :ref:`icecc <ref-classes-icecc>` class. You set this variable in + your ``local.conf`` file. + + When you list packages using this variable, you are "blacklisting" + them from distributed compilation across remote hosts. Any packages + you list will be distributed and compiled locally. + + ICECC_USER_PACKAGE_WL + Identifies user recipes that use an empty + :term:`PARALLEL_MAKE` variable that you want to + force remote distributed compilation on using the Icecream + distributed compile support. This variable is used by the + :ref:`icecc <ref-classes-icecc>` class. You set this variable in + your ``local.conf`` file. + + IMAGE_BASENAME + The base name of image output files. This variable defaults to the + recipe name (``${``\ :term:`PN`\ ``}``). + + IMAGE_EFI_BOOT_FILES + A space-separated list of files installed into the boot partition + when preparing an image using the Wic tool with the + ``bootimg-efi`` source plugin. By default, + the files are + installed under the same name as the source files. To change the + installed name, separate it from the original name with a semi-colon + (;). Source files need to be located in + :term:`DEPLOY_DIR_IMAGE`. Here are two + examples: + :: + + IMAGE_EFI_BOOT_FILES = "${KERNEL_IMAGETYPE};bz2" + IMAGE_EFI_BOOT_FILES = "${KERNEL_IMAGETYPE} microcode.cpio" + + Alternatively, source files can be picked up using a glob pattern. In + this case, the destination file must have the same name as the base + name of the source file path. To install files into a directory + within the target location, pass its name after a semi-colon (;). + Here are two examples: + :: + + IMAGE_EFI_BOOT_FILES = "boot/loader/*" + IMAGE_EFI_BOOT_FILES = "boot/loader/*;boot/" + + The first example + installs all files from ``${DEPLOY_DIR_IMAGE}/boot/loader/`` + into the root of the target partition. The second example installs + the same files into a ``boot`` directory within the target partition. + + You can find information on how to use the Wic tool in the + ":ref:`dev-manual/dev-manual-common-tasks:creating partitioned images using wic`" + section of the Yocto Project Development Tasks Manual. Reference + material for Wic is located in the + ":doc:`../ref-manual/ref-kickstart`" chapter. + + IMAGE_BOOT_FILES + A space-separated list of files installed into the boot partition + when preparing an image using the Wic tool with the + ``bootimg-partition`` source plugin. By default, + the files are + installed under the same name as the source files. To change the + installed name, separate it from the original name with a semi-colon + (;). Source files need to be located in + :term:`DEPLOY_DIR_IMAGE`. Here are two + examples: + :: + + IMAGE_BOOT_FILES = "u-boot.img uImage;kernel" + IMAGE_BOOT_FILES = "u-boot.${UBOOT_SUFFIX} ${KERNEL_IMAGETYPE}" + + Alternatively, source files can be picked up using a glob pattern. In + this case, the destination file must have the same name as the base + name of the source file path. To install files into a directory + within the target location, pass its name after a semi-colon (;). + Here are two examples: + :: + + IMAGE_BOOT_FILES = "bcm2835-bootfiles/*" + IMAGE_BOOT_FILES = "bcm2835-bootfiles/*;boot/" + + The first example + installs all files from ``${DEPLOY_DIR_IMAGE}/bcm2835-bootfiles`` + into the root of the target partition. The second example installs + the same files into a ``boot`` directory within the target partition. + + You can find information on how to use the Wic tool in the + ":ref:`dev-manual/dev-manual-common-tasks:creating partitioned images using wic`" + section of the Yocto Project Development Tasks Manual. Reference + material for Wic is located in the + ":doc:`../ref-manual/ref-kickstart`" chapter. + + IMAGE_CLASSES + A list of classes that all images should inherit. You typically use + this variable to specify the list of classes that register the + different types of images the OpenEmbedded build system creates. + + The default value for ``IMAGE_CLASSES`` is ``image_types``. You can + set this variable in your ``local.conf`` or in a distribution + configuration file. + + For more information, see ``meta/classes/image_types.bbclass`` in the + :term:`Source Directory`. + + IMAGE_CMD + Specifies the command to create the image file for a specific image + type, which corresponds to the value set set in + :term:`IMAGE_FSTYPES`, (e.g. ``ext3``, + ``btrfs``, and so forth). When setting this variable, you should use + an override for the associated type. Here is an example: + :: + + IMAGE_CMD_jffs2 = "mkfs.jffs2 --root=${IMAGE_ROOTFS} \ + --faketime --output=${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.jffs2 \ + ${EXTRA_IMAGECMD}" + + You typically do not need to set this variable unless you are adding + support for a new image type. For more examples on how to set this + variable, see the :ref:`image_types <ref-classes-image_types>` + class file, which is ``meta/classes/image_types.bbclass``. + + IMAGE_DEVICE_TABLES + Specifies one or more files that contain custom device tables that + are passed to the ``makedevs`` command as part of creating an image. + These files list basic device nodes that should be created under + ``/dev`` within the image. If ``IMAGE_DEVICE_TABLES`` is not set, + ``files/device_table-minimal.txt`` is used, which is located by + :term:`BBPATH`. For details on how you should write + device table files, see ``meta/files/device_table-minimal.txt`` as an + example. + + IMAGE_FEATURES + The primary list of features to include in an image. Typically, you + configure this variable in an image recipe. Although you can use this + variable from your ``local.conf`` file, which is found in the + :term:`Build Directory`, best practices dictate that you do + not. + + .. note:: + + To enable extra features from outside the image recipe, use the + EXTRA_IMAGE_FEATURES + variable. + + For a list of image features that ships with the Yocto Project, see + the "`Image Features <#ref-features-image>`__" section. + + For an example that shows how to customize your image by using this + variable, see the ":ref:`usingpoky-extend-customimage-imagefeatures`" + section in the Yocto Project Development Tasks Manual. + + IMAGE_FSTYPES + Specifies the formats the OpenEmbedded build system uses during the + build when creating the root filesystem. For example, setting + ``IMAGE_FSTYPES`` as follows causes the build system to create root + filesystems using two formats: ``.ext3`` and ``.tar.bz2``: + :: + + IMAGE_FSTYPES = "ext3 tar.bz2" + + For the complete list of supported image formats from which you can + choose, see :term:`IMAGE_TYPES`. + + .. note:: + + - If an image recipe uses the "inherit image" line and you are + setting ``IMAGE_FSTYPES`` inside the recipe, you must set + ``IMAGE_FSTYPES`` prior to using the "inherit image" line. + + - Due to the way the OpenEmbedded build system processes this + variable, you cannot update its contents by using ``_append`` + or ``_prepend``. You must use the ``+=`` operator to add one or + more options to the ``IMAGE_FSTYPES`` variable. + + IMAGE_INSTALL + Used by recipes to specify the packages to install into an image + through the :ref:`image <ref-classes-image>` class. Use the + ``IMAGE_INSTALL`` variable with care to avoid ordering issues. + + Image recipes set ``IMAGE_INSTALL`` to specify the packages to + install into an image through ``image.bbclass``. Additionally, + "helper" classes such as the + :ref:`core-image <ref-classes-core-image>` class exist that can + take lists used with ``IMAGE_FEATURES`` and turn them into + auto-generated entries in ``IMAGE_INSTALL`` in addition to its + default contents. + + When you use this variable, it is best to use it as follows: + :: + + IMAGE_INSTALL_append = " package-name" + + Be sure to include the space + between the quotation character and the start of the package name or + names. + + .. note:: + + - When working with a + ```core-image-minimal-initramfs`` <#images-core-image-minimal-initramfs>`__ + image, do not use the ``IMAGE_INSTALL`` variable to specify + packages for installation. Instead, use the + :term:`PACKAGE_INSTALL` variable, which + allows the initial RAM filesystem (initramfs) recipe to use a + fixed set of packages and not be affected by ``IMAGE_INSTALL``. + For information on creating an initramfs, see the + ":ref:`building-an-initramfs-image`" + section in the Yocto Project Development Tasks Manual. + + - Using ``IMAGE_INSTALL`` with the + :ref:`+= <bitbake:appending-and-prepending>` + BitBake operator within the ``/conf/local.conf`` file or from + within an image recipe is not recommended. Use of this operator + in these ways can cause ordering issues. Since + ``core-image.bbclass`` sets ``IMAGE_INSTALL`` to a default + value using the + :ref:`?= <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:setting a default value (?=)>` + operator, using a ``+=`` operation against ``IMAGE_INSTALL`` + results in unexpected behavior when used within + ``conf/local.conf``. Furthermore, the same operation from + within an image recipe may or may not succeed depending on the + specific situation. In both these cases, the behavior is + contrary to how most users expect the ``+=`` operator to work. + + IMAGE_LINGUAS + Specifies the list of locales to install into the image during the + root filesystem construction process. The OpenEmbedded build system + automatically splits locale files, which are used for localization, + into separate packages. Setting the ``IMAGE_LINGUAS`` variable + ensures that any locale packages that correspond to packages already + selected for installation into the image are also installed. Here is + an example: + :: + + IMAGE_LINGUAS = "pt-br de-de" + + In this example, the build system ensures any Brazilian Portuguese + and German locale files that correspond to packages in the image are + installed (i.e. ``*-locale-pt-br`` and ``*-locale-de-de`` as well as + ``*-locale-pt`` and ``*-locale-de``, since some software packages + only provide locale files by language and not by country-specific + language). + + See the :term:`GLIBC_GENERATE_LOCALES` + variable for information on generating GLIBC locales. + + IMAGE_MANIFEST + The manifest file for the image. This file lists all the installed + packages that make up the image. The file contains package + information on a line-per-package basis as follows: + :: + + packagename packagearch version + + The :ref:`image <ref-classes-image>` class defines the manifest + file as follows: + :: + + IMAGE_MANIFEST ="${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.manifest" + + The location is + derived using the :term:`DEPLOY_DIR_IMAGE` + and :term:`IMAGE_NAME` variables. You can find + information on how the image is created in the ":ref:`image-generation-dev-environment`" + section in the Yocto Project Overview and Concepts Manual. + + IMAGE_NAME + The name of the output image files minus the extension. This variable + is derived using the :term:`IMAGE_BASENAME`, + :term:`MACHINE`, and :term:`DATETIME` + variables: + :: + + IMAGE_NAME = "${IMAGE_BASENAME}-${MACHINE}-${DATETIME}" + + IMAGE_OVERHEAD_FACTOR + Defines a multiplier that the build system applies to the initial + image size for cases when the multiplier times the returned disk + usage value for the image is greater than the sum of + ``IMAGE_ROOTFS_SIZE`` and ``IMAGE_ROOTFS_EXTRA_SPACE``. The result of + the multiplier applied to the initial image size creates free disk + space in the image as overhead. By default, the build process uses a + multiplier of 1.3 for this variable. This default value results in + 30% free disk space added to the image when this method is used to + determine the final generated image size. You should be aware that + post install scripts and the package management system uses disk + space inside this overhead area. Consequently, the multiplier does + not produce an image with all the theoretical free disk space. See + ``IMAGE_ROOTFS_SIZE`` for information on how the build system + determines the overall image size. + + The default 30% free disk space typically gives the image enough room + to boot and allows for basic post installs while still leaving a + small amount of free disk space. If 30% free space is inadequate, you + can increase the default value. For example, the following setting + gives you 50% free space added to the image: + :: + + IMAGE_OVERHEAD_FACTOR = "1.5" + + Alternatively, you can ensure a specific amount of free disk space is + added to the image by using the ``IMAGE_ROOTFS_EXTRA_SPACE`` + variable. + + IMAGE_PKGTYPE + Defines the package type (i.e. DEB, RPM, IPK, or TAR) used by the + OpenEmbedded build system. The variable is defined appropriately by + the :ref:`package_deb <ref-classes-package_deb>`, + :ref:`package_rpm <ref-classes-package_rpm>`, + :ref:`package_ipk <ref-classes-package_ipk>`, or + :ref:`package_tar <ref-classes-package_tar>` class. + + .. note:: + + The + package_tar + class is broken and is not supported. It is recommended that you + do not use it. + + The :ref:`populate_sdk_* <ref-classes-populate-sdk-*>` and + :ref:`image <ref-classes-image>` classes use the ``IMAGE_PKGTYPE`` + for packaging up images and SDKs. + + You should not set the ``IMAGE_PKGTYPE`` manually. Rather, the + variable is set indirectly through the appropriate + :ref:`package_* <ref-classes-package>` class using the + :term:`PACKAGE_CLASSES` variable. The + OpenEmbedded build system uses the first package type (e.g. DEB, RPM, + or IPK) that appears with the variable + + .. note:: + + Files using the + .tar + format are never used as a substitute packaging format for DEB, + RPM, and IPK formatted files for your image or SDK. + + IMAGE_POSTPROCESS_COMMAND + Specifies a list of functions to call once the OpenEmbedded build + system creates the final image output files. You can specify + functions separated by semicolons: + :: + + IMAGE_POSTPROCESS_COMMAND += "function; ... " + + If you need to pass the root filesystem path to a command within the + function, you can use ``${IMAGE_ROOTFS}``, which points to the + directory that becomes the root filesystem image. See the + :term:`IMAGE_ROOTFS` variable for more + information. + + IMAGE_PREPROCESS_COMMAND + Specifies a list of functions to call before the OpenEmbedded build + system creates the final image output files. You can specify + functions separated by semicolons: + :: + + IMAGE_PREPROCESS_COMMAND += "function; ... " + + If you need to pass the root filesystem path to a command within the + function, you can use ``${IMAGE_ROOTFS}``, which points to the + directory that becomes the root filesystem image. See the + :term:`IMAGE_ROOTFS` variable for more + information. + + IMAGE_ROOTFS + The location of the root filesystem while it is under construction + (i.e. during the :ref:`ref-tasks-rootfs` task). This + variable is not configurable. Do not change it. + + IMAGE_ROOTFS_ALIGNMENT + Specifies the alignment for the output image file in Kbytes. If the + size of the image is not a multiple of this value, then the size is + rounded up to the nearest multiple of the value. The default value is + "1". See :term:`IMAGE_ROOTFS_SIZE` for + additional information. + + IMAGE_ROOTFS_EXTRA_SPACE + Defines additional free disk space created in the image in Kbytes. By + default, this variable is set to "0". This free disk space is added + to the image after the build system determines the image size as + described in ``IMAGE_ROOTFS_SIZE``. + + This variable is particularly useful when you want to ensure that a + specific amount of free disk space is available on a device after an + image is installed and running. For example, to be sure 5 Gbytes of + free disk space is available, set the variable as follows: + :: + + IMAGE_ROOTFS_EXTRA_SPACE = "5242880" + + For example, the Yocto Project Build Appliance specifically requests + 40 Gbytes of extra space with the line: + :: + + IMAGE_ROOTFS_EXTRA_SPACE = "41943040" + + IMAGE_ROOTFS_SIZE + Defines the size in Kbytes for the generated image. The OpenEmbedded + build system determines the final size for the generated image using + an algorithm that takes into account the initial disk space used for + the generated image, a requested size for the image, and requested + additional free disk space to be added to the image. Programatically, + the build system determines the final size of the generated image as + follows: + :: + + if (image-du * overhead) < rootfs-size: + internal-rootfs-size = rootfs-size + xspace + else: + internal-rootfs-size = (image-du * overhead) + xspace + where: + image-du = Returned value of the du command on the image. + overhead = IMAGE_OVERHEAD_FACTOR + rootfs-size = IMAGE_ROOTFS_SIZE + internal-rootfs-size = Initial root filesystem size before any modifications. + xspace = IMAGE_ROOTFS_EXTRA_SPACE + + See the :term:`IMAGE_OVERHEAD_FACTOR` + and :term:`IMAGE_ROOTFS_EXTRA_SPACE` + variables for related information. + + IMAGE_TYPEDEP + Specifies a dependency from one image type on another. Here is an + example from the :ref:`image-live <ref-classes-image-live>` class: + :: + + IMAGE_TYPEDEP_live = "ext3" + + In the previous example, the variable ensures that when "live" is + listed with the :term:`IMAGE_FSTYPES` variable, + the OpenEmbedded build system produces an ``ext3`` image first since + one of the components of the live image is an ``ext3`` formatted + partition containing the root filesystem. + + IMAGE_TYPES + Specifies the complete list of supported image types by default: + + - btrfs + - container + - cpio + - cpio.gz + - cpio.lz4 + - cpio.lzma + - cpio.xz + - cramfs + - ext2 + - ext2.bz2 + - ext2.gz + - ext2.lzma + - ext3 + - ext3.gz + - ext4 + - ext4.gz + - f2fs + - hddimg + - iso + - jffs2 + - jffs2.sum + - multiubi + - squashfs + - squashfs-lz4 + - squashfs-lzo + - squashfs-xz + - tar + - tar.bz2 + - tar.gz + - tar.lz4 + - tar.xz + - tar.zst + - ubi + - ubifs + - wic + - wic.bz2 + - wic.gz + - wic.lzma + + For more information about these types of images, see + ``meta/classes/image_types*.bbclass`` in the :term:`Source Directory`. + + INC_PR + Helps define the recipe revision for recipes that share a common + ``include`` file. You can think of this variable as part of the + recipe revision as set from within an include file. + + Suppose, for example, you have a set of recipes that are used across + several projects. And, within each of those recipes the revision (its + :term:`PR` value) is set accordingly. In this case, when + the revision of those recipes changes, the burden is on you to find + all those recipes and be sure that they get changed to reflect the + updated version of the recipe. In this scenario, it can get + complicated when recipes that are used in many places and provide + common functionality are upgraded to a new revision. + + A more efficient way of dealing with this situation is to set the + ``INC_PR`` variable inside the ``include`` files that the recipes + share and then expand the ``INC_PR`` variable within the recipes to + help define the recipe revision. + + The following provides an example that shows how to use the + ``INC_PR`` variable given a common ``include`` file that defines the + variable. Once the variable is defined in the ``include`` file, you + can use the variable to set the ``PR`` values in each recipe. You + will notice that when you set a recipe's ``PR`` you can provide more + granular revisioning by appending values to the ``INC_PR`` variable: + :: + + recipes-graphics/xorg-font/xorg-font-common.inc:INC_PR = "r2" + recipes-graphics/xorg-font/encodings_1.0.4.bb:PR = "${INC_PR}.1" + recipes-graphics/xorg-font/font-util_1.3.0.bb:PR = "${INC_PR}.0" + recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" + + The + first line of the example establishes the baseline revision to be + used for all recipes that use the ``include`` file. The remaining + lines in the example are from individual recipes and show how the + ``PR`` value is set. + + INCOMPATIBLE_LICENSE + Specifies a space-separated list of license names (as they would + appear in :term:`LICENSE`) that should be excluded + from the build. Recipes that provide no alternatives to listed + incompatible licenses are not built. Packages that are individually + licensed with the specified incompatible licenses will be deleted. + + .. note:: + + This functionality is only regularly tested using the following + setting: + :: + + INCOMPATIBLE_LICENSE = "GPL-3.0 LGPL-3.0 AGPL-3.0" + + + Although you can use other settings, you might be required to + remove dependencies on or provide alternatives to components that + are required to produce a functional system image. + + .. note:: + + It is possible to define a list of licenses that are allowed to be + used instead of the licenses that are excluded. To do this, define + a variable + COMPATIBLE_LICENSES + with the names of the licences that are allowed. Then define + INCOMPATIBLE_LICENSE + as: + :: + + INCOMPATIBLE_LICENSE = "${@' '.join(sorted(set(d.getVar('AVAILABLE_LICENSES').split()) - set(d.getVar('COMPATIBLE_LICENSES').split())))}" + + + This will result in + INCOMPATIBLE_LICENSE + containing the names of all licences from + AVAILABLE_LICENSES + except the ones specified in + COMPATIBLE_LICENSES + , thus only allowing the latter licences to be used. + + INHERIT + Causes the named class or classes to be inherited globally. Anonymous + functions in the class or classes are not executed for the base + configuration and in each individual recipe. The OpenEmbedded build + system ignores changes to ``INHERIT`` in individual recipes. + + For more information on ``INHERIT``, see the + :ref:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata:\`\`inherit\`\` configuration directive`" + section in the Bitbake User Manual. + + INHERIT_DISTRO + Lists classes that will be inherited at the distribution level. It is + unlikely that you want to edit this variable. + + The default value of the variable is set as follows in the + ``meta/conf/distro/defaultsetup.conf`` file: + :: + + INHERIT_DISTRO ?= "debian devshell sstate license" + + INHIBIT_DEFAULT_DEPS + Prevents the default dependencies, namely the C compiler and standard + C library (libc), from being added to :term:`DEPENDS`. + This variable is usually used within recipes that do not require any + compilation using the C compiler. + + Set the variable to "1" to prevent the default dependencies from + being added. + + INHIBIT_PACKAGE_DEBUG_SPLIT + Prevents the OpenEmbedded build system from splitting out debug + information during packaging. By default, the build system splits out + debugging information during the + :ref:`ref-tasks-package` task. For more information on + how debug information is split out, see the + :term:`PACKAGE_DEBUG_SPLIT_STYLE` + variable. + + To prevent the build system from splitting out debug information + during packaging, set the ``INHIBIT_PACKAGE_DEBUG_SPLIT`` variable as + follows: + :: + + INHIBIT_PACKAGE_DEBUG_SPLIT = "1" + + INHIBIT_PACKAGE_STRIP + If set to "1", causes the build to not strip binaries in resulting + packages and prevents the ``-dbg`` package from containing the source + files. + + By default, the OpenEmbedded build system strips binaries and puts + the debugging symbols into ``${``\ :term:`PN`\ ``}-dbg``. + Consequently, you should not set ``INHIBIT_PACKAGE_STRIP`` when you + plan to debug in general. + + INHIBIT_SYSROOT_STRIP + If set to "1", causes the build to not strip binaries in the + resulting sysroot. + + By default, the OpenEmbedded build system strips binaries in the + resulting sysroot. When you specifically set the + ``INHIBIT_SYSROOT_STRIP`` variable to "1" in your recipe, you inhibit + this stripping. + + If you want to use this variable, include the + :ref:`staging <ref-classes-staging>` class. This class uses a + ``sys_strip()`` function to test for the variable and acts + accordingly. + + .. note:: + + Use of the + INHIBIT_SYSROOT_STRIP + variable occurs in rare and special circumstances. For example, + suppose you are building bare-metal firmware by using an external + GCC toolchain. Furthermore, even if the toolchain's binaries are + strippable, other files exist that are needed for the build that + are not strippable. + + INITRAMFS_FSTYPES + Defines the format for the output image of an initial RAM filesystem + (initramfs), which is used during boot. Supported formats are the + same as those supported by the + :term:`IMAGE_FSTYPES` variable. + + The default value of this variable, which is set in the + ``meta/conf/bitbake.conf`` configuration file in the + :term:`Source Directory`, is "cpio.gz". The Linux kernel's + initramfs mechanism, as opposed to the initial RAM filesystem + `initrd <https://en.wikipedia.org/wiki/Initrd>`__ mechanism, expects + an optionally compressed cpio archive. + + INITRAMFS_IMAGE + Specifies the :term:`PROVIDES` name of an image + recipe that is used to build an initial RAM filesystem (initramfs) + image. In other words, the ``INITRAMFS_IMAGE`` variable causes an + additional recipe to be built as a dependency to whatever root + filesystem recipe you might be using (e.g. ``core-image-sato``). The + initramfs image recipe you provide should set + :term:`IMAGE_FSTYPES` to + :term:`INITRAMFS_FSTYPES`. + + An initramfs image provides a temporary root filesystem used for + early system initialization (e.g. loading of modules needed to locate + and mount the "real" root filesystem). + + .. note:: + + See the + meta/recipes-core/images/core-image-minimal-initramfs.bb + recipe in the + Source Directory + for an example initramfs recipe. To select this sample recipe as + the one built to provide the initramfs image, set + INITRAMFS_IMAGE + to "core-image-minimal-initramfs". + + You can also find more information by referencing the + ``meta-poky/conf/local.conf.sample.extended`` configuration file in + the Source Directory, the :ref:`image <ref-classes-image>` class, + and the :ref:`kernel <ref-classes-kernel>` class to see how to use + the ``INITRAMFS_IMAGE`` variable. + + If ``INITRAMFS_IMAGE`` is empty, which is the default, then no + initramfs image is built. + + For more information, you can also see the + :term:`INITRAMFS_IMAGE_BUNDLE` + variable, which allows the generated image to be bundled inside the + kernel image. Additionally, for information on creating an initramfs + image, see the ":ref:`building-an-initramfs-image`" section + in the Yocto Project Development Tasks Manual. + + INITRAMFS_IMAGE_BUNDLE + Controls whether or not the image recipe specified by + :term:`INITRAMFS_IMAGE` is run through an + extra pass + (:ref:`ref-tasks-bundle_initramfs`) during + kernel compilation in order to build a single binary that contains + both the kernel image and the initial RAM filesystem (initramfs) + image. This makes use of the + :term:`CONFIG_INITRAMFS_SOURCE` kernel + feature. + + .. note:: + + Using an extra compilation pass to bundle the initramfs avoids a + circular dependency between the kernel recipe and the initramfs + recipe should the initramfs include kernel modules. Should that be + the case, the initramfs recipe depends on the kernel for the + kernel modules, and the kernel depends on the initramfs recipe + since the initramfs is bundled inside the kernel image. + + The combined binary is deposited into the ``tmp/deploy`` directory, + which is part of the :term:`Build Directory`. + + Setting the variable to "1" in a configuration file causes the + OpenEmbedded build system to generate a kernel image with the + initramfs specified in ``INITRAMFS_IMAGE`` bundled within: + :: + + INITRAMFS_IMAGE_BUNDLE = "1" + + By default, the + :ref:`kernel <ref-classes-kernel>` class sets this variable to a + null string as follows: + :: + + INITRAMFS_IMAGE_BUNDLE ?= "" + + .. note:: + + You must set the + INITRAMFS_IMAGE_BUNDLE + variable in a configuration file. You cannot set the variable in a + recipe file. + + See the + :yocto_git:`local.conf.sample.extended </cgit/cgit.cgi/poky/tree/meta-poky/conf/local.conf.sample.extended>` + file for additional information. Also, for information on creating an + initramfs, see the ":ref:`building-an-initramfs-image`" section + in the Yocto Project Development Tasks Manual. + + INITRAMFS_LINK_NAME + The link name of the initial RAM filesystem image. This variable is + set in the ``meta/classes/kernel-artifact-names.bbclass`` file as + follows: + :: + + INITRAMFS_LINK_NAME ?= "initramfs-${KERNEL_ARTIFACT_LINK_NAME}" + + The value of the + ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in the same + file, has the following value: + :: + + KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}" + + See the :term:`MACHINE` variable for additional + information. + + INITRAMFS_NAME + The base name of the initial RAM filesystem image. This variable is + set in the ``meta/classes/kernel-artifact-names.bbclass`` file as + follows: + :: + + INITRAMFS_NAME ?= "initramfs-${KERNEL_ARTIFACT_NAME}" + + The value of the :term:`KERNEL_ARTIFACT_NAME` + variable, which is set in the same file, has the following value: + :: + + KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}" + + INITRD + Indicates list of filesystem images to concatenate and use as an + initial RAM disk (``initrd``). + + The ``INITRD`` variable is an optional variable used with the + :ref:`image-live <ref-classes-image-live>` class. + + INITRD_IMAGE + When building a "live" bootable image (i.e. when + :term:`IMAGE_FSTYPES` contains "live"), + ``INITRD_IMAGE`` specifies the image recipe that should be built to + provide the initial RAM disk image. The default value is + "core-image-minimal-initramfs". + + See the :ref:`image-live <ref-classes-image-live>` class for more + information. + + INITSCRIPT_NAME + The filename of the initialization script as installed to + ``${sysconfdir}/init.d``. + + This variable is used in recipes when using ``update-rc.d.bbclass``. + The variable is mandatory. + + INITSCRIPT_PACKAGES + A list of the packages that contain initscripts. If multiple packages + are specified, you need to append the package name to the other + ``INITSCRIPT_*`` as an override. + + This variable is used in recipes when using ``update-rc.d.bbclass``. + The variable is optional and defaults to the :term:`PN` + variable. + + INITSCRIPT_PARAMS + Specifies the options to pass to ``update-rc.d``. Here is an example: + :: + + INITSCRIPT_PARAMS = "start 99 5 2 . stop 20 0 1 6 ." + + In this example, the script has a runlevel of 99, starts the script + in initlevels 2 and 5, and stops the script in levels 0, 1 and 6. + + The variable's default value is "defaults", which is set in the + :ref:`update-rc.d <ref-classes-update-rc.d>` class. + + The value in ``INITSCRIPT_PARAMS`` is passed through to the + ``update-rc.d`` command. For more information on valid parameters, + please see the ``update-rc.d`` manual page at + https://manpages.debian.org/buster/init-system-helpers/update-rc.d.8.en.html + + INSANE_SKIP + Specifies the QA checks to skip for a specific package within a + recipe. For example, to skip the check for symbolic link ``.so`` + files in the main package of a recipe, add the following to the + recipe. The package name override must be used, which in this example + is ``${PN}``: + :: + + INSANE_SKIP_${PN} += "dev-so" + + See the ":ref:`insane.bbclass <ref-classes-insane>`" section for a + list of the valid QA checks you can specify using this variable. + + INSTALL_TIMEZONE_FILE + By default, the ``tzdata`` recipe packages an ``/etc/timezone`` file. + Set the ``INSTALL_TIMEZONE_FILE`` variable to "0" at the + configuration level to disable this behavior. + + IPK_FEED_URIS + When the IPK backend is in use and package management is enabled on + the target, you can use this variable to set up ``opkg`` in the + target image to point to package feeds on a nominated server. Once + the feed is established, you can perform installations or upgrades + using the package manager at runtime. + + KARCH + Defines the kernel architecture used when assembling the + configuration. Architectures supported for this release are: + + - powerpc + - i386 + - x86_64 + - arm + - qemu + - mips + + You define the ``KARCH`` variable in the :ref:`kernel-dev/kernel-dev-advanced:bsp descriptions`. + + KBRANCH + A regular expression used by the build process to explicitly identify + the kernel branch that is validated, patched, and configured during a + build. You must set this variable to ensure the exact kernel branch + you want is being used by the build process. + + Values for this variable are set in the kernel's recipe file and the + kernel's append file. For example, if you are using the + ``linux-yocto_4.12`` kernel, the kernel recipe file is the + ``meta/recipes-kernel/linux/linux-yocto_4.12.bb`` file. ``KBRANCH`` + is set as follows in that kernel recipe file: + :: + + KBRANCH ?= "standard/base" + + This variable is also used from the kernel's append file to identify + the kernel branch specific to a particular machine or target + hardware. Continuing with the previous kernel example, the kernel's + append file (i.e. ``linux-yocto_4.12.bbappend``) is located in the + BSP layer for a given machine. For example, the append file for the + Beaglebone, EdgeRouter, and generic versions of both 32 and 64-bit IA + machines (``meta-yocto-bsp``) is named + ``meta-yocto-bsp/recipes-kernel/linux/linux-yocto_4.12.bbappend``. + Here are the related statements from that append file: + :: + + KBRANCH_genericx86 = "standard/base" + KBRANCH_genericx86-64 = "standard/base" + KBRANCH_edgerouter = "standard/edgerouter" + KBRANCH_beaglebone = "standard/beaglebone" + + The ``KBRANCH`` statements + identify the kernel branch to use when building for each supported + BSP. + + KBUILD_DEFCONFIG + When used with the :ref:`kernel-yocto <ref-classes-kernel-yocto>` + class, specifies an "in-tree" kernel configuration file for use + during a kernel build. + + Typically, when using a ``defconfig`` to configure a kernel during a + build, you place the file in your layer in the same manner as you + would place patch files and configuration fragment files (i.e. + "out-of-tree"). However, if you want to use a ``defconfig`` file that + is part of the kernel tree (i.e. "in-tree"), you can use the + ``KBUILD_DEFCONFIG`` variable and append the + :term:`KMACHINE` variable to point to the + ``defconfig`` file. + + To use the variable, set it in the append file for your kernel recipe + using the following form: + :: + + KBUILD_DEFCONFIG_KMACHINE ?= defconfig_file + + Here is an example from a "raspberrypi2" ``KMACHINE`` build that uses + a ``defconfig`` file named "bcm2709_defconfig": + :: + + KBUILD_DEFCONFIG_raspberrypi2 = "bcm2709_defconfig" + + As an alternative, you can use the following within your append file: + :: + + KBUILD_DEFCONFIG_pn-linux-yocto ?= defconfig_file + + For more + information on how to use the ``KBUILD_DEFCONFIG`` variable, see the + ":ref:`kernel-dev/kernel-dev-common:using an "in-tree" \`\`defconfig\`\` file`" + section in the Yocto Project Linux Kernel Development Manual. + + KERNEL_ALT_IMAGETYPE + Specifies an alternate kernel image type for creation in addition to + the kernel image type specified using the + :term:`KERNEL_IMAGETYPE` variable. + + KERNEL_ARTIFACT_NAME + Specifies the name of all of the build artifacts. You can change the + name of the artifacts by changing the ``KERNEL_ARTIFACT_NAME`` + variable. + + The value of ``KERNEL_ARTIFACT_NAME``, which is set in the + ``meta/classes/kernel-artifact-names.bbclass`` file, has the + following default value: + :: + + KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}" + + See the :term:`PKGE`, :term:`PKGV`, :term:`PKGR`, and :term:`MACHINE` + variables for additional information. + + .. note:: + + The IMAGE_VERSION_SUFFIX variable is set to DATETIME. + + KERNEL_CLASSES + A list of classes defining kernel image types that the + :ref:`kernel <ref-classes-kernel>` class should inherit. You + typically append this variable to enable extended image types. An + example is the "kernel-fitimage", which enables fitImage support and + resides in ``meta/classes/kernel-fitimage.bbclass``. You can register + custom kernel image types with the ``kernel`` class using this + variable. + + KERNEL_DEVICETREE + Specifies the name of the generated Linux kernel device tree (i.e. + the ``.dtb``) file. + + .. note:: + + Legacy support exists for specifying the full path to the device + tree. However, providing just the .dtb file is preferred. + + In order to use this variable, the + :ref:`kernel-devicetree <ref-classes-kernel-devicetree>` class must + be inherited. + + KERNEL_DTB_LINK_NAME + The link name of the kernel device tree binary (DTB). This variable + is set in the ``meta/classes/kernel-artifact-names.bbclass`` file as + follows: + :: + + KERNEL_DTB_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}" + + The + value of the ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in + the same file, has the following value: + :: + + KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}" + + See the :term:`MACHINE` variable for additional + information. + + KERNEL_DTB_NAME + The base name of the kernel device tree binary (DTB). This variable + is set in the ``meta/classes/kernel-artifact-names.bbclass`` file as + follows: + :: + + KERNEL_DTB_NAME ?= "${KERNEL_ARTIFACT_NAME}" + + The value of the :term:`KERNEL_ARTIFACT_NAME` + variable, which is set in the same file, has the following value: + :: + + KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}" + + KERNEL_EXTRA_ARGS + Specifies additional ``make`` command-line arguments the OpenEmbedded + build system passes on when compiling the kernel. + + KERNEL_FEATURES + Includes additional kernel metadata. In the OpenEmbedded build + system, the default Board Support Packages (BSPs) + :term:`Metadata` is provided through the + :term:`KMACHINE` and :term:`KBRANCH` + variables. You can use the ``KERNEL_FEATURES`` variable from within + the kernel recipe or kernel append file to further add metadata for + all BSPs or specific BSPs. + + The metadata you add through this variable includes config fragments + and features descriptions, which usually includes patches as well as + config fragments. You typically override the ``KERNEL_FEATURES`` + variable for a specific machine. In this way, you can provide + validated, but optional, sets of kernel configurations and features. + + For example, the following example from the ``linux-yocto-rt_4.12`` + kernel recipe adds "netfilter" and "taskstats" features to all BSPs + as well as "virtio" configurations to all QEMU machines. The last two + statements add specific configurations to targeted machine types: + :: + + KERNEL_EXTRA_FEATURES ?= "features/netfilter/netfilter.scc features/taskstats/taskstats.scc" + KERNEL_FEATURES_append = "${KERNEL_EXTRA_FEATURES}" + KERNEL_FEATURES_append_qemuall = "cfg/virtio.scc" + KERNEL_FEATURES_append_qemux86 = " cfg/sound.scc cfg/paravirt_kvm.scc" + KERNEL_FEATURES_append_qemux86-64 = "cfg/sound.scc" + + KERNEL_FIT_LINK_NAME + The link name of the kernel flattened image tree (FIT) image. This + variable is set in the ``meta/classes/kernel-artifact-names.bbclass`` + file as follows: + :: + + KERNEL_FIT_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}" + + The value of the + ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in the same + file, has the following value: + :: + + KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}" + + See the :term:`MACHINE` variable for additional + information. + + KERNEL_FIT_NAME + The base name of the kernel flattened image tree (FIT) image. This + variable is set in the ``meta/classes/kernel-artifact-names.bbclass`` + file as follows: + :: + + KERNEL_FIT_NAME ?= "${KERNEL_ARTIFACT_NAME}" + + The value of the :term:`KERNEL_ARTIFACT_NAME` + variable, which is set in the same file, has the following value: + :: + + KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}" + + KERNEL_IMAGE_LINK_NAME + The link name for the kernel image. This variable is set in the + ``meta/classes/kernel-artifact-names.bbclass`` file as follows: + :: + + KERNEL_IMAGE_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}" + + The value of + the ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in the same + file, has the following value: + :: + + KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}" + + See the :term:`MACHINE` variable for additional + information. + + KERNEL_IMAGE_MAXSIZE + Specifies the maximum size of the kernel image file in kilobytes. If + ``KERNEL_IMAGE_MAXSIZE`` is set, the size of the kernel image file is + checked against the set value during the + :ref:`ref-tasks-sizecheck` task. The task fails if + the kernel image file is larger than the setting. + + ``KERNEL_IMAGE_MAXSIZE`` is useful for target devices that have a + limited amount of space in which the kernel image must be stored. + + By default, this variable is not set, which means the size of the + kernel image is not checked. + + KERNEL_IMAGE_NAME + The base name of the kernel image. This variable is set in the + ``meta/classes/kernel-artifact-names.bbclass`` file as follows: + :: + + KERNEL_IMAGE_NAME ?= "${KERNEL_ARTIFACT_NAME}" + + The value of the + :term:`KERNEL_ARTIFACT_NAME` variable, + which is set in the same file, has the following value: + :: + + KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}" + + KERNEL_IMAGETYPE + The type of kernel to build for a device, usually set by the machine + configuration files and defaults to "zImage". This variable is used + when building the kernel and is passed to ``make`` as the target to + build. + + If you want to build an alternate kernel image type, use the + :term:`KERNEL_ALT_IMAGETYPE` variable. + + KERNEL_MODULE_AUTOLOAD + Lists kernel modules that need to be auto-loaded during boot. + + .. note:: + + This variable replaces the deprecated + module_autoload + variable. + + You can use the ``KERNEL_MODULE_AUTOLOAD`` variable anywhere that it + can be recognized by the kernel recipe or by an out-of-tree kernel + module recipe (e.g. a machine configuration file, a distribution + configuration file, an append file for the recipe, or the recipe + itself). + + Specify it as follows: + :: + + KERNEL_MODULE_AUTOLOAD += "module_name1 module_name2 module_name3" + + Including ``KERNEL_MODULE_AUTOLOAD`` causes the OpenEmbedded build + system to populate the ``/etc/modules-load.d/modname.conf`` file with + the list of modules to be auto-loaded on boot. The modules appear + one-per-line in the file. Here is an example of the most common use + case: + :: + + KERNEL_MODULE_AUTOLOAD += "module_name" + + For information on how to populate the ``modname.conf`` file with + ``modprobe.d`` syntax lines, see the :term:`KERNEL_MODULE_PROBECONF` variable. + + KERNEL_MODULE_PROBECONF + Provides a list of modules for which the OpenEmbedded build system + expects to find ``module_conf_``\ modname values that specify + configuration for each of the modules. For information on how to + provide those module configurations, see the + :term:`module_conf_* <module_conf>` variable. + + KERNEL_PATH + The location of the kernel sources. This variable is set to the value + of the :term:`STAGING_KERNEL_DIR` within + the :ref:`module <ref-classes-module>` class. For information on + how this variable is used, see the + ":ref:`kernel-dev/kernel-dev-common:incorporating out-of-tree modules`" + section in the Yocto Project Linux Kernel Development Manual. + + To help maximize compatibility with out-of-tree drivers used to build + modules, the OpenEmbedded build system also recognizes and uses the + :term:`KERNEL_SRC` variable, which is identical to + the ``KERNEL_PATH`` variable. Both variables are common variables + used by external Makefiles to point to the kernel source directory. + + KERNEL_SRC + The location of the kernel sources. This variable is set to the value + of the :term:`STAGING_KERNEL_DIR` within + the :ref:`module <ref-classes-module>` class. For information on + how this variable is used, see the + ":ref:`kernel-dev/kernel-dev-common:incorporating out-of-tree modules`" + section in the Yocto Project Linux Kernel Development Manual. + + To help maximize compatibility with out-of-tree drivers used to build + modules, the OpenEmbedded build system also recognizes and uses the + :term:`KERNEL_PATH` variable, which is identical + to the ``KERNEL_SRC`` variable. Both variables are common variables + used by external Makefiles to point to the kernel source directory. + + KERNEL_VERSION + Specifies the version of the kernel as extracted from ``version.h`` + or ``utsrelease.h`` within the kernel sources. Effects of setting + this variable do not take affect until the kernel has been + configured. Consequently, attempting to refer to this variable in + contexts prior to configuration will not work. + + KERNELDEPMODDEPEND + Specifies whether the data referenced through + :term:`PKGDATA_DIR` is needed or not. The + ``KERNELDEPMODDEPEND`` does not control whether or not that data + exists, but simply whether or not it is used. If you do not need to + use the data, set the ``KERNELDEPMODDEPEND`` variable in your + ``initramfs`` recipe. Setting the variable there when the data is not + needed avoids a potential dependency loop. + + KFEATURE_DESCRIPTION + Provides a short description of a configuration fragment. You use + this variable in the ``.scc`` file that describes a configuration + fragment file. Here is the variable used in a file named ``smp.scc`` + to describe SMP being enabled: + :: + + define KFEATURE_DESCRIPTION "Enable SMP" + + KMACHINE + The machine as known by the kernel. Sometimes the machine name used + by the kernel does not match the machine name used by the + OpenEmbedded build system. For example, the machine name that the + OpenEmbedded build system understands as ``core2-32-intel-common`` + goes by a different name in the Linux Yocto kernel. The kernel + understands that machine as ``intel-core2-32``. For cases like these, + the ``KMACHINE`` variable maps the kernel machine name to the + OpenEmbedded build system machine name. + + These mappings between different names occur in the Yocto Linux + Kernel's ``meta`` branch. As an example take a look in the + ``common/recipes-kernel/linux/linux-yocto_3.19.bbappend`` file: + :: + + LINUX_VERSION_core2-32-intel-common = "3.19.0" + COMPATIBLE_MACHINE_core2-32-intel-common = "${MACHINE}" + SRCREV_meta_core2-32-intel-common = "8897ef68b30e7426bc1d39895e71fb155d694974" + SRCREV_machine_core2-32-intel-common = "43b9eced9ba8a57add36af07736344dcc383f711" + KMACHINE_core2-32-intel-common = "intel-core2-32" + KBRANCH_core2-32-intel-common = "standard/base" + KERNEL_FEATURES_append_core2-32-intel-common = "${KERNEL_FEATURES_INTEL_COMMON}" + + The ``KMACHINE`` statement says + that the kernel understands the machine name as "intel-core2-32". + However, the OpenEmbedded build system understands the machine as + "core2-32-intel-common". + + KTYPE + Defines the kernel type to be used in assembling the configuration. + The linux-yocto recipes define "standard", "tiny", and "preempt-rt" + kernel types. See the ":ref:`kernel-dev/kernel-dev-advanced:kernel types`" + section in the + Yocto Project Linux Kernel Development Manual for more information on + kernel types. + + You define the ``KTYPE`` variable in the + :ref:`kernel-dev/kernel-dev-advanced:bsp descriptions`. The + value you use must match the value used for the + :term:`LINUX_KERNEL_TYPE` value used by the + kernel recipe. + + LABELS + Provides a list of targets for automatic configuration. + + See the :ref:`grub-efi <ref-classes-grub-efi>` class for more + information on how this variable is used. + + LAYERDEPENDS + Lists the layers, separated by spaces, on which this recipe depends. + Optionally, you can specify a specific layer version for a dependency + by adding it to the end of the layer name. Here is an example: + :: + + LAYERDEPENDS_mylayer = "anotherlayer (=3)" + + In this previous example, + version 3 of "anotherlayer" is compared against + :term:`LAYERVERSION`\ ``_anotherlayer``. + + An error is produced if any dependency is missing or the version + numbers (if specified) do not match exactly. This variable is used in + the ``conf/layer.conf`` file and must be suffixed with the name of + the specific layer (e.g. ``LAYERDEPENDS_mylayer``). + + LAYERDIR + When used inside the ``layer.conf`` configuration file, this variable + provides the path of the current layer. This variable is not + available outside of ``layer.conf`` and references are expanded + immediately when parsing of the file completes. + + LAYERRECOMMENDS + Lists the layers, separated by spaces, recommended for use with this + layer. + + Optionally, you can specify a specific layer version for a + recommendation by adding the version to the end of the layer name. + Here is an example: + :: + + LAYERRECOMMENDS_mylayer = "anotherlayer (=3)" + + In this previous example, version 3 of "anotherlayer" is compared + against ``LAYERVERSION_anotherlayer``. + + This variable is used in the ``conf/layer.conf`` file and must be + suffixed with the name of the specific layer (e.g. + ``LAYERRECOMMENDS_mylayer``). + + LAYERSERIES_COMPAT + Lists the versions of the :term:`OpenEmbedded-Core (OE-Core)` for which + a layer is compatible. Using the ``LAYERSERIES_COMPAT`` variable + allows the layer maintainer to indicate which combinations of the + layer and OE-Core can be expected to work. The variable gives the + system a way to detect when a layer has not been tested with new + releases of OE-Core (e.g. the layer is not maintained). + + To specify the OE-Core versions for which a layer is compatible, use + this variable in your layer's ``conf/layer.conf`` configuration file. + For the list, use the Yocto Project + :yocto_wiki:`Release Name </wiki/Releases>` (e.g. + DISTRO_NAME_NO_CAP). To specify multiple OE-Core versions for the + layer, use a space-separated list: + :: + + LAYERSERIES_COMPAT_layer_root_name = "DISTRO_NAME_NO_CAP DISTRO_NAME_NO_CAP_MINUS_ONE" + + .. note:: + + Setting + LAYERSERIES_COMPAT + is required by the Yocto Project Compatible version 2 standard. + The OpenEmbedded build system produces a warning if the variable + is not set for any given layer. + + See the ":ref:`dev-manual/dev-manual-common-tasks:creating your own layer`" + section in the Yocto Project Development Tasks Manual. + + LAYERVERSION + Optionally specifies the version of a layer as a single number. You + can use this within :term:`LAYERDEPENDS` for + another layer in order to depend on a specific version of the layer. + This variable is used in the ``conf/layer.conf`` file and must be + suffixed with the name of the specific layer (e.g. + ``LAYERVERSION_mylayer``). + + LD + The minimal command and arguments used to run the linker. + + LDFLAGS + Specifies the flags to pass to the linker. This variable is exported + to an environment variable and thus made visible to the software + being built during the compilation step. + + Default initialization for ``LDFLAGS`` varies depending on what is + being built: + + - :term:`TARGET_LDFLAGS` when building for the + target + + - :term:`BUILD_LDFLAGS` when building for the + build host (i.e. ``-native``) + + - :term:`BUILDSDK_LDFLAGS` when building for + an SDK (i.e. ``nativesdk-``) + + LEAD_SONAME + Specifies the lead (or primary) compiled library file (i.e. ``.so``) + that the :ref:`debian <ref-classes-debian>` class applies its + naming policy to given a recipe that packages multiple libraries. + + This variable works in conjunction with the ``debian`` class. + + LIC_FILES_CHKSUM + Checksums of the license text in the recipe source code. + + This variable tracks changes in license text of the source code + files. If the license text is changed, it will trigger a build + failure, which gives the developer an opportunity to review any + license change. + + This variable must be defined for all recipes (unless + :term:`LICENSE` is set to "CLOSED"). + + For more information, see the ":ref:`usingpoky-configuring-lic_files_chksum`" + section in the Yocto Project Development Tasks Manual. + + LICENSE + The list of source licenses for the recipe. Follow these rules: + + - Do not use spaces within individual license names. + + - Separate license names using \| (pipe) when there is a choice + between licenses. + + - Separate license names using & (ampersand) when multiple licenses + exist that cover different parts of the source. + + - You can use spaces between license names. + + - For standard licenses, use the names of the files in + ``meta/files/common-licenses/`` or the + :term:`SPDXLICENSEMAP` flag names defined in + ``meta/conf/licenses.conf``. + + Here are some examples: + :: + + LICENSE = "LGPLv2.1 | GPLv3" + LICENSE = "MPL-1 & LGPLv2.1" + LICENSE = "GPLv2+" + + The first example is from the + recipes for Qt, which the user may choose to distribute under either + the LGPL version 2.1 or GPL version 3. The second example is from + Cairo where two licenses cover different parts of the source code. + The final example is from ``sysstat``, which presents a single + license. + + You can also specify licenses on a per-package basis to handle + situations where components of the output have different licenses. + For example, a piece of software whose code is licensed under GPLv2 + but has accompanying documentation licensed under the GNU Free + Documentation License 1.2 could be specified as follows: + :: + + LICENSE = "GFDL-1.2 & GPLv2" + LICENSE_${PN} = "GPLv2" + LICENSE_${PN}-doc = "GFDL-1.2" + + LICENSE_CREATE_PACKAGE + Setting ``LICENSE_CREATE_PACKAGE`` to "1" causes the OpenEmbedded + build system to create an extra package (i.e. + ``${``\ :term:`PN`\ ``}-lic``) for each recipe and to add + those packages to the + :term:`RRECOMMENDS`\ ``_${PN}``. + + The ``${PN}-lic`` package installs a directory in + ``/usr/share/licenses`` named ``${PN}``, which is the recipe's base + name, and installs files in that directory that contain license and + copyright information (i.e. copies of the appropriate license files + from ``meta/common-licenses`` that match the licenses specified in + the :term:`LICENSE` variable of the recipe metadata + and copies of files marked in + :term:`LIC_FILES_CHKSUM` as containing + license text). + + For related information on providing license text, see the + :term:`COPY_LIC_DIRS` variable, the + :term:`COPY_LIC_MANIFEST` variable, and the + ":ref:`dev-manual/dev-manual-common-tasks:providing license text`" + section in the Yocto Project Development Tasks Manual. + + LICENSE_FLAGS + Specifies additional flags for a recipe you must whitelist through + :term:`LICENSE_FLAGS_WHITELIST` in + order to allow the recipe to be built. When providing multiple flags, + separate them with spaces. + + This value is independent of :term:`LICENSE` and is + typically used to mark recipes that might require additional licenses + in order to be used in a commercial product. For more information, + see the + ":ref:`dev-manual/dev-manual-common-tasks:enabling commercially licensed recipes`" + section in the Yocto Project Development Tasks Manual. + + LICENSE_FLAGS_WHITELIST + Lists license flags that when specified in + :term:`LICENSE_FLAGS` within a recipe should not + prevent that recipe from being built. This practice is otherwise + known as "whitelisting" license flags. For more information, see the + ":ref:`dev-manual/dev-manual-common-tasks:enabling commercially licensed recipes`" + section in the Yocto Project Development Tasks Manual. + + LICENSE_PATH + Path to additional licenses used during the build. By default, the + OpenEmbedded build system uses ``COMMON_LICENSE_DIR`` to define the + directory that holds common license text used during the build. The + ``LICENSE_PATH`` variable allows you to extend that location to other + areas that have additional licenses: + :: + + LICENSE_PATH += "path-to-additional-common-licenses" + + LINUX_KERNEL_TYPE + Defines the kernel type to be used in assembling the configuration. + The linux-yocto recipes define "standard", "tiny", and "preempt-rt" + kernel types. See the ":ref:`kernel-dev/kernel-dev-advanced:kernel types`" + section in the + Yocto Project Linux Kernel Development Manual for more information on + kernel types. + + If you do not specify a ``LINUX_KERNEL_TYPE``, it defaults to + "standard". Together with :term:`KMACHINE`, the + ``LINUX_KERNEL_TYPE`` variable defines the search arguments used by + the kernel tools to find the appropriate description within the + kernel :term:`Metadata` with which to build out the sources + and configuration. + + LINUX_VERSION + The Linux version from ``kernel.org`` on which the Linux kernel image + being built using the OpenEmbedded build system is based. You define + this variable in the kernel recipe. For example, the + ``linux-yocto-3.4.bb`` kernel recipe found in + ``meta/recipes-kernel/linux`` defines the variables as follows: + :: + + LINUX_VERSION ?= "3.4.24" + + The ``LINUX_VERSION`` variable is used to define :term:`PV` + for the recipe: + :: + + PV = "${LINUX_VERSION}+git${SRCPV}" + + LINUX_VERSION_EXTENSION + A string extension compiled into the version string of the Linux + kernel built with the OpenEmbedded build system. You define this + variable in the kernel recipe. For example, the linux-yocto kernel + recipes all define the variable as follows: + :: + + LINUX_VERSION_EXTENSION ?= "-yocto-${LINUX_KERNEL_TYPE}" + + Defining this variable essentially sets the Linux kernel + configuration item ``CONFIG_LOCALVERSION``, which is visible through + the ``uname`` command. Here is an example that shows the extension + assuming it was set as previously shown: + :: + + $ uname -r + 3.7.0-rc8-custom + + LOG_DIR + Specifies the directory to which the OpenEmbedded build system writes + overall log files. The default directory is ``${TMPDIR}/log``. + + For the directory containing logs specific to each task, see the + :term:`T` variable. + + MACHINE + Specifies the target device for which the image is built. You define + ``MACHINE`` in the ``local.conf`` file found in the + :term:`Build Directory`. By default, ``MACHINE`` is set to + "qemux86", which is an x86-based architecture machine to be emulated + using QEMU: + :: + + MACHINE ?= "qemux86" + + The variable corresponds to a machine configuration file of the same + name, through which machine-specific configurations are set. Thus, + when ``MACHINE`` is set to "qemux86" there exists the corresponding + ``qemux86.conf`` machine configuration file, which can be found in + the :term:`Source Directory` in + ``meta/conf/machine``. + + The list of machines supported by the Yocto Project as shipped + include the following: + :: + + MACHINE ?= "qemuarm" + MACHINE ?= "qemuarm64" + MACHINE ?= "qemumips" + MACHINE ?= "qemumips64" + MACHINE ?= "qemuppc" + MACHINE ?= "qemux86" + MACHINE ?= "qemux86-64" + MACHINE ?= "genericx86" + MACHINE ?= "genericx86-64" + MACHINE ?= "beaglebone" + MACHINE ?= "edgerouter" + + The last five are Yocto Project reference hardware + boards, which are provided in the ``meta-yocto-bsp`` layer. + + .. note:: + + Adding additional Board Support Package (BSP) layers to your + configuration adds new possible settings for + MACHINE + . + + MACHINE_ARCH + Specifies the name of the machine-specific architecture. This + variable is set automatically from :term:`MACHINE` or + :term:`TUNE_PKGARCH`. You should not hand-edit + the ``MACHINE_ARCH`` variable. + + MACHINE_ESSENTIAL_EXTRA_RDEPENDS + A list of required machine-specific packages to install as part of + the image being built. The build process depends on these packages + being present. Furthermore, because this is a "machine-essential" + variable, the list of packages are essential for the machine to boot. + The impact of this variable affects images based on + ``packagegroup-core-boot``, including the ``core-image-minimal`` + image. + + This variable is similar to the + ``MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS`` variable with the exception + that the image being built has a build dependency on the variable's + list of packages. In other words, the image will not build if a file + in this list is not found. + + As an example, suppose the machine for which you are building + requires ``example-init`` to be run during boot to initialize the + hardware. In this case, you would use the following in the machine's + ``.conf`` configuration file: + :: + + MACHINE_ESSENTIAL_EXTRA_RDEPENDS += "example-init" + + MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS + A list of recommended machine-specific packages to install as part of + the image being built. The build process does not depend on these + packages being present. However, because this is a + "machine-essential" variable, the list of packages are essential for + the machine to boot. The impact of this variable affects images based + on ``packagegroup-core-boot``, including the ``core-image-minimal`` + image. + + This variable is similar to the ``MACHINE_ESSENTIAL_EXTRA_RDEPENDS`` + variable with the exception that the image being built does not have + a build dependency on the variable's list of packages. In other + words, the image will still build if a package in this list is not + found. Typically, this variable is used to handle essential kernel + modules, whose functionality may be selected to be built into the + kernel rather than as a module, in which case a package will not be + produced. + + Consider an example where you have a custom kernel where a specific + touchscreen driver is required for the machine to be usable. However, + the driver can be built as a module or into the kernel depending on + the kernel configuration. If the driver is built as a module, you + want it to be installed. But, when the driver is built into the + kernel, you still want the build to succeed. This variable sets up a + "recommends" relationship so that in the latter case, the build will + not fail due to the missing package. To accomplish this, assuming the + package for the module was called ``kernel-module-ab123``, you would + use the following in the machine's ``.conf`` configuration file: + :: + + MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-module-ab123" + + .. note:: + + In this example, the + kernel-module-ab123 + recipe needs to explicitly set its + PACKAGES + variable to ensure that BitBake does not use the kernel recipe's + PACKAGES_DYNAMIC + variable to satisfy the dependency. + + Some examples of these machine essentials are flash, screen, + keyboard, mouse, or touchscreen drivers (depending on the machine). + + MACHINE_EXTRA_RDEPENDS + A list of machine-specific packages to install as part of the image + being built that are not essential for the machine to boot. However, + the build process for more fully-featured images depends on the + packages being present. + + This variable affects all images based on ``packagegroup-base``, + which does not include the ``core-image-minimal`` or + ``core-image-full-cmdline`` images. + + The variable is similar to the ``MACHINE_EXTRA_RRECOMMENDS`` variable + with the exception that the image being built has a build dependency + on the variable's list of packages. In other words, the image will + not build if a file in this list is not found. + + An example is a machine that has WiFi capability but is not essential + for the machine to boot the image. However, if you are building a + more fully-featured image, you want to enable the WiFi. The package + containing the firmware for the WiFi hardware is always expected to + exist, so it is acceptable for the build process to depend upon + finding the package. In this case, assuming the package for the + firmware was called ``wifidriver-firmware``, you would use the + following in the ``.conf`` file for the machine: + :: + + MACHINE_EXTRA_RDEPENDS += "wifidriver-firmware" + + MACHINE_EXTRA_RRECOMMENDS + A list of machine-specific packages to install as part of the image + being built that are not essential for booting the machine. The image + being built has no build dependency on this list of packages. + + This variable affects only images based on ``packagegroup-base``, + which does not include the ``core-image-minimal`` or + ``core-image-full-cmdline`` images. + + This variable is similar to the ``MACHINE_EXTRA_RDEPENDS`` variable + with the exception that the image being built does not have a build + dependency on the variable's list of packages. In other words, the + image will build if a file in this list is not found. + + An example is a machine that has WiFi capability but is not essential + For the machine to boot the image. However, if you are building a + more fully-featured image, you want to enable WiFi. In this case, the + package containing the WiFi kernel module will not be produced if the + WiFi driver is built into the kernel, in which case you still want + the build to succeed instead of failing as a result of the package + not being found. To accomplish this, assuming the package for the + module was called ``kernel-module-examplewifi``, you would use the + following in the ``.conf`` file for the machine: + :: + + MACHINE_EXTRA_RRECOMMENDS += "kernel-module-examplewifi" + + MACHINE_FEATURES + Specifies the list of hardware features the + :term:`MACHINE` is capable of supporting. For related + information on enabling features, see the + :term:`DISTRO_FEATURES`, + :term:`COMBINED_FEATURES`, and + :term:`IMAGE_FEATURES` variables. + + For a list of hardware features supported by the Yocto Project as + shipped, see the "`Machine Features <#ref-features-machine>`__" + section. + + MACHINE_FEATURES_BACKFILL + Features to be added to ``MACHINE_FEATURES`` if not also present in + ``MACHINE_FEATURES_BACKFILL_CONSIDERED``. + + This variable is set in the ``meta/conf/bitbake.conf`` file. It is + not intended to be user-configurable. It is best to just reference + the variable to see which machine features are being backfilled for + all machine configurations. See the "`Feature + Backfilling <#ref-features-backfill>`__" section for more + information. + + MACHINE_FEATURES_BACKFILL_CONSIDERED + Features from ``MACHINE_FEATURES_BACKFILL`` that should not be + backfilled (i.e. added to ``MACHINE_FEATURES``) during the build. See + the "`Feature Backfilling <#ref-features-backfill>`__" section for + more information. + + MACHINEOVERRIDES + A colon-separated list of overrides that apply to the current + machine. By default, this list includes the value of + :term:`MACHINE`. + + You can extend ``MACHINEOVERRIDES`` to add extra overrides that + should apply to a machine. For example, all machines emulated in QEMU + (e.g. ``qemuarm``, ``qemux86``, and so forth) include a file named + ``meta/conf/machine/include/qemu.inc`` that prepends the following + override to ``MACHINEOVERRIDES``: + :: + + MACHINEOVERRIDES =. "qemuall:" + + This + override allows variables to be overriden for all machines emulated + in QEMU, like in the following example from the ``connman-conf`` + recipe: + :: + + SRC_URI_append_qemuall = "file://wired.config \ + file://wired-setup \ + " + + The underlying mechanism behind + ``MACHINEOVERRIDES`` is simply that it is included in the default + value of :term:`OVERRIDES`. + + MAINTAINER + The email address of the distribution maintainer. + + MIRRORS + Specifies additional paths from which the OpenEmbedded build system + gets source code. When the build system searches for source code, it + first tries the local download directory. If that location fails, the + build system tries locations defined by + :term:`PREMIRRORS`, the upstream source, and then + locations specified by ``MIRRORS`` in that order. + + Assuming your distribution (:term:`DISTRO`) is "poky", + the default value for ``MIRRORS`` is defined in the + ``conf/distro/poky.conf`` file in the ``meta-poky`` Git repository. + + MLPREFIX + Specifies a prefix has been added to :term:`PN` to create a + special version of a recipe or package (i.e. a Multilib version). The + variable is used in places where the prefix needs to be added to or + removed from a the name (e.g. the :term:`BPN` variable). + ``MLPREFIX`` gets set when a prefix has been added to ``PN``. + + .. note:: + + The "ML" in + MLPREFIX + stands for "MultiLib". This representation is historical and comes + from a time when + nativesdk + was a suffix rather than a prefix on the recipe name. When + nativesdk + was turned into a prefix, it made sense to set + MLPREFIX + for it as well. + + To help understand when ``MLPREFIX`` might be needed, consider when + :term:`BBCLASSEXTEND` is used to provide a + ``nativesdk`` version of a recipe in addition to the target version. + If that recipe declares build-time dependencies on tasks in other + recipes by using :term:`DEPENDS`, then a dependency on + "foo" will automatically get rewritten to a dependency on + "nativesdk-foo". However, dependencies like the following will not + get rewritten automatically: + :: + + do_foo[depends] += "recipe:do_foo" + + If you want such a dependency to also get transformed, you can do the + following: + :: + + do_foo[depends] += "${MLPREFIX}recipe:do_foo" + + module_autoload + This variable has been replaced by the ``KERNEL_MODULE_AUTOLOAD`` + variable. You should replace all occurrences of ``module_autoload`` + with additions to ``KERNEL_MODULE_AUTOLOAD``, for example: + :: + + module_autoload_rfcomm = "rfcomm" + + should now be replaced with: + :: + + KERNEL_MODULE_AUTOLOAD += "rfcomm" + + See the :term:`KERNEL_MODULE_AUTOLOAD` variable for more information. + + module_conf + Specifies `modprobe.d <http://linux.die.net/man/5/modprobe.d>`_ + syntax lines for inclusion in the ``/etc/modprobe.d/modname.conf`` + file. + + You can use this variable anywhere that it can be recognized by the + kernel recipe or out-of-tree kernel module recipe (e.g. a machine + configuration file, a distribution configuration file, an append file + for the recipe, or the recipe itself). If you use this variable, you + must also be sure to list the module name in the + :term:`KERNEL_MODULE_AUTOLOAD` + variable. + + Here is the general syntax: + :: + + module_conf_module_name = "modprobe.d-syntax" + + You must use the kernel module name override. + + Run ``man modprobe.d`` in the shell to find out more information on + the exact syntax you want to provide with ``module_conf``. + + Including ``module_conf`` causes the OpenEmbedded build system to + populate the ``/etc/modprobe.d/modname.conf`` file with + ``modprobe.d`` syntax lines. Here is an example that adds the options + ``arg1`` and ``arg2`` to a module named ``mymodule``: + :: + + module_conf_mymodule = "options mymodule arg1=val1 arg2=val2" + + For information on how to specify kernel modules to auto-load on + boot, see the :term:`KERNEL_MODULE_AUTOLOAD` variable. + + MODULE_TARBALL_DEPLOY + Controls creation of the ``modules-*.tgz`` file. Set this variable to + "0" to disable creation of this file, which contains all of the + kernel modules resulting from a kernel build. + + MODULE_TARBALL_LINK_NAME + The link name of the kernel module tarball. This variable is set in + the ``meta/classes/kernel-artifact-names.bbclass`` file as follows: + :: + + MODULE_TARBALL_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}" + + The value + of the ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in the + same file, has the following value: + :: + + KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}" + + See the :term:`MACHINE` variable for additional information. + + MODULE_TARBALL_NAME + The base name of the kernel module tarball. This variable is set in + the ``meta/classes/kernel-artifact-names.bbclass`` file as follows: + :: + + MODULE_TARBALL_NAME ?= "${KERNEL_ARTIFACT_NAME}" + + The value of the :term:`KERNEL_ARTIFACT_NAME` variable, + which is set in the same file, has the following value: + :: + + KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}" + + MULTIMACH_TARGET_SYS + Uniquely identifies the type of the target system for which packages + are being built. This variable allows output for different types of + target systems to be put into different subdirectories of the same + output directory. + + The default value of this variable is: + :: + + ${PACKAGE_ARCH}${TARGET_VENDOR}-${TARGET_OS} + + Some classes (e.g. + :ref:`cross-canadian <ref-classes-cross-canadian>`) modify the + ``MULTIMACH_TARGET_SYS`` value. + + See the :term:`STAMP` variable for an example. See the + :term:`STAGING_DIR_TARGET` variable for more information. + + NATIVELSBSTRING + A string identifying the host distribution. Strings consist of the + host distributor ID followed by the release, as reported by the + ``lsb_release`` tool or as read from ``/etc/lsb-release``. For + example, when running a build on Ubuntu 12.10, the value is + "Ubuntu-12.10". If this information is unable to be determined, the + value resolves to "Unknown". + + This variable is used by default to isolate native shared state + packages for different distributions (e.g. to avoid problems with + ``glibc`` version incompatibilities). Additionally, the variable is + checked against + :term:`SANITY_TESTED_DISTROS` if that + variable is set. + + NM + The minimal command and arguments to run ``nm``. + + NO_GENERIC_LICENSE + Avoids QA errors when you use a non-common, non-CLOSED license in a + recipe. Packages exist, such as the linux-firmware package, with many + licenses that are not in any way common. Also, new licenses are added + occasionally to avoid introducing a lot of common license files, + which are only applicable to a specific package. + ``NO_GENERIC_LICENSE`` is used to allow copying a license that does + not exist in common licenses. + + The following example shows how to add ``NO_GENERIC_LICENSE`` to a + recipe: + :: + + NO_GENERIC_LICENSE[license_name] = "license_file_in_fetched_source" + + The following is an example that + uses the ``LICENSE.Abilis.txt`` file as the license from the fetched + source: + :: + + NO_GENERIC_LICENSE[Firmware-Abilis] = "LICENSE.Abilis.txt" + + NO_RECOMMENDATIONS + Prevents installation of all "recommended-only" packages. + Recommended-only packages are packages installed only through the + :term:`RRECOMMENDS` variable). Setting the + ``NO_RECOMMENDATIONS`` variable to "1" turns this feature on: :: + + NO_RECOMMENDATIONS = "1" + + You can set this variable globally in your ``local.conf`` file or you + can attach it to a specific image recipe by using the recipe name + override: :: + + NO_RECOMMENDATIONS_pn-target_image = "1" + + It is important to realize that if you choose to not install packages + using this variable and some other packages are dependent on them + (i.e. listed in a recipe's :term:`RDEPENDS` + variable), the OpenEmbedded build system ignores your request and + will install the packages to avoid dependency errors. + + .. note:: + + Some recommended packages might be required for certain system + functionality, such as kernel modules. It is up to you to add + packages with the IMAGE_INSTALL variable. + + Support for this variable exists only when using the IPK and RPM + packaging backend. Support does not exist for DEB. + + See the :term:`BAD_RECOMMENDATIONS` and + the :term:`PACKAGE_EXCLUDE` variables for + related information. + + NOAUTOPACKAGEDEBUG + Disables auto package from splitting ``.debug`` files. If a recipe + requires ``FILES_${PN}-dbg`` to be set manually, the + ``NOAUTOPACKAGEDEBUG`` can be defined allowing you to define the + content of the debug package. For example: + :: + + NOAUTOPACKAGEDEBUG = "1" + FILES_${PN}-dev = "${includedir}/${QT_DIR_NAME}/Qt/*" + FILES_${PN}-dbg = "/usr/src/debug/" + FILES_${QT_BASE_NAME}-demos-doc = "${docdir}/${QT_DIR_NAME}/qch/qt.qch" + + OBJCOPY + The minimal command and arguments to run ``objcopy``. + + OBJDUMP + The minimal command and arguments to run ``objdump``. + + OE_BINCONFIG_EXTRA_MANGLE + When inheriting the :ref:`binconfig <ref-classes-binconfig>` class, + this variable specifies additional arguments passed to the "sed" + command. The sed command alters any paths in configuration scripts + that have been set up during compilation. Inheriting this class + results in all paths in these scripts being changed to point into the + ``sysroots/`` directory so that all builds that use the script will + use the correct directories for the cross compiling layout. + + See the ``meta/classes/binconfig.bbclass`` in the + :term:`Source Directory` for details on how this class + applies these additional sed command arguments. For general + information on the ``binconfig`` class, see the + ":ref:`binconfig.bbclass <ref-classes-binconfig>`" section. + + OE_IMPORTS + An internal variable used to tell the OpenEmbedded build system what + Python modules to import for every Python function run by the system. + + .. note:: + + Do not set this variable. It is for internal use only. + + OE_INIT_ENV_SCRIPT + The name of the build environment setup script for the purposes of + setting up the environment within the extensible SDK. The default + value is "oe-init-build-env". + + If you use a custom script to set up your build environment, set the + ``OE_INIT_ENV_SCRIPT`` variable to its name. + + OE_TERMINAL + Controls how the OpenEmbedded build system spawns interactive + terminals on the host development system (e.g. using the BitBake + command with the ``-c devshell`` command-line option). For more + information, see the ":ref:`platdev-appdev-devshell`" section in + the Yocto Project Development Tasks Manual. + + You can use the following values for the ``OE_TERMINAL`` variable: + + - auto + - gnome + - xfce + - rxvt + - screen + - konsole + - none + + OEROOT + The directory from which the top-level build environment setup script + is sourced. The Yocto Project provides a top-level build environment + setup script: ````` <#structure-core-script>`__. When you run this + script, the ``OEROOT`` variable resolves to the directory that + contains the script. + + For additional information on how this variable is used, see the + initialization script. + + OLDEST_KERNEL + Declares the oldest version of the Linux kernel that the produced + binaries must support. This variable is passed into the build of the + Embedded GNU C Library (``glibc``). + + The default for this variable comes from the + ``meta/conf/bitbake.conf`` configuration file. You can override this + default by setting the variable in a custom distribution + configuration file. + + OVERRIDES + A colon-separated list of overrides that currently apply. Overrides + are a BitBake mechanism that allows variables to be selectively + overridden at the end of parsing. The set of overrides in + ``OVERRIDES`` represents the "state" during building, which includes + the current recipe being built, the machine for which it is being + built, and so forth. + + As an example, if the string "an-override" appears as an element in + the colon-separated list in ``OVERRIDES``, then the following + assignment will override ``FOO`` with the value "overridden" at the + end of parsing: + :: + + FOO_an-override = "overridden" + + See the + ":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata:conditional syntax (overrides)`" + section in the BitBake User Manual for more information on the + overrides mechanism. + + The default value of ``OVERRIDES`` includes the values of the + :term:`CLASSOVERRIDE`, + :term:`MACHINEOVERRIDES`, and + :term:`DISTROOVERRIDES` variables. Another + important override included by default is ``pn-${PN}``. This override + allows variables to be set for a single recipe within configuration + (``.conf``) files. Here is an example: + :: + + FOO_pn-myrecipe = "myrecipe-specific value" + + .. note:: + + An easy way to see what overrides apply is to search for + OVERRIDES + in the output of the + bitbake -e + command. See the " + Viewing Variable Values + " section in the Yocto Project Development Tasks Manual for more + information. + + P + The recipe name and version. ``P`` is comprised of the following: + :: + + ${PN}-${PV} + + PACKAGE_ADD_METADATA + This variable defines additional metdata to add to packages. + + You may find you need to inject additional metadata into packages. + This variable allows you to do that by setting the injected data as + the value. Multiple fields can be added by splitting the content with + the literal separator "\n". + + The suffixes '_IPK', '_DEB', or '_RPM' can be applied to the variable + to do package type specific settings. It can also be made package + specific by using the package name as a suffix. + + You can find out more about applying this variable in the + ":ref:`dev-manual/dev-manual-common-tasks:adding custom metadata to packages`" + section in the Yocto Project Development Tasks Manual. + + PACKAGE_ARCH + The architecture of the resulting package or packages. + + By default, the value of this variable is set to + :term:`TUNE_PKGARCH` when building for the + target, :term:`BUILD_ARCH` when building for the + build host, and "${SDK_ARCH}-${SDKPKGSUFFIX}" when building for the + SDK. + + .. note:: + + See + SDK_ARCH + for more information. + + However, if your recipe's output packages are built specific to the + target machine rather than generally for the architecture of the + machine, you should set ``PACKAGE_ARCH`` to the value of + :term:`MACHINE_ARCH` in the recipe as follows: + :: + + PACKAGE_ARCH = "${MACHINE_ARCH}" + + PACKAGE_ARCHS + Specifies a list of architectures compatible with the target machine. + This variable is set automatically and should not normally be + hand-edited. Entries are separated using spaces and listed in order + of priority. The default value for ``PACKAGE_ARCHS`` is "all any + noarch ${PACKAGE_EXTRA_ARCHS} ${MACHINE_ARCH}". + + PACKAGE_BEFORE_PN + Enables easily adding packages to ``PACKAGES`` before ``${PN}`` so + that those added packages can pick up files that would normally be + included in the default package. + + PACKAGE_CLASSES + This variable, which is set in the ``local.conf`` configuration file + found in the ``conf`` folder of the + :term:`Build Directory`, specifies the package manager the + OpenEmbedded build system uses when packaging data. + + You can provide one or more of the following arguments for the + variable: PACKAGE_CLASSES ?= "package_rpm package_deb package_ipk + package_tar" + + .. note:: + + While it is a legal option, the + package_tar + class has limited functionality due to no support for package + dependencies by that backend. Therefore, it is recommended that + you do not use it. + + The build system uses only the first argument in the list as the + package manager when creating your image or SDK. However, packages + will be created using any additional packaging classes you specify. + For example, if you use the following in your ``local.conf`` file: + :: + + PACKAGE_CLASSES ?= "package_ipk" + + The OpenEmbedded build system uses + the IPK package manager to create your image or SDK. + + For information on packaging and build performance effects as a + result of the package manager in use, see the + ":ref:`package.bbclass <ref-classes-package>`" section. + + PACKAGE_DEBUG_SPLIT_STYLE + Determines how to split up the binary and debug information when + creating ``*-dbg`` packages to be used with the GNU Project Debugger + (GDB). + + With the ``PACKAGE_DEBUG_SPLIT_STYLE`` variable, you can control + where debug information, which can include or exclude source files, + is stored: + + - ".debug": Debug symbol files are placed next to the binary in a + ``.debug`` directory on the target. For example, if a binary is + installed into ``/bin``, the corresponding debug symbol files are + installed in ``/bin/.debug``. Source files are placed in + ``/usr/src/debug``. + + - "debug-file-directory": Debug symbol files are placed under + ``/usr/lib/debug`` on the target, and separated by the path from + where the binary is installed. For example, if a binary is + installed in ``/bin``, the corresponding debug symbols are + installed in ``/usr/lib/debug/bin``. Source files are placed in + ``/usr/src/debug``. + + - "debug-without-src": The same behavior as ".debug" previously + described with the exception that no source files are installed. + + - "debug-with-srcpkg": The same behavior as ".debug" previously + described with the exception that all source files are placed in a + separate ``*-src`` pkg. This is the default behavior. + + You can find out more about debugging using GDB by reading the + ":ref:`platdev-gdb-remotedebug`" section + in the Yocto Project Development Tasks Manual. + + PACKAGE_EXCLUDE_COMPLEMENTARY + Prevents specific packages from being installed when you are + installing complementary packages. + + You might find that you want to prevent installing certain packages + when you are installing complementary packages. For example, if you + are using :term:`IMAGE_FEATURES` to install + ``dev-pkgs``, you might not want to install all packages from a + particular multilib. If you find yourself in this situation, you can + use the ``PACKAGE_EXCLUDE_COMPLEMENTARY`` variable to specify regular + expressions to match the packages you want to exclude. + + PACKAGE_EXCLUDE + Lists packages that should not be installed into an image. For + example: + :: + + PACKAGE_EXCLUDE = "package_name package_name package_name ..." + + You can set this variable globally in your ``local.conf`` file or you + can attach it to a specific image recipe by using the recipe name + override: + :: + + PACKAGE_EXCLUDE_pn-target_image = "package_name" + + If you choose to not install a package using this variable and some + other package is dependent on it (i.e. listed in a recipe's + :term:`RDEPENDS` variable), the OpenEmbedded build + system generates a fatal installation error. Because the build system + halts the process with a fatal error, you can use the variable with + an iterative development process to remove specific components from a + system. + + Support for this variable exists only when using the IPK and RPM + packaging backend. Support does not exist for DEB. + + See the :term:`NO_RECOMMENDATIONS` and the + :term:`BAD_RECOMMENDATIONS` variables for + related information. + + PACKAGE_EXTRA_ARCHS + Specifies the list of architectures compatible with the device CPU. + This variable is useful when you build for several different devices + that use miscellaneous processors such as XScale and ARM926-EJS. + + PACKAGE_FEED_ARCHS + Optionally specifies the package architectures used as part of the + package feed URIs during the build. When used, the + ``PACKAGE_FEED_ARCHS`` variable is appended to the final package feed + URI, which is constructed using the + :term:`PACKAGE_FEED_URIS` and + :term:`PACKAGE_FEED_BASE_PATHS` + variables. + + .. note:: + + You can use the + PACKAGE_FEEDS_ARCHS + variable to whitelist specific package architectures. If you do + not need to whitelist specific architectures, which is a common + case, you can omit this variable. Omitting the variable results in + all available architectures for the current machine being included + into remote package feeds. + + Consider the following example where the ``PACKAGE_FEED_URIS``, + ``PACKAGE_FEED_BASE_PATHS``, and ``PACKAGE_FEED_ARCHS`` variables are + defined in your ``local.conf`` file: + :: + + PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \ + https://example.com/packagerepos/updates" + PACKAGE_FEED_BASE_PATHS = "rpm rpm-dev" + PACKAGE_FEED_ARCHS = "all core2-64" + + Given these settings, the resulting package feeds are as follows: + :: + + https://example.com/packagerepos/release/rpm/all + https://example.com/packagerepos/release/rpm/core2-64 + https://example.com/packagerepos/release/rpm-dev/all + https://example.com/packagerepos/release/rpm-dev/core2-64 + https://example.com/packagerepos/updates/rpm/all + https://example.com/packagerepos/updates/rpm/core2-64 + https://example.com/packagerepos/updates/rpm-dev/all + https://example.com/packagerepos/updates/rpm-dev/core2-64 + + PACKAGE_FEED_BASE_PATHS + Specifies the base path used when constructing package feed URIs. The + ``PACKAGE_FEED_BASE_PATHS`` variable makes up the middle portion of a + package feed URI used by the OpenEmbedded build system. The base path + lies between the :term:`PACKAGE_FEED_URIS` + and :term:`PACKAGE_FEED_ARCHS` variables. + + Consider the following example where the ``PACKAGE_FEED_URIS``, + ``PACKAGE_FEED_BASE_PATHS``, and ``PACKAGE_FEED_ARCHS`` variables are + defined in your ``local.conf`` file: + :: + + PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \ + https://example.com/packagerepos/updates" + PACKAGE_FEED_BASE_PATHS = "rpm rpm-dev" + PACKAGE_FEED_ARCHS = "all core2-64" + + Given these settings, the resulting package feeds are as follows: + :: + + https://example.com/packagerepos/release/rpm/all + https://example.com/packagerepos/release/rpm/core2-64 + https://example.com/packagerepos/release/rpm-dev/all + https://example.com/packagerepos/release/rpm-dev/core2-64 + https://example.com/packagerepos/updates/rpm/all + https://example.com/packagerepos/updates/rpm/core2-64 + https://example.com/packagerepos/updates/rpm-dev/all + https://example.com/packagerepos/updates/rpm-dev/core2-64 + + PACKAGE_FEED_URIS + Specifies the front portion of the package feed URI used by the + OpenEmbedded build system. Each final package feed URI is comprised + of ``PACKAGE_FEED_URIS``, + :term:`PACKAGE_FEED_BASE_PATHS`, and + :term:`PACKAGE_FEED_ARCHS` variables. + + Consider the following example where the ``PACKAGE_FEED_URIS``, + ``PACKAGE_FEED_BASE_PATHS``, and ``PACKAGE_FEED_ARCHS`` variables are + defined in your ``local.conf`` file: + :: + + PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \ + https://example.com/packagerepos/updates" + PACKAGE_FEED_BASE_PATHS = "rpm rpm-dev" + PACKAGE_FEED_ARCHS = "all core2-64" + + Given these settings, the resulting package feeds are as follows: + :: + + https://example.com/packagerepos/release/rpm/all + https://example.com/packagerepos/release/rpm/core2-64 + https://example.com/packagerepos/release/rpm-dev/all + https://example.com/packagerepos/release/rpm-dev/core2-64 + https://example.com/packagerepos/updates/rpm/all + https://example.com/packagerepos/updates/rpm/core2-64 + https://example.com/packagerepos/updates/rpm-dev/all + https://example.com/packagerepos/updates/rpm-dev/core2-64 + + PACKAGE_INSTALL + The final list of packages passed to the package manager for + installation into the image. + + Because the package manager controls actual installation of all + packages, the list of packages passed using ``PACKAGE_INSTALL`` is + not the final list of packages that are actually installed. This + variable is internal to the image construction code. Consequently, in + general, you should use the + :term:`IMAGE_INSTALL` variable to specify + packages for installation. The exception to this is when working with + the + ```core-image-minimal-initramfs`` <#images-core-image-minimal-initramfs>`__ + image. When working with an initial RAM filesystem (initramfs) image, + use the ``PACKAGE_INSTALL`` variable. For information on creating an + initramfs, see the ":ref:`building-an-initramfs-image`" section + in the Yocto Project Development Tasks Manual. + + PACKAGE_INSTALL_ATTEMPTONLY + Specifies a list of packages the OpenEmbedded build system attempts + to install when creating an image. If a listed package fails to + install, the build system does not generate an error. This variable + is generally not user-defined. + + PACKAGE_PREPROCESS_FUNCS + Specifies a list of functions run to pre-process the + :term:`PKGD` directory prior to splitting the files out + to individual packages. + + PACKAGE_WRITE_DEPS + Specifies a list of dependencies for post-installation and + pre-installation scripts on native/cross tools. If your + post-installation or pre-installation script can execute at rootfs + creation time rather than on the target but depends on a native tool + in order to execute, you need to list the tools in + ``PACKAGE_WRITE_DEPS``. + + For information on running post-installation scripts, see the + ":ref:`dev-manual/dev-manual-common-tasks:post-installation scripts`" + section in the Yocto Project Development Tasks Manual. + + PACKAGECONFIG + This variable provides a means of enabling or disabling features of a + recipe on a per-recipe basis. ``PACKAGECONFIG`` blocks are defined in + recipes when you specify features and then arguments that define + feature behaviors. Here is the basic block structure (broken over + multiple lines for readability): + :: + + PACKAGECONFIG ??= "f1 f2 f3 ..." + PACKAGECONFIG[f1] = "\ + --with-f1, \ + --without-f1, \ + build-deps-for-f1, \ + runtime-deps-for-f1, \ + runtime-recommends-for-f1, \ + packageconfig-conflicts-for-f1" + PACKAGECONFIG[f2] = "\ + ... and so on and so on ... + + The ``PACKAGECONFIG`` variable itself specifies a space-separated + list of the features to enable. Following the features, you can + determine the behavior of each feature by providing up to six + order-dependent arguments, which are separated by commas. You can + omit any argument you like but must retain the separating commas. The + order is important and specifies the following: + + 1. Extra arguments that should be added to the configure script + argument list (:term:`EXTRA_OECONF` or + :term:`PACKAGECONFIG_CONFARGS`) if + the feature is enabled. + + 2. Extra arguments that should be added to ``EXTRA_OECONF`` or + ``PACKAGECONFIG_CONFARGS`` if the feature is disabled. + + 3. Additional build dependencies (:term:`DEPENDS`) + that should be added if the feature is enabled. + + 4. Additional runtime dependencies (:term:`RDEPENDS`) + that should be added if the feature is enabled. + + 5. Additional runtime recommendations + (:term:`RRECOMMENDS`) that should be added if + the feature is enabled. + + 6. Any conflicting (that is, mutually exclusive) ``PACKAGECONFIG`` + settings for this feature. + + Consider the following ``PACKAGECONFIG`` block taken from the + ``librsvg`` recipe. In this example the feature is ``gtk``, which has + three arguments that determine the feature's behavior. + :: + + PACKAGECONFIG[gtk] = "--with-gtk3,--without-gtk3,gtk+3" + + The + ``--with-gtk3`` and ``gtk+3`` arguments apply only if the feature is + enabled. In this case, ``--with-gtk3`` is added to the configure + script argument list and ``gtk+3`` is added to ``DEPENDS``. On the + other hand, if the feature is disabled say through a ``.bbappend`` + file in another layer, then the second argument ``--without-gtk3`` is + added to the configure script instead. + + The basic ``PACKAGECONFIG`` structure previously described holds true + regardless of whether you are creating a block or changing a block. + When creating a block, use the structure inside your recipe. + + If you want to change an existing ``PACKAGECONFIG`` block, you can do + so one of two ways: + + - *Append file:* Create an append file named + recipename\ ``.bbappend`` in your layer and override the value of + ``PACKAGECONFIG``. You can either completely override the + variable: + :: + + PACKAGECONFIG = "f4 f5" + + Or, you can just append the variable: + :: + + PACKAGECONFIG_append = " f4" + + - *Configuration file:* This method is identical to changing the + block through an append file except you edit your ``local.conf`` + or ``mydistro.conf`` file. As with append files previously + described, you can either completely override the variable: + PACKAGECONFIG_pn-recipename = "f4 f5" Or, you can just amend the + variable: + :: + + PACKAGECONFIG_append_pn-recipename = " f4" + + PACKAGECONFIG_CONFARGS + A space-separated list of configuration options generated from the + :term:`PACKAGECONFIG` setting. + + Classes such as :ref:`autotools <ref-classes-autotools>` and + :ref:`cmake <ref-classes-cmake>` use ``PACKAGECONFIG_CONFARGS`` to + pass ``PACKAGECONFIG`` options to ``configure`` and ``cmake``, + respectively. If you are using ``PACKAGECONFIG`` but not a class that + handles the ``do_configure`` task, then you need to use + ``PACKAGECONFIG_CONFARGS`` appropriately. + + PACKAGEGROUP_DISABLE_COMPLEMENTARY + For recipes inheriting the + :ref:`packagegroup <ref-classes-packagegroup>` class, setting + ``PACKAGEGROUP_DISABLE_COMPLEMENTARY`` to "1" specifies that the + normal complementary packages (i.e. ``-dev``, ``-dbg``, and so forth) + should not be automatically created by the ``packagegroup`` recipe, + which is the default behavior. + + PACKAGES + The list of packages the recipe creates. The default value is the + following: + :: + + ${PN}-dbg ${PN}-staticdev ${PN}-dev ${PN}-doc ${PN}-locale ${PACKAGE_BEFORE_PN} ${PN} + + During packaging, the :ref:`ref-tasks-package` task + goes through ``PACKAGES`` and uses the :term:`FILES` + variable corresponding to each package to assign files to the + package. If a file matches the ``FILES`` variable for more than one + package in ``PACKAGES``, it will be assigned to the earliest + (leftmost) package. + + Packages in the variable's list that are empty (i.e. where none of + the patterns in ``FILES_``\ pkg match any files installed by the + :ref:`ref-tasks-install` task) are not generated, + unless generation is forced through the + :term:`ALLOW_EMPTY` variable. + + PACKAGES_DYNAMIC + A promise that your recipe satisfies runtime dependencies for + optional modules that are found in other recipes. + ``PACKAGES_DYNAMIC`` does not actually satisfy the dependencies, it + only states that they should be satisfied. For example, if a hard, + runtime dependency (:term:`RDEPENDS`) of another + package is satisfied at build time through the ``PACKAGES_DYNAMIC`` + variable, but a package with the module name is never actually + produced, then the other package will be broken. Thus, if you attempt + to include that package in an image, you will get a dependency + failure from the packaging system during the + :ref:`ref-tasks-rootfs` task. + + Typically, if there is a chance that such a situation can occur and + the package that is not created is valid without the dependency being + satisfied, then you should use :term:`RRECOMMENDS` + (a soft runtime dependency) instead of ``RDEPENDS``. + + For an example of how to use the ``PACKAGES_DYNAMIC`` variable when + you are splitting packages, see the + ":ref:`dev-manual/dev-manual-common-tasks:handling optional module packaging`" + section in the Yocto Project Development Tasks Manual. + + PACKAGESPLITFUNCS + Specifies a list of functions run to perform additional splitting of + files into individual packages. Recipes can either prepend to this + variable or prepend to the ``populate_packages`` function in order to + perform additional package splitting. In either case, the function + should set :term:`PACKAGES`, + :term:`FILES`, :term:`RDEPENDS` and + other packaging variables appropriately in order to perform the + desired splitting. + + PARALLEL_MAKE + Extra options passed to the ``make`` command during the + :ref:`ref-tasks-compile` task in order to specify + parallel compilation on the local build host. This variable is + usually in the form "-j x", where x represents the maximum number of + parallel threads ``make`` can run. + + .. note:: + + In order for + PARALLEL_MAKE + to be effective, + make + must be called with + ${ + EXTRA_OEMAKE + } + . An easy way to ensure this is to use the + oe_runmake + function. + + By default, the OpenEmbedded build system automatically sets this + variable to be equal to the number of cores the build system uses. + + .. note:: + + If the software being built experiences dependency issues during + the + do_compile + task that result in race conditions, you can clear the + PARALLEL_MAKE + variable within the recipe as a workaround. For information on + addressing race conditions, see the " + Debugging Parallel Make Races + " section in the Yocto Project Development Tasks Manual. + + For single socket systems (i.e. one CPU), you should not have to + override this variable to gain optimal parallelism during builds. + However, if you have very large systems that employ multiple physical + CPUs, you might want to make sure the ``PARALLEL_MAKE`` variable is + not set higher than "-j 20". + + For more information on speeding up builds, see the + ":ref:`dev-manual/dev-manual-common-tasks:speeding up a build`" + section in the Yocto Project Development Tasks Manual. + + PARALLEL_MAKEINST + Extra options passed to the ``make install`` command during the + :ref:`ref-tasks-install` task in order to specify + parallel installation. This variable defaults to the value of + :term:`PARALLEL_MAKE`. + + .. note:: + + In order for ``PARALLEL_MAKEINST`` to be effective, ``make`` must + be called with + ``${``\ :term:`EXTRA_OEMAKE`\ ``}``. An easy + way to ensure this is to use the ``oe_runmake`` function. + + If the software being built experiences dependency issues during + the ``do_install`` task that result in race conditions, you can + clear the ``PARALLEL_MAKEINST`` variable within the recipe as a + workaround. For information on addressing race conditions, see the + ":ref:`dev-manual/dev-manual-common-tasks:debugging parallel make races`" + section in the Yocto Project Development Tasks Manual. + + PATCHRESOLVE + Determines the action to take when a patch fails. You can set this + variable to one of two values: "noop" and "user". + + The default value of "noop" causes the build to simply fail when the + OpenEmbedded build system cannot successfully apply a patch. Setting + the value to "user" causes the build system to launch a shell and + places you in the right location so that you can manually resolve the + conflicts. + + Set this variable in your ``local.conf`` file. + + PATCHTOOL + Specifies the utility used to apply patches for a recipe during the + :ref:`ref-tasks-patch` task. You can specify one of + three utilities: "patch", "quilt", or "git". The default utility used + is "quilt" except for the quilt-native recipe itself. Because the + quilt tool is not available at the time quilt-native is being + patched, it uses "patch". + + If you wish to use an alternative patching tool, set the variable in + the recipe using one of the following: + :: + + PATCHTOOL = "patch" + PATCHTOOL = "quilt" + PATCHTOOL = "git" + + PE + The epoch of the recipe. By default, this variable is unset. The + variable is used to make upgrades possible when the versioning scheme + changes in some backwards incompatible way. + + ``PE`` is the default value of the :term:`PKGE` variable. + + PF + Specifies the recipe or package name and includes all version and + revision numbers (i.e. ``glibc-2.13-r20+svnr15508/`` and + ``bash-4.2-r1/``). This variable is comprised of the following: + ${:term:`PN`}-${:term:`EXTENDPE`}${:term:`PV`}-${:term:`PR`} + + PIXBUF_PACKAGES + When inheriting the :ref:`pixbufcache <ref-classes-pixbufcache>` + class, this variable identifies packages that contain the pixbuf + loaders used with ``gdk-pixbuf``. By default, the ``pixbufcache`` + class assumes that the loaders are in the recipe's main package (i.e. + ``${``\ :term:`PN`\ ``}``). Use this variable if the + loaders you need are in a package other than that main package. + + PKG + The name of the resulting package created by the OpenEmbedded build + system. + + .. note:: + + When using the + PKG + variable, you must use a package name override. + + For example, when the :ref:`debian <ref-classes-debian>` class + renames the output package, it does so by setting + ``PKG_packagename``. + + PKG_CONFIG_PATH + The path to ``pkg-config`` files for the current build context. + ``pkg-config`` reads this variable from the environment. + + PKGD + Points to the destination directory for files to be packaged before + they are split into individual packages. This directory defaults to + the following: + :: + + ${WORKDIR}/package + + Do not change this default. + + PKGDATA_DIR + Points to a shared, global-state directory that holds data generated + during the packaging process. During the packaging process, the + :ref:`ref-tasks-packagedata` task packages data + for each recipe and installs it into this temporary, shared area. + This directory defaults to the following, which you should not + change: + :: + + ${STAGING_DIR_HOST}/pkgdata + + For examples of how this data is used, see the + ":ref:`overview-manual/overview-manual-concepts:automatically added runtime dependencies`" + section in the Yocto Project Overview and Concepts Manual and the + ":ref:`dev-manual/dev-manual-common-tasks:viewing package information with \`\`oe-pkgdata-util\`\``" + section in the Yocto Project Development Tasks Manual. For more + information on the shared, global-state directory, see + :term:`STAGING_DIR_HOST`. + + PKGDEST + Points to the parent directory for files to be packaged after they + have been split into individual packages. This directory defaults to + the following: + :: + + ${WORKDIR}/packages-split + + Under this directory, the build system creates directories for each + package specified in :term:`PACKAGES`. Do not change + this default. + + PKGDESTWORK + Points to a temporary work area where the + :ref:`ref-tasks-package` task saves package metadata. + The ``PKGDESTWORK`` location defaults to the following: + :: + + ${WORKDIR}/pkgdata + + Do not change this default. + + The :ref:`ref-tasks-packagedata` task copies the + package metadata from ``PKGDESTWORK`` to + :term:`PKGDATA_DIR` to make it available globally. + + PKGE + The epoch of the package(s) built by the recipe. By default, ``PKGE`` + is set to :term:`PE`. + + PKGR + The revision of the package(s) built by the recipe. By default, + ``PKGR`` is set to :term:`PR`. + + PKGV + The version of the package(s) built by the recipe. By default, + ``PKGV`` is set to :term:`PV`. + + PN + This variable can have two separate functions depending on the + context: a recipe name or a resulting package name. + + ``PN`` refers to a recipe name in the context of a file used by the + OpenEmbedded build system as input to create a package. The name is + normally extracted from the recipe file name. For example, if the + recipe is named ``expat_2.0.1.bb``, then the default value of ``PN`` + will be "expat". + + The variable refers to a package name in the context of a file + created or produced by the OpenEmbedded build system. + + If applicable, the ``PN`` variable also contains any special suffix + or prefix. For example, using ``bash`` to build packages for the + native machine, ``PN`` is ``bash-native``. Using ``bash`` to build + packages for the target and for Multilib, ``PN`` would be ``bash`` + and ``lib64-bash``, respectively. + + PNBLACKLIST + Lists recipes you do not want the OpenEmbedded build system to build. + This variable works in conjunction with the + :ref:`blacklist <ref-classes-blacklist>` class, which is inherited + globally. + + To prevent a recipe from being built, use the ``PNBLACKLIST`` + variable in your ``local.conf`` file. Here is an example that + prevents ``myrecipe`` from being built: + :: + + PNBLACKLIST[myrecipe] = "Not supported by our organization." + + POPULATE_SDK_POST_HOST_COMMAND + Specifies a list of functions to call once the OpenEmbedded build + system has created the host part of the SDK. You can specify + functions separated by semicolons: + :: + + POPULATE_SDK_POST_HOST_COMMAND += "function; ... " + + If you need to pass the SDK path to a command within a function, you + can use ``${SDK_DIR}``, which points to the parent directory used by + the OpenEmbedded build system when creating SDK output. See the + :term:`SDK_DIR` variable for more information. + + POPULATE_SDK_POST_TARGET_COMMAND + Specifies a list of functions to call once the OpenEmbedded build + system has created the target part of the SDK. You can specify + functions separated by semicolons: + :: + + POPULATE_SDK_POST_TARGET_COMMAND += "function; ... " + + If you need to pass the SDK path to a command within a function, you + can use ``${SDK_DIR}``, which points to the parent directory used by + the OpenEmbedded build system when creating SDK output. See the + :term:`SDK_DIR` variable for more information. + + PR + The revision of the recipe. The default value for this variable is + "r0". Subsequent revisions of the recipe conventionally have the + values "r1", "r2", and so forth. When :term:`PV` increases, + ``PR`` is conventionally reset to "r0". + + .. note:: + + The OpenEmbedded build system does not need the aid of + PR + to know when to rebuild a recipe. The build system uses the task + input checksums + along with the + stamp + and + shared state cache + mechanisms. + + The ``PR`` variable primarily becomes significant when a package + manager dynamically installs packages on an already built image. In + this case, ``PR``, which is the default value of + :term:`PKGR`, helps the package manager distinguish which + package is the most recent one in cases where many packages have the + same ``PV`` (i.e. ``PKGV``). A component having many packages with + the same ``PV`` usually means that the packages all install the same + upstream version, but with later (``PR``) version packages including + packaging fixes. + + .. note:: + + PR + does not need to be increased for changes that do not change the + package contents or metadata. + + Because manually managing ``PR`` can be cumbersome and error-prone, + an automated solution exists. See the + ":ref:`dev-manual/dev-manual-common-tasks:working with a pr service`" section + in the Yocto Project Development Tasks Manual for more information. + + PREFERRED_PROVIDER + If multiple recipes provide the same item, this variable determines + which recipe is preferred and thus provides the item (i.e. the + preferred provider). You should always suffix this variable with the + name of the provided item. And, you should define the variable using + the preferred recipe's name (:term:`PN`). Here is a common + example: + :: + + PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto" + + In the previous example, multiple recipes are providing "virtual/kernel". + The ``PREFERRED_PROVIDER`` variable is set with the name (``PN``) of + the recipe you prefer to provide "virtual/kernel". + + Following are more examples: + :: + + PREFERRED_PROVIDER_virtual/xserver = "xserver-xf86" + PREFERRED_PROVIDER_virtual/libgl ?= "mesa" + + For more + information, see the ":ref:`metadata-virtual-providers`" + section in the Yocto Project Development Tasks Manual. + + .. note:: + + If you use a + virtual/\* + item with + PREFERRED_PROVIDER + , then any recipe that + PROVIDES + that item but is not selected (defined) by + PREFERRED_PROVIDER + is prevented from building, which is usually desirable since this + mechanism is designed to select between mutually exclusive + alternative providers. + + PREFERRED_VERSION + If multiple versions of recipes exist, this variable determines which + version is given preference. You must always suffix the variable with + the :term:`PN` you want to select, and you should set the + :term:`PV` accordingly for precedence. + + The ``PREFERRED_VERSION`` variable supports limited wildcard use + through the "``%``" character. You can use the character to match any + number of characters, which can be useful when specifying versions + that contain long revision numbers that potentially change. Here are + two examples: + :: + + PREFERRED_VERSION_python = "3.4.0" + PREFERRED_VERSION_linux-yocto = "5.0%" + + .. note:: + + The use of the "%" character is limited in that it only works at the end of the + string. You cannot use the wildcard character in any other + location of the string. + + The specified version is matched against :term:`PV`, which + does not necessarily match the version part of the recipe's filename. + For example, consider two recipes ``foo_1.2.bb`` and ``foo_git.bb`` + where ``foo_git.bb`` contains the following assignment: + :: + + PV = "1.1+git${SRCPV}" + + In this case, the correct way to select + ``foo_git.bb`` is by using an assignment such as the following: + :: + + PREFERRED_VERSION_foo = "1.1+git%" + + Compare that previous example + against the following incorrect example, which does not work: + :: + + PREFERRED_VERSION_foo = "git" + + Sometimes the ``PREFERRED_VERSION`` variable can be set by + configuration files in a way that is hard to change. You can use + :term:`OVERRIDES` to set a machine-specific + override. Here is an example: + :: + + PREFERRED_VERSION_linux-yocto_qemux86 = "5.0%" + + Although not recommended, worst case, you can also use the + "forcevariable" override, which is the strongest override possible. + Here is an example: + :: + + PREFERRED_VERSION_linux-yocto_forcevariable = "5.0%" + + .. note:: + + The \_forcevariable override is not handled specially. This override + only works because the default value of OVERRIDES includes "forcevariable". + + PREMIRRORS + Specifies additional paths from which the OpenEmbedded build system + gets source code. When the build system searches for source code, it + first tries the local download directory. If that location fails, the + build system tries locations defined by ``PREMIRRORS``, the upstream + source, and then locations specified by + :term:`MIRRORS` in that order. + + Assuming your distribution (:term:`DISTRO`) is "poky", + the default value for ``PREMIRRORS`` is defined in the + ``conf/distro/poky.conf`` file in the ``meta-poky`` Git repository. + + Typically, 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 in the + :term:`Build Directory`: + :: + + PREMIRRORS_prepend = "\ + git://.*/.* http://www.yoctoproject.org/sources/ \n \ + ftp://.*/.* http://www.yoctoproject.org/sources/ \n \ + http://.*/.* http://www.yoctoproject.org/sources/ \n \ + https://.*/.* http://www.yoctoproject.org/sources/ \n" + + 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. + + PRIORITY + Indicates the importance of a package. + + ``PRIORITY`` is considered to be part of the distribution policy + because the importance of any given recipe depends on the purpose for + which the distribution is being produced. Thus, ``PRIORITY`` is not + normally set within recipes. + + You can set ``PRIORITY`` to "required", "standard", "extra", and + "optional", which is the default. + + PRIVATE_LIBS + Specifies libraries installed within a recipe that should be ignored + by the OpenEmbedded build system's shared library resolver. This + variable is typically used when software being built by a recipe has + its own private versions of a library normally provided by another + recipe. In this case, you would not want the package containing the + private libraries to be set as a dependency on other unrelated + packages that should instead depend on the package providing the + standard version of the library. + + Libraries specified in this variable should be specified by their + file name. For example, from the Firefox recipe in meta-browser: + :: + + PRIVATE_LIBS = "libmozjs.so \ + libxpcom.so \ + libnspr4.so \ + libxul.so \ + libmozalloc.so \ + libplc4.so \ + libplds4.so" + + For more information, see the + ":ref:`overview-manual/overview-manual-concepts:automatically added runtime dependencies`" + section in the Yocto Project Overview and Concepts Manual. + + PROVIDES + A list of aliases by which a particular recipe can be known. By + default, a recipe's own ``PN`` is implicitly already in its + ``PROVIDES`` list and therefore does not need to mention that it + provides itself. If a recipe uses ``PROVIDES``, the additional + aliases are synonyms for the recipe and can be useful for satisfying + dependencies of other recipes during the build as specified by + ``DEPENDS``. + + Consider the following example ``PROVIDES`` statement from the recipe + file ``eudev_3.2.9.bb``: + :: + + PROVIDES = "udev" + + The ``PROVIDES`` statement + results in the "eudev" recipe also being available as simply "udev". + + .. note:: + + Given that a recipe's own recipe name is already implicitly in its + own + PROVIDES + list, it is unnecessary to add aliases with the "+=" operator; + using a simple assignment will be sufficient. In other words, + while you could write: + :: + + PROVIDES += "udev" + + + in the above, the "+=" is overkill and unnecessary. + + In addition to providing recipes under alternate names, the + ``PROVIDES`` mechanism is also used to implement virtual targets. A + virtual target is a name that corresponds to some particular + functionality (e.g. a Linux kernel). Recipes that provide the + functionality in question list the virtual target in ``PROVIDES``. + Recipes that depend on the functionality in question can include the + virtual target in ``DEPENDS`` to leave the choice of provider open. + + Conventionally, virtual targets have names on the form + "virtual/function" (e.g. "virtual/kernel"). The slash is simply part + of the name and has no syntactical significance. + + The :term:`PREFERRED_PROVIDER` variable is + used to select which particular recipe provides a virtual target. + + .. note:: + + A corresponding mechanism for virtual runtime dependencies + (packages) exists. However, the mechanism does not depend on any + special functionality beyond ordinary variable assignments. For + example, ``VIRTUAL-RUNTIME_dev_manager`` refers to the package of + the component that manages the ``/dev`` directory. + + Setting the "preferred provider" for runtime dependencies is as + simple as using the following assignment in a configuration file: + :: + + VIRTUAL-RUNTIME_dev_manager = "udev" + + + PRSERV_HOST + The network based :term:`PR` service host and port. + + The ``conf/local.conf.sample.extended`` configuration file in the + :term:`Source Directory` shows how the + ``PRSERV_HOST`` variable is set: + :: + + PRSERV_HOST = "localhost:0" + + You must + set the variable if you want to automatically start a local :ref:`PR + service <dev-manual/dev-manual-common-tasks:working with a pr service>`. You can + set ``PRSERV_HOST`` to other values to use a remote PR service. + + PTEST_ENABLED + Specifies whether or not :ref:`Package + Test <dev-manual/dev-manual-common-tasks:testing packages with ptest>` (ptest) + functionality is enabled when building a recipe. You should not set + this variable directly. Enabling and disabling building Package Tests + at build time should be done by adding "ptest" to (or removing it + from) :term:`DISTRO_FEATURES`. + + PV + The version of the recipe. The version is normally extracted from the + recipe filename. For example, if the recipe is named + ``expat_2.0.1.bb``, then the default value of ``PV`` will be "2.0.1". + ``PV`` is generally not overridden within a recipe unless it is + building an unstable (i.e. development) version from a source code + repository (e.g. Git or Subversion). + + ``PV`` is the default value of the :term:`PKGV` variable. + + PYTHON_ABI + When used by recipes that inherit the + :ref:`distutils3 <ref-classes-distutils3>`, + :ref:`setuptools3 <ref-classes-setuptools3>`, + :ref:`distutils <ref-classes-distutils>`, or + :ref:`setuptools <ref-classes-setuptools>` classes, denotes the + Application Binary Interface (ABI) currently in use for Python. By + default, the ABI is "m". You do not have to set this variable as the + OpenEmbedded build system sets it for you. + + The OpenEmbedded build system uses the ABI to construct directory + names used when installing the Python headers and libraries in + sysroot (e.g. ``.../python3.3m/...``). + + Recipes that inherit the ``distutils`` class during cross-builds also + use this variable to locate the headers and libraries of the + appropriate Python that the extension is targeting. + + PYTHON_PN + When used by recipes that inherit the + `distutils3 <ref-classes-distutils3>`, + :ref:`setuptools3 <ref-classes-setuptools3>`, + :ref:`distutils <ref-classes-distutils>`, or + :ref:`setuptools <ref-classes-setuptools>` classes, specifies the + major Python version being built. For Python 3.x, ``PYTHON_PN`` would + be "python3". You do not have to set this variable as the + OpenEmbedded build system automatically sets it for you. + + The variable allows recipes to use common infrastructure such as the + following: + :: + + DEPENDS += "${PYTHON_PN}-native" + + In the previous example, + the version of the dependency is ``PYTHON_PN``. + + RANLIB + The minimal command and arguments to run ``ranlib``. + + RCONFLICTS + The list of packages that conflict with packages. Note that packages + will not be installed if conflicting packages are not first removed. + + Like all package-controlling variables, you must always use them in + conjunction with a package name override. Here is an example: + :: + + RCONFLICTS_${PN} = "another_conflicting_package_name" + + BitBake, which the OpenEmbedded build system uses, supports + specifying versioned dependencies. Although the syntax varies + depending on the packaging format, BitBake hides these differences + from you. Here is the general syntax to specify versions with the + ``RCONFLICTS`` variable: + :: + + RCONFLICTS_${PN} = "package (operator version)" + + For ``operator``, you can specify the following: = < > <= + >= For example, the following sets up a dependency on version 1.2 or + greater of the package ``foo``: + :: + + RCONFLICTS_${PN} = "foo (>= 1.2)" + + RDEPENDS + Lists runtime dependencies of a package. These dependencies are other + packages that must be installed in order for the package to function + correctly. As an example, the following assignment declares that the + package ``foo`` needs the packages ``bar`` and ``baz`` to be + installed: + :: + + RDEPENDS_foo = "bar baz" + + The most common types of package + runtime dependencies are automatically detected and added. Therefore, + most recipes do not need to set ``RDEPENDS``. For more information, + see the + ":ref:`overview-manual/overview-manual-concepts:automatically added runtime dependencies`" + section in the Yocto Project Overview and Concepts Manual. + + The practical effect of the above ``RDEPENDS`` assignment is that + ``bar`` and ``baz`` will be declared as dependencies inside the + package ``foo`` when it is written out by one of the + ```do_package_write_*`` <#ref-tasks-package_write_deb>`__ tasks. + Exactly how this is done depends on which package format is used, + which is determined by + :term:`PACKAGE_CLASSES`. When the + corresponding package manager installs the package, it will know to + also install the packages on which it depends. + + To ensure that the packages ``bar`` and ``baz`` get built, the + previous ``RDEPENDS`` assignment also causes a task dependency to be + added. This dependency is from the recipe's + :ref:`ref-tasks-build` (not to be confused with + :ref:`ref-tasks-compile`) task to the + ``do_package_write_*`` task of the recipes that build ``bar`` and + ``baz``. + + The names of the packages you list within ``RDEPENDS`` must be the + names of other packages - they cannot be recipe names. Although + package names and recipe names usually match, the important point + here is that you are providing package names within the ``RDEPENDS`` + variable. For an example of the default list of packages created from + a recipe, see the :term:`PACKAGES` variable. + + Because the ``RDEPENDS`` variable applies to packages being built, + you should always use the variable in a form with an attached package + name (remember that a single recipe can build multiple packages). For + example, suppose you are building a development package that depends + on the ``perl`` package. In this case, you would use the following + ``RDEPENDS`` statement: + :: + + RDEPENDS_${PN}-dev += "perl" + + In the example, + the development package depends on the ``perl`` package. Thus, the + ``RDEPENDS`` variable has the ``${PN}-dev`` package name as part of + the variable. + + .. note:: + + RDEPENDS_${PN}-dev + includes + ${ + PN + } + by default. This default is set in the BitBake configuration file + ( + meta/conf/bitbake.conf + ). Be careful not to accidentally remove + ${PN} + when modifying + RDEPENDS_${PN}-dev + . Use the "+=" operator rather than the "=" operator. + + The package names you use with ``RDEPENDS`` must appear as they would + in the ``PACKAGES`` variable. The :term:`PKG` variable + allows a different name to be used for the final package (e.g. the + :ref:`debian <ref-classes-debian>` class uses this to rename + packages), but this final package name cannot be used with + ``RDEPENDS``, which makes sense as ``RDEPENDS`` is meant to be + independent of the package format used. + + BitBake, which the OpenEmbedded build system uses, supports + specifying versioned dependencies. Although the syntax varies + depending on the packaging format, BitBake hides these differences + from you. Here is the general syntax to specify versions with the + ``RDEPENDS`` variable: + :: + + RDEPENDS_${PN} = "package (operator version)" + + For operator, you can specify the following: = < > <= >= For version, + provide the version number. + + .. note:: + + You can use + EXTENDPKGV + to provide a full package version specification. + + For example, the following sets up a dependency on version 1.2 or + greater of the package ``foo``: + :: + + RDEPENDS_${PN} = "foo (>= 1.2)" + + For information on build-time dependencies, see the + :term:`DEPENDS` variable. You can also see the + ":ref:`Tasks <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:tasks>`" and + ":ref:`Dependencies <bitbake:bitbake-user-manual/bitbake-user-manual-execution:dependencies>`" sections in the + BitBake User Manual for additional information on tasks and + dependencies. + + REQUIRED_DISTRO_FEATURES + When inheriting the + :ref:`distro_features_check <ref-classes-distro_features_check>` + class, this variable identifies distribution features that must exist + in the current configuration in order for the OpenEmbedded build + system to build the recipe. In other words, if the + ``REQUIRED_DISTRO_FEATURES`` variable lists a feature that does not + appear in ``DISTRO_FEATURES`` within the current configuration, an + error occurs and the build stops. + + RM_WORK_EXCLUDE + With ``rm_work`` enabled, this variable specifies a list of recipes + whose work directories should not be removed. See the + ":ref:`rm_work.bbclass <ref-classes-rm-work>`" section for more + details. + + ROOT_HOME + Defines the root home directory. By default, this directory is set as + follows in the BitBake configuration file: + :: + + ROOT_HOME ??= "/home/root" + + .. note:: + + This default value is likely used because some embedded solutions + prefer to have a read-only root filesystem and prefer to keep + writeable data in one place. + + You can override the default by setting the variable in any layer or + in the ``local.conf`` file. Because the default is set using a "weak" + assignment (i.e. "??="), you can use either of the following forms to + define your override: + :: + + ROOT_HOME = "/root" + ROOT_HOME ?= "/root" + + These + override examples use ``/root``, which is probably the most commonly + used override. + + ROOTFS + Indicates a filesystem image to include as the root filesystem. + + The ``ROOTFS`` variable is an optional variable used with the + :ref:`image-live <ref-classes-image-live>` class. + + ROOTFS_POSTINSTALL_COMMAND + Specifies a list of functions to call after the OpenEmbedded build + system has installed packages. You can specify functions separated by + semicolons: + :: + + ROOTFS_POSTINSTALL_COMMAND += "function; ... " + + If you need to pass the root filesystem path to a command within a + function, you can use ``${IMAGE_ROOTFS}``, which points to the + directory that becomes the root filesystem image. See the + :term:`IMAGE_ROOTFS` variable for more + information. + + ROOTFS_POSTPROCESS_COMMAND + Specifies a list of functions to call once the OpenEmbedded build + system has created the root filesystem. You can specify functions + separated by semicolons: + :: + + ROOTFS_POSTPROCESS_COMMAND += "function; ... " + + If you need to pass the root filesystem path to a command within a + function, you can use ``${IMAGE_ROOTFS}``, which points to the + directory that becomes the root filesystem image. See the + :term:`IMAGE_ROOTFS` variable for more + information. + + ROOTFS_POSTUNINSTALL_COMMAND + Specifies a list of functions to call after the OpenEmbedded build + system has removed unnecessary packages. When runtime package + management is disabled in the image, several packages are removed + including ``base-passwd``, ``shadow``, and ``update-alternatives``. + You can specify functions separated by semicolons: + :: + + ROOTFS_POSTUNINSTALL_COMMAND += "function; ... " + + If you need to pass the root filesystem path to a command within a + function, you can use ``${IMAGE_ROOTFS}``, which points to the + directory that becomes the root filesystem image. See the + :term:`IMAGE_ROOTFS` variable for more + information. + + ROOTFS_PREPROCESS_COMMAND + Specifies a list of functions to call before the OpenEmbedded build + system has created the root filesystem. You can specify functions + separated by semicolons: + :: + + ROOTFS_PREPROCESS_COMMAND += "function; ... " + + If you need to pass the root filesystem path to a command within a + function, you can use ``${IMAGE_ROOTFS}``, which points to the + directory that becomes the root filesystem image. See the + :term:`IMAGE_ROOTFS` variable for more + information. + + RPROVIDES + A list of package name aliases that a package also provides. These + aliases are useful for satisfying runtime dependencies of other + packages both during the build and on the target (as specified by + ``RDEPENDS``). + + .. note:: + + A package's own name is implicitly already in its + RPROVIDES + list. + + As with all package-controlling variables, you must always use the + variable in conjunction with a package name override. Here is an + example: + :: + + RPROVIDES_${PN} = "widget-abi-2" + + RRECOMMENDS + A list of packages that extends the usability of a package being + built. The package being built does not depend on this list of + packages in order to successfully build, but rather uses them for + extended usability. To specify runtime dependencies for packages, see + the ``RDEPENDS`` variable. + + The package manager will automatically install the ``RRECOMMENDS`` + list of packages when installing the built package. However, you can + prevent listed packages from being installed by using the + :term:`BAD_RECOMMENDATIONS`, + :term:`NO_RECOMMENDATIONS`, and + :term:`PACKAGE_EXCLUDE` variables. + + Packages specified in ``RRECOMMENDS`` need not actually be produced. + However, a recipe must exist that provides each package, either + through the :term:`PACKAGES` or + :term:`PACKAGES_DYNAMIC` variables or the + :term:`RPROVIDES` variable, or an error will occur + during the build. If such a recipe does exist and the package is not + produced, the build continues without error. + + Because the ``RRECOMMENDS`` variable applies to packages being built, + you should always attach an override to the variable to specify the + particular package whose usability is being extended. For example, + suppose you are building a development package that is extended to + support wireless functionality. In this case, you would use the + following: + :: + + RRECOMMENDS_${PN}-dev += "wireless_package_name" + + In the + example, the package name (``${PN}-dev``) must appear as it would in + the ``PACKAGES`` namespace before any renaming of the output package + by classes such as ``debian.bbclass``. + + BitBake, which the OpenEmbedded build system uses, supports + specifying versioned recommends. Although the syntax varies depending + on the packaging format, BitBake hides these differences from you. + Here is the general syntax to specify versions with the + ``RRECOMMENDS`` variable: + :: + + RRECOMMENDS_${PN} = "package (operator version)" + + For ``operator``, you can specify the following: + + - = + - < + - > + - <= + - >= + + For example, the following sets up a recommend on version 1.2 or + greater of the package ``foo``: + :: + + RRECOMMENDS_${PN} = "foo (>= 1.2)" + + RREPLACES + A list of packages replaced by a package. The package manager uses + this variable to determine which package should be installed to + replace other package(s) during an upgrade. In order to also have the + other package(s) removed at the same time, you must add the name of + the other package to the ``RCONFLICTS`` variable. + + As with all package-controlling variables, you must use this variable + in conjunction with a package name override. Here is an example: + :: + + RREPLACES_${PN} = "other_package_being_replaced" + + BitBake, which the OpenEmbedded build system uses, supports + specifying versioned replacements. Although the syntax varies + depending on the packaging format, BitBake hides these differences + from you. Here is the general syntax to specify versions with the + ``RREPLACES`` variable: + :: + + RREPLACES_${PN} = "package (operator version)" + + For ``operator``, you can specify the following: + + - = + - < + - > + - <= + - >= + + For example, the following sets up a replacement using version 1.2 + or greater of the package ``foo``: + :: + + RREPLACES_${PN} = "foo (>= 1.2)" + + RSUGGESTS + A list of additional packages that you can suggest for installation + by the package manager at the time a package is installed. Not all + package managers support this functionality. + + As with all package-controlling variables, you must always use this + variable in conjunction with a package name override. Here is an + example: + :: + + RSUGGESTS_${PN} = "useful_package another_package" + + S + The location in the :term:`Build Directory` where + unpacked recipe source code resides. By default, this directory is + ``${``\ :term:`WORKDIR`\ ``}/${``\ :term:`BPN`\ ``}-${``\ :term:`PV`\ ``}``, + where ``${BPN}`` is the base recipe name and ``${PV}`` is the recipe + version. If the source tarball extracts the code to a directory named + anything other than ``${BPN}-${PV}``, or if the source code is + fetched from an SCM such as Git or Subversion, then you must set + ``S`` in the recipe so that the OpenEmbedded build system knows where + to find the unpacked source. + + As an example, assume a :term:`Source Directory` + top-level folder named ``poky`` and a default Build Directory at + ``poky/build``. In this case, the work directory the build system + uses to keep the unpacked recipe for ``db`` is the following: + :: + + poky/build/tmp/work/qemux86-poky-linux/db/5.1.19-r3/db-5.1.19 + + The unpacked source code resides in the ``db-5.1.19`` folder. + + This next example assumes a Git repository. By default, Git + repositories are cloned to ``${WORKDIR}/git`` during + :ref:`ref-tasks-fetch`. Since this path is different + from the default value of ``S``, you must set it specifically so the + source can be located: + :: + + SRC_URI = "git://path/to/repo.git" + S = "${WORKDIR}/git" + + SANITY_REQUIRED_UTILITIES + Specifies a list of command-line utilities that should be checked for + during the initial sanity checking process when running BitBake. If + any of the utilities are not installed on the build host, then + BitBake immediately exits with an error. + + SANITY_TESTED_DISTROS + A list of the host distribution identifiers that the build system has + been tested against. Identifiers consist of the host distributor ID + followed by the release, as reported by the ``lsb_release`` tool or + as read from ``/etc/lsb-release``. Separate the list items with + explicit newline characters (``\n``). If ``SANITY_TESTED_DISTROS`` is + not empty and the current value of + :term:`NATIVELSBSTRING` does not appear in the + list, then the build system reports a warning that indicates the + current host distribution has not been tested as a build host. + + SDK_ARCH + The target architecture for the SDK. Typically, you do not directly + set this variable. Instead, use :term:`SDKMACHINE`. + + SDK_DEPLOY + The directory set up and used by the + :ref:`populate_sdk_base <ref-classes-populate-sdk>` class to which + the SDK is deployed. The ``populate_sdk_base`` class defines + ``SDK_DEPLOY`` as follows: + :: + + SDK_DEPLOY = "${TMPDIR}/deploy/sdk" + + SDK_DIR + The parent directory used by the OpenEmbedded build system when + creating SDK output. The + :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class defines + the variable as follows: + :: + + SDK_DIR = "${WORKDIR}/sdk" + + .. note:: + + The + SDK_DIR + directory is a temporary directory as it is part of + WORKDIR + . The final output directory is + SDK_DEPLOY + . + + SDK_EXT_TYPE + Controls whether or not shared state artifacts are copied into the + extensible SDK. The default value of "full" copies all of the + required shared state artifacts into the extensible SDK. The value + "minimal" leaves these artifacts out of the SDK. + + .. note:: + + If you set the variable to "minimal", you need to ensure + SSTATE_MIRRORS + is set in the SDK's configuration to enable the artifacts to be + fetched as needed. + + SDK_HOST_MANIFEST + The manifest file for the host part of the SDK. This file lists all + the installed packages that make up the host part of the SDK. The + file contains package information on a line-per-package basis as + follows: + :: + + packagename packagearch version + + The :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class + defines the manifest file as follows: + :: + + SDK_HOST_MANIFEST = "${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.host.manifest" + + The location is derived using the :term:`SDK_DEPLOY` and + :term:`TOOLCHAIN_OUTPUTNAME` variables. + + SDK_INCLUDE_PKGDATA + When set to "1", specifies to include the packagedata for all recipes + in the "world" target in the extensible SDK. Including this data + allows the ``devtool search`` command to find these recipes in search + results, as well as allows the ``devtool add`` command to map + dependencies more effectively. + + .. note:: + + Enabling the + SDK_INCLUDE_PKGDATA + variable significantly increases build time because all of world + needs to be built. Enabling the variable also slightly increases + the size of the extensible SDK. + + SDK_INCLUDE_TOOLCHAIN + When set to "1", specifies to include the toolchain in the extensible + SDK. Including the toolchain is useful particularly when + :term:`SDK_EXT_TYPE` is set to "minimal" to keep + the SDK reasonably small but you still want to provide a usable + toolchain. For example, suppose you want to use the toolchain from an + IDE or from other tools and you do not want to perform additional + steps to install the toolchain. + + The ``SDK_INCLUDE_TOOLCHAIN`` variable defaults to "0" if + ``SDK_EXT_TYPE`` is set to "minimal", and defaults to "1" if + ``SDK_EXT_TYPE`` is set to "full". + + SDK_INHERIT_BLACKLIST + A list of classes to remove from the :term:`INHERIT` + value globally within the extensible SDK configuration. The + :ref:`populate-sdk-ext <ref-classes-populate-sdk-*>` class sets the + default value: + :: + + SDK_INHERIT_BLACKLIST ?= "buildhistory icecc" + + Some classes are not generally applicable within the extensible SDK + context. You can use this variable to disable those classes. + + For additional information on how to customize the extensible SDK's + configuration, see the + ":ref:`sdk-manual/sdk-appendix-customizing:configuring the extensible sdk`" + section in the Yocto Project Application Development and the + Extensible Software Development Kit (eSDK) manual. + + SDK_LOCAL_CONF_BLACKLIST + A list of variables not allowed through from the OpenEmbedded build + system configuration into the extensible SDK configuration. Usually, + these are variables that are specific to the machine on which the + build system is running and thus would be potentially problematic + within the extensible SDK. + + By default, ``SDK_LOCAL_CONF_BLACKLIST`` is set in the + :ref:`populate-sdk-ext <ref-classes-populate-sdk-*>` class and + excludes the following variables: + + - :term:`CONF_VERSION` + - :term:`BB_NUMBER_THREADS` + - :term:`bitbake:BB_NUMBER_PARSE_THREADS` + - :term:`PARALLEL_MAKE` + - :term:`PRSERV_HOST` + - :term:`SSTATE_MIRRORS` :term:`DL_DIR` + - :term:`SSTATE_DIR` :term:`TMPDIR` + - :term:`BB_SERVER_TIMEOUT` + + For additional information on how to customize the extensible SDK's + configuration, see the + ":ref:`sdk-manual/sdk-appendix-customizing:configuring the extensible sdk`" + section in the Yocto Project Application Development and the + Extensible Software Development Kit (eSDK) manual. + + SDK_LOCAL_CONF_WHITELIST + A list of variables allowed through from the OpenEmbedded build + system configuration into the extensible SDK configuration. By + default, the list of variables is empty and is set in the + :ref:`populate-sdk-ext <ref-classes-populate-sdk-*>` class. + + This list overrides the variables specified using the + :term:`SDK_LOCAL_CONF_BLACKLIST` + variable as well as any variables identified by automatic + blacklisting due to the "/" character being found at the start of the + value, which is usually indicative of being a path and thus might not + be valid on the system where the SDK is installed. + + For additional information on how to customize the extensible SDK's + configuration, see the + ":ref:`sdk-manual/sdk-appendix-customizing:configuring the extensible sdk`" + section in the Yocto Project Application Development and the + Extensible Software Development Kit (eSDK) manual. + + SDK_NAME + The base name for SDK output files. The name is derived from the + :term:`DISTRO`, :term:`TCLIBC`, + :term:`SDK_ARCH`, + :term:`IMAGE_BASENAME`, and + :term:`TUNE_PKGARCH` variables: + :: + + SDK_NAME = "${DISTRO}-${TCLIBC}-${SDK_ARCH}-${IMAGE_BASENAME}-${TUNE_PKGARCH}" + + SDK_OS + Specifies the operating system for which the SDK will be built. The + default value is the value of :term:`BUILD_OS`. + + SDK_OUTPUT + The location used by the OpenEmbedded build system when creating SDK + output. The :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` + class defines the variable as follows: + :: + + SDK_DIR = "${WORKDIR}/sdk" + SDK_OUTPUT = "${SDK_DIR}/image" + SDK_DEPLOY = "${DEPLOY_DIR}/sdk" + + .. note:: + + The SDK_OUTPUT directory is a temporary directory as it is part of + WORKDIR by way of SDK_DIR. The final output directory is + SDK_DEPLOY. + + SDK_PACKAGE_ARCHS + Specifies a list of architectures compatible with the SDK machine. + This variable is set automatically and should not normally be + hand-edited. Entries are separated using spaces and listed in order + of priority. The default value for ``SDK_PACKAGE_ARCHS`` is "all any + noarch ${SDK_ARCH}-${SDKPKGSUFFIX}". + + SDK_POSTPROCESS_COMMAND + Specifies a list of functions to call once the OpenEmbedded build + system creates the SDK. You can specify functions separated by + semicolons: SDK_POSTPROCESS_COMMAND += "function; ... " + + If you need to pass an SDK path to a command within a function, you + can use ``${SDK_DIR}``, which points to the parent directory used by + the OpenEmbedded build system when creating SDK output. See the + :term:`SDK_DIR` variable for more information. + + SDK_PREFIX + The toolchain binary prefix used for ``nativesdk`` recipes. The + OpenEmbedded build system uses the ``SDK_PREFIX`` value to set the + :term:`TARGET_PREFIX` when building + ``nativesdk`` recipes. The default value is "${SDK_SYS}-". + + SDK_RECRDEP_TASKS + A list of shared state tasks added to the extensible SDK. By default, + the following tasks are added: + + - do_populate_lic + - do_package_qa + - do_populate_sysroot + - do_deploy + + Despite the default value of "" for the + ``SDK_RECRDEP_TASKS`` variable, the above four tasks are always added + to the SDK. To specify tasks beyond these four, you need to use the + ``SDK_RECRDEP_TASKS`` variable (e.g. you are defining additional + tasks that are needed in order to build + :term:`SDK_TARGETS`). + + SDK_SYS + Specifies the system, including the architecture and the operating + system, for which the SDK will be built. + + The OpenEmbedded build system automatically sets this variable based + on :term:`SDK_ARCH`, + :term:`SDK_VENDOR`, and + :term:`SDK_OS`. You do not need to set the ``SDK_SYS`` + variable yourself. + + SDK_TARGET_MANIFEST + The manifest file for the target part of the SDK. This file lists all + the installed packages that make up the target part of the SDK. The + file contains package information on a line-per-package basis as + follows: + :: + + packagename packagearch version + + The :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class + defines the manifest file as follows: + :: + + SDK_TARGET_MANIFEST = "${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.target.manifest" + + The location is derived using the :term:`SDK_DEPLOY` and + :term:`TOOLCHAIN_OUTPUTNAME` variables. + + SDK_TARGETS + A list of targets to install from shared state as part of the + standard or extensible SDK installation. The default value is "${PN}" + (i.e. the image from which the SDK is built). + + The ``SDK_TARGETS`` variable is an internal variable and typically + would not be changed. + + SDK_TITLE + The title to be printed when running the SDK installer. By default, + this title is based on the :term:`DISTRO_NAME` or + :term:`DISTRO` variable and is set in the + :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class as + follows: + :: + + SDK_TITLE ??= "${@d.getVar('DISTRO_NAME') or d.getVar('DISTRO')} SDK" + + For the default distribution "poky", + ``SDK_TITLE`` is set to "Poky (Yocto Project Reference Distro)". + + For information on how to change this default title, see the + ":ref:`sdk-manual/sdk-appendix-customizing:changing the extensible sdk installer title`" + section in the Yocto Project Application Development and the + Extensible Software Development Kit (eSDK) manual. + + SDK_UPDATE_URL + An optional URL for an update server for the extensible SDK. If set, + the value is used as the default update server when running + ``devtool sdk-update`` within the extensible SDK. + + SDK_VENDOR + Specifies the name of the SDK vendor. + + SDK_VERSION + Specifies the version of the SDK. The distribution configuration file + (e.g. ``/meta-poky/conf/distro/poky.conf``) defines the + ``SDK_VERSION`` as follows: + :: + + SDK_VERSION = "${@d.getVar('DISTRO_VERSION').replace('snapshot-${DATE}','snapshot')}" + + For additional information, see the + :term:`DISTRO_VERSION` and + :term:`DATE` variables. + + SDKEXTPATH + The default installation directory for the Extensible SDK. By + default, this directory is based on the :term:`DISTRO` + variable and is set in the + :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class as + follows: + :: + + SDKEXTPATH ??= "~/${@d.getVar('DISTRO')}_sdk" + + For the + default distribution "poky", the ``SDKEXTPATH`` is set to "poky_sdk". + + For information on how to change this default directory, see the + ":ref:`sdk-manual/sdk-appendix-customizing:changing the default sdk installation directory`" + section in the Yocto Project Application Development and the + Extensible Software Development Kit (eSDK) manual. + + SDKIMAGE_FEATURES + Equivalent to ``IMAGE_FEATURES``. However, this variable applies to + the SDK generated from an image using the following command: + :: + + $ bitbake -c populate_sdk imagename + + SDKMACHINE + The machine for which the SDK is built. In other words, the SDK is + built such that it runs on the target you specify with the + ``SDKMACHINE`` value. The value points to a corresponding ``.conf`` + file under ``conf/machine-sdk/``. + + You can use "i686" and "x86_64" as possible values for this variable. + The variable defaults to "i686" and is set in the local.conf file in + the Build Directory. + :: + + SDKMACHINE ?= "i686" + + .. note:: + + You cannot set the + SDKMACHINE + variable in your distribution configuration file. If you do, the + configuration will not take affect. + + SDKPATH + Defines the path offered to the user for installation of the SDK that + is generated by the OpenEmbedded build system. The path appears as + the default location for installing the SDK when you run the SDK's + installation script. You can override the offered path when you run + the script. + + SDKTARGETSYSROOT + The full path to the sysroot used for cross-compilation within an SDK + as it will be when installed into the default + :term:`SDKPATH`. + + SECTION + The section in which packages should be categorized. Package + management utilities can make use of this variable. + + SELECTED_OPTIMIZATION + Specifies the optimization flags passed to the C compiler when + building for the target. The flags are passed through the default + value of the :term:`TARGET_CFLAGS` variable. + + The ``SELECTED_OPTIMIZATION`` variable takes the value of + ``FULL_OPTIMIZATION`` unless ``DEBUG_BUILD`` = "1". If that is the + case, the value of ``DEBUG_OPTIMIZATION`` is used. + + SERIAL_CONSOLE + Defines a serial console (TTY) to enable using + `getty <https://en.wikipedia.org/wiki/Getty_(Unix)>`__. Provide a + value that specifies the baud rate followed by the TTY device name + separated by a space. You cannot specify more than one TTY device: + :: + + SERIAL_CONSOLE = "115200 ttyS0" + + .. note:: + + The + SERIAL_CONSOLE + variable is deprecated. Please use the + SERIAL_CONSOLES + variable. + + SERIAL_CONSOLES + Defines a serial console (TTY) to enable using + `getty <https://en.wikipedia.org/wiki/Getty_(Unix)>`__. Provide a + value that specifies the baud rate followed by the TTY device name + separated by a semicolon. Use spaces to separate multiple devices: + :: + + SERIAL_CONSOLES = "115200;ttyS0 115200;ttyS1" + + SERIAL_CONSOLES_CHECK + Specifies serial consoles, which must be listed in + :term:`SERIAL_CONSOLES`, to check against + ``/proc/console`` before enabling them using getty. This variable + allows aliasing in the format: <device>:<alias>. If a device was + listed as "sclp_line0" in ``/dev/`` and "ttyS0" was listed in + ``/proc/console``, you would do the following: :: + + SERIAL_CONSOLES_CHECK = "slcp_line0:ttyS0" + + This variable is currently only supported with SysVinit (i.e. not + with systemd). + + SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS + A list of recipe dependencies that should not be used to determine + signatures of tasks from one recipe when they depend on tasks from + another recipe. For example: :: + + SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS += "intone->mplayer2" + + In the previous example, ``intone`` depends on ``mplayer2``. + + You can use the special token ``"*"`` on the left-hand side of the + dependency to match all recipes except the one on the right-hand + side. Here is an example: :: + + SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS += "*->quilt-native" + + In the previous example, all recipes except ``quilt-native`` ignore + task signatures from the ``quilt-native`` recipe when determining + their task signatures. + + Use of this variable is one mechanism to remove dependencies that + affect task signatures and thus force rebuilds when a recipe changes. + + .. note:: + + If you add an inappropriate dependency for a recipe relationship, + the software might break during runtime if the interface of the + second recipe was changed after the first recipe had been built. + + SIGGEN_EXCLUDERECIPES_ABISAFE + A list of recipes that are completely stable and will never change. + The ABI for the recipes in the list are presented by output from the + tasks run to build the recipe. Use of this variable is one way to + remove dependencies from one recipe on another that affect task + signatures and thus force rebuilds when the recipe changes. + + .. note:: + + If you add an inappropriate variable to this list, the software + might break at runtime if the interface of the recipe was changed + after the other had been built. + + SITEINFO_BITS + Specifies the number of bits for the target system CPU. The value + should be either "32" or "64". + + SITEINFO_ENDIANNESS + Specifies the endian byte order of the target system. The value + should be either "le" for little-endian or "be" for big-endian. + + SKIP_FILEDEPS + Enables removal of all files from the "Provides" section of an RPM + package. Removal of these files is required for packages containing + prebuilt binaries and libraries such as ``libstdc++`` and ``glibc``. + + To enable file removal, set the variable to "1" in your + ``conf/local.conf`` configuration file in your: + :term:`Build Directory`. + :: + + SKIP_FILEDEPS = "1" + + SOC_FAMILY + Groups together machines based upon the same family of SOC (System On + Chip). You typically set this variable in a common ``.inc`` file that + you include in the configuration files of all the machines. + + .. note:: + + You must include + conf/machine/include/soc-family.inc + for this variable to appear in + MACHINEOVERRIDES + . + + SOLIBS + Defines the suffix for shared libraries used on the target platform. + By default, this suffix is ".so.*" for all Linux-based systems and is + defined in the ``meta/conf/bitbake.conf`` configuration file. + + You will see this variable referenced in the default values of + ``FILES_${PN}``. + + SOLIBSDEV + Defines the suffix for the development symbolic link (symlink) for + shared libraries on the target platform. By default, this suffix is + ".so" for Linux-based systems and is defined in the + ``meta/conf/bitbake.conf`` configuration file. + + You will see this variable referenced in the default values of + ``FILES_${PN}-dev``. + + SOURCE_MIRROR_FETCH + When you are fetching files to create a mirror of sources (i.e. + creating a source mirror), setting ``SOURCE_MIRROR_FETCH`` to "1" in + your ``local.conf`` configuration file ensures the source for all + recipes are fetched regardless of whether or not a recipe is + compatible with the configuration. A recipe is considered + incompatible with the currently configured machine when either or + both the :term:`COMPATIBLE_MACHINE` + variable and :term:`COMPATIBLE_HOST` variables + specify compatibility with a machine other than that of the current + machine or host. + + .. note:: + + Do not set the + SOURCE_MIRROR_FETCH + variable unless you are creating a source mirror. In other words, + do not set the variable during a normal build. + + SOURCE_MIRROR_URL + Defines your own :term:`PREMIRRORS` from which to + first fetch source before attempting to fetch from the upstream + specified in :term:`SRC_URI`. + + To use this variable, you must globally inherit the + :ref:`own-mirrors <ref-classes-own-mirrors>` class and then provide + the URL to your mirrors. Here is the general syntax: + :: + + INHERIT += "own-mirrors" + SOURCE_MIRROR_URL = "http://example.com/my_source_mirror" + + .. note:: + + You can specify only a single URL in + SOURCE_MIRROR_URL + . + + SPDXLICENSEMAP + Maps commonly used license names to their SPDX counterparts found in + ``meta/files/common-licenses/``. For the default ``SPDXLICENSEMAP`` + mappings, see the ``meta/conf/licenses.conf`` file. + + For additional information, see the :term:`LICENSE` + variable. + + SPECIAL_PKGSUFFIX + A list of prefixes for :term:`PN` used by the OpenEmbedded + build system to create variants of recipes or packages. The list + specifies the prefixes to strip off during certain circumstances such + as the generation of the :term:`BPN` variable. + + SPL_BINARY + The file type for the Secondary Program Loader (SPL). Some devices + use an SPL from which to boot (e.g. the BeagleBone development + board). For such cases, you can declare the file type of the SPL + binary in the ``u-boot.inc`` include file, which is used in the + U-Boot recipe. + + The SPL file type is set to "null" by default in the ``u-boot.inc`` + file as follows: + :: + + # Some versions of u-boot build an SPL (Second Program Loader) image that + # should be packaged along with the u-boot binary as well as placed in the + # deploy directory. For those versions they can set the following variables + # to allow packaging the SPL. + SPL_BINARY ?= "" + SPL_BINARYNAME ?= "${@os.path.basename(d.getVar("SPL_BINARY"))}" + SPL_IMAGE ?= "${SPL_BINARYNAME}-${MACHINE}-${PV}-${PR}" + SPL_SYMLINK ?= "${SPL_BINARYNAME}-${MACHINE}" + + The ``SPL_BINARY`` variable helps form + various ``SPL_*`` variables used by the OpenEmbedded build system. + + See the BeagleBone machine configuration example in the + ":ref:`dev-manual/dev-manual-common-tasks:adding a layer using the \`\`bitbake-layers\`\` script`" + section in the Yocto Project Board Support Package Developer's Guide + for additional information. + + SRC_URI + The list of source files - local or remote. This variable tells the + OpenEmbedded build system which bits to pull in for the build and how + to pull them in. For example, if the recipe or append file only needs + to fetch a tarball from the Internet, the recipe or append file uses + a single ``SRC_URI`` entry. On the other hand, if the recipe or + append file needs to fetch a tarball, apply two patches, and include + a custom file, the recipe or append file would include four instances + of the variable. + + The following list explains the available URI protocols. URI + protocols are highly dependent on particular BitBake Fetcher + submodules. Depending on the fetcher BitBake uses, various URL + parameters are employed. For specifics on the supported Fetchers, see + the ":ref:`Fetchers <bitbake:bb-fetchers>`" section in the + BitBake User Manual. + + - ``file://`` - Fetches files, which are usually files shipped + with the :term:`Metadata`, from the local machine (e.g. + :ref:`patch <patching-dev-environment>` files). + The path is relative to the :term:`FILESPATH` + variable. Thus, the build system searches, in order, from the + following directories, which are assumed to be a subdirectories of + the directory in which the recipe file (``.bb``) or append file + (``.bbappend``) resides: + + - ``${BPN}`` - The base recipe name without any special suffix + or version numbers. + + - ``${BP}`` - ``${BPN}-${PV}``. The base recipe name and + version but without any special package name suffix. + + - *files -* Files within a directory, which is named ``files`` + and is also alongside the recipe or append file. + + .. note:: + + If you want the build system to pick up files specified through + a + SRC_URI + statement from your append file, you need to be sure to extend + the + FILESPATH + variable by also using the + FILESEXTRAPATHS + variable from within your append file. + + - ``bzr://`` - Fetches files from a Bazaar revision control + repository. + + - ``git://`` - Fetches files from a Git revision control + repository. + + - ``osc://`` - Fetches files from an OSC (OpenSUSE Build service) + revision control repository. + + - ``repo://`` - Fetches files from a repo (Git) repository. + + - ``ccrc://`` - Fetches files from a ClearCase repository. + + - ``http://`` - Fetches files from the Internet using ``http``. + + - ``https://`` - Fetches files from the Internet using ``https``. + + - ``ftp://`` - Fetches files from the Internet using ``ftp``. + + - ``cvs://`` - Fetches files from a CVS revision control + repository. + + - ``hg://`` - Fetches files from a Mercurial (``hg``) revision + control repository. + + - ``p4://`` - Fetches files from a Perforce (``p4``) revision + control repository. + + - ``ssh://`` - Fetches files from a secure shell. + + - ``svn://`` - Fetches files from a Subversion (``svn``) revision + control repository. + + - ``npm://`` - Fetches JavaScript modules from a registry. + + Standard and recipe-specific options for ``SRC_URI`` exist. Here are + standard options: + + - ``apply`` - Whether to apply the patch or not. The default + action is to apply the patch. + + - ``striplevel`` - Which striplevel to use when applying the + patch. The default level is 1. + + - ``patchdir`` - Specifies the directory in which the patch should + be applied. The default is ``${``\ :term:`S`\ ``}``. + + Here are options specific to recipes building code from a revision + control system: + + - ``mindate`` - Apply the patch only if + :term:`SRCDATE` is equal to or greater than + ``mindate``. + + - ``maxdate`` - Apply the patch only if ``SRCDATE`` is not later + than ``maxdate``. + + - ``minrev`` - Apply the patch only if ``SRCREV`` is equal to or + greater than ``minrev``. + + - ``maxrev`` - Apply the patch only if ``SRCREV`` is not later + than ``maxrev``. + + - ``rev`` - Apply the patch only if ``SRCREV`` is equal to + ``rev``. + + - ``notrev`` - Apply the patch only if ``SRCREV`` is not equal to + ``rev``. + + Here are some additional options worth mentioning: + + - ``unpack`` - Controls whether or not to unpack the file if it is + an archive. The default action is to unpack the file. + + - ``destsuffix`` - Places the file (or extracts its contents) into + the specified subdirectory of :term:`WORKDIR` when + the Git fetcher is used. + + - ``subdir`` - Places the file (or extracts its contents) into the + specified subdirectory of ``WORKDIR`` when the local (``file://``) + fetcher is used. + + - ``localdir`` - Places the file (or extracts its contents) into + the specified subdirectory of ``WORKDIR`` when the CVS fetcher is + used. + + - ``subpath`` - Limits the checkout to a specific subpath of the + tree when using the Git fetcher is used. + + - ``name`` - Specifies a name to be used for association with + ``SRC_URI`` checksums when you have more than one file specified + in ``SRC_URI``. + + - ``downloadfilename`` - Specifies the filename used when storing + the downloaded file. + + SRC_URI_OVERRIDES_PACKAGE_ARCH + By default, the OpenEmbedded build system automatically detects + whether ``SRC_URI`` contains files that are machine-specific. If so, + the build system automatically changes ``PACKAGE_ARCH``. Setting this + variable to "0" disables this behavior. + + SRCDATE + The date of the source code used to build the package. This variable + applies only if the source was fetched from a Source Code Manager + (SCM). + + SRCPV + Returns the version string of the current package. This string is + used to help define the value of :term:`PV`. + + The ``SRCPV`` variable is defined in the ``meta/conf/bitbake.conf`` + configuration file in the :term:`Source Directory` as + follows: + :: + + SRCPV = "${@bb.fetch2.get_srcrev(d)}" + + Recipes that need to define ``PV`` do so with the help of the + ``SRCPV``. For example, the ``ofono`` recipe (``ofono_git.bb``) + located in ``meta/recipes-connectivity`` in the Source Directory + defines ``PV`` as follows: + :: + + PV = "0.12-git${SRCPV}" + + SRCREV + The revision of the source code used to build the package. This + variable applies to Subversion, Git, Mercurial, and Bazaar only. Note + that if you want to build a fixed revision and you want to avoid + performing a query on the remote repository every time BitBake parses + your recipe, you should specify a ``SRCREV`` that is a full revision + identifier and not just a tag. + + .. note:: + + For information on limitations when inheriting the latest revision + of software using + SRCREV + , see the + AUTOREV + variable description and the " + Automatically Incrementing a Binary Package Revision Number + " section, which is in the Yocto Project Development Tasks Manual. + + SSTATE_DIR + The directory for the shared state cache. + + SSTATE_MIRROR_ALLOW_NETWORK + If set to "1", allows fetches from mirrors that are specified in + :term:`SSTATE_MIRRORS` to work even when + fetching from the network is disabled by setting ``BB_NO_NETWORK`` to + "1". Using the ``SSTATE_MIRROR_ALLOW_NETWORK`` variable is useful if + you have set ``SSTATE_MIRRORS`` to point to an internal server for + your shared state cache, but you want to disable any other fetching + from the network. + + SSTATE_MIRRORS + Configures the OpenEmbedded build system to search other mirror + locations for prebuilt cache data objects before building out the + data. This variable works like fetcher :term:`MIRRORS` + and :term:`PREMIRRORS` and points to the cache + locations to check for the shared state (sstate) objects. + + You can specify a filesystem directory or a remote URL such as HTTP + or FTP. The locations you specify need to contain the shared state + cache (sstate-cache) results from previous builds. The sstate-cache + you point to can also be from builds on other machines. + + When pointing to sstate build artifacts on another machine that uses + a different GCC version for native builds, you must configure + ``SSTATE_MIRRORS`` with a regular expression that maps local search + paths to server paths. The paths need to take into account + :term:`NATIVELSBSTRING` set by the + :ref:`uninative <ref-classes-uninative>` class. For example, the + following maps the local search path ``universal-4.9`` to the + server-provided path server_url_sstate_path: + :: + + SSTATE_MIRRORS ?= "file://universal-4.9/(.*) http://server_url_sstate_path/universal-4.8/\1 \n" + + If a mirror uses the same structure as + :term:`SSTATE_DIR`, you need to add "PATH" at the + end as shown in the examples below. The build system substitutes the + correct path within the directory structure. + :: + + SSTATE_MIRRORS ?= "\ + file://.* http://someserver.tld/share/sstate/PATH;downloadfilename=PATH \n \ + file://.* file:///some-local-dir/sstate/PATH" + + SSTATE_SCAN_FILES + Controls the list of files the OpenEmbedded build system scans for + hardcoded installation paths. The variable uses a space-separated + list of filenames (not paths) with standard wildcard characters + allowed. + + During a build, the OpenEmbedded build system creates a shared state + (sstate) object during the first stage of preparing the sysroots. + That object is scanned for hardcoded paths for original installation + locations. The list of files that are scanned for paths is controlled + by the ``SSTATE_SCAN_FILES`` variable. Typically, recipes add files + they want to be scanned to the value of ``SSTATE_SCAN_FILES`` rather + than the variable being comprehensively set. The + :ref:`sstate <ref-classes-sstate>` class specifies the default list + of files. + + For details on the process, see the + :ref:`staging <ref-classes-staging>` class. + + STAGING_BASE_LIBDIR_NATIVE + Specifies the path to the ``/lib`` subdirectory of the sysroot + directory for the build host. + + STAGING_BASELIBDIR + Specifies the path to the ``/lib`` subdirectory of the sysroot + directory for the target for which the current recipe is being built + (:term:`STAGING_DIR_HOST`). + + STAGING_BINDIR + Specifies the path to the ``/usr/bin`` subdirectory of the sysroot + directory for the target for which the current recipe is being built + (:term:`STAGING_DIR_HOST`). + + STAGING_BINDIR_CROSS + Specifies the path to the directory containing binary configuration + scripts. These scripts provide configuration information for other + software that wants to make use of libraries or include files + provided by the software associated with the script. + + .. note:: + + This style of build configuration has been largely replaced by + pkg-config + . Consequently, if + pkg-config + is supported by the library to which you are linking, it is + recommended you use + pkg-config + instead of a provided configuration script. + + STAGING_BINDIR_NATIVE + Specifies the path to the ``/usr/bin`` subdirectory of the sysroot + directory for the build host. + + STAGING_DATADIR + Specifies the path to the ``/usr/share`` subdirectory of the sysroot + directory for the target for which the current recipe is being built + (:term:`STAGING_DIR_HOST`). + + STAGING_DATADIR_NATIVE + Specifies the path to the ``/usr/share`` subdirectory of the sysroot + directory for the build host. + + STAGING_DIR + Helps construct the ``recipe-sysroots`` directory, which is used + during packaging. + + For information on how staging for recipe-specific sysroots occurs, + see the :ref:`ref-tasks-populate_sysroot` + task, the ":ref:`sdk-manual/sdk-extensible:sharing files between recipes`" + section in the Yocto Project Development Tasks Manual, the + ":ref:`configuration-compilation-and-staging-dev-environment`" + section in the Yocto Project Overview and Concepts Manual, and the + :term:`SYSROOT_DIRS` variable. + + .. note:: + + Recipes should never write files directly under the + STAGING_DIR + directory because the OpenEmbedded build system manages the + directory automatically. Instead, files should be installed to + ${ + D + } + within your recipe's + do_install + task and then the OpenEmbedded build system will stage a subset of + those files into the sysroot. + + STAGING_DIR_HOST + Specifies the path to the sysroot directory for the system on which + the component is built to run (the system that hosts the component). + For most recipes, this sysroot is the one in which that recipe's + :ref:`ref-tasks-populate_sysroot` task copies + files. Exceptions include ``-native`` recipes, where the + ``do_populate_sysroot`` task instead uses + :term:`STAGING_DIR_NATIVE`. Depending on + the type of recipe and the build target, ``STAGING_DIR_HOST`` can + have the following values: + + - For recipes building for the target machine, the value is + "${:term:`STAGING_DIR`}/${:term:`MACHINE`}". + + - For native recipes building for the build host, the value is empty + given the assumption that when building for the build host, the + build host's own directories should be used. + + .. note:: + + ``-native`` recipes are not installed into host paths like such + as ``/usr``. Rather, these recipes are installed into + ``STAGING_DIR_NATIVE``. When compiling ``-native`` recipes, + standard build environment variables such as + :term:`CPPFLAGS` and + :term:`CFLAGS` are set up so that both host paths + and ``STAGING_DIR_NATIVE`` are searched for libraries and + headers using, for example, GCC's ``-isystem`` option. + + Thus, the emphasis is that the ``STAGING_DIR*`` variables + should be viewed as input variables by tasks such as + :ref:`ref-tasks-configure`, + :ref:`ref-tasks-compile`, and + :ref:`ref-tasks-install`. Having the real system + root correspond to ``STAGING_DIR_HOST`` makes conceptual sense + for ``-native`` recipes, as they make use of host headers and + libraries. + + STAGING_DIR_NATIVE + Specifies the path to the sysroot directory used when building + components that run on the build host itself. + + STAGING_DIR_TARGET + Specifies the path to the sysroot used for the system for which the + component generates code. For components that do not generate code, + which is the majority, ``STAGING_DIR_TARGET`` is set to match + :term:`STAGING_DIR_HOST`. + + Some recipes build binaries that can run on the target system but + those binaries in turn generate code for another different system + (e.g. cross-canadian recipes). Using terminology from GNU, the + primary system is referred to as the "HOST" and the secondary, or + different, system is referred to as the "TARGET". Thus, the binaries + run on the "HOST" system and generate binaries for the "TARGET" + system. The ``STAGING_DIR_HOST`` variable points to the sysroot used + for the "HOST" system, while ``STAGING_DIR_TARGET`` points to the + sysroot used for the "TARGET" system. + + STAGING_ETCDIR_NATIVE + Specifies the path to the ``/etc`` subdirectory of the sysroot + directory for the build host. + + STAGING_EXECPREFIXDIR + Specifies the path to the ``/usr`` subdirectory of the sysroot + directory for the target for which the current recipe is being built + (:term:`STAGING_DIR_HOST`). + + STAGING_INCDIR + Specifies the path to the ``/usr/include`` subdirectory of the + sysroot directory for the target for which the current recipe being + built (:term:`STAGING_DIR_HOST`). + + STAGING_INCDIR_NATIVE + Specifies the path to the ``/usr/include`` subdirectory of the + sysroot directory for the build host. + + STAGING_KERNEL_BUILDDIR + Points to the directory containing the kernel build artifacts. + Recipes building software that needs to access kernel build artifacts + (e.g. ``systemtap-uprobes``) can look in the directory specified with + the ``STAGING_KERNEL_BUILDDIR`` variable to find these artifacts + after the kernel has been built. + + STAGING_KERNEL_DIR + The directory with kernel headers that are required to build + out-of-tree modules. + + STAGING_LIBDIR + Specifies the path to the ``/usr/lib`` subdirectory of the sysroot + directory for the target for which the current recipe is being built + (:term:`STAGING_DIR_HOST`). + + STAGING_LIBDIR_NATIVE + Specifies the path to the ``/usr/lib`` subdirectory of the sysroot + directory for the build host. + + STAMP + Specifies the base path used to create recipe stamp files. The path + to an actual stamp file is constructed by evaluating this string and + then appending additional information. Currently, the default + assignment for ``STAMP`` as set in the ``meta/conf/bitbake.conf`` + file is: + :: + + STAMP = "${STAMPS_DIR}/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}" + + For information on how BitBake uses stamp files to determine if a + task should be rerun, see the + ":ref:`overview-manual/overview-manual-concepts:stamp files and the rerunning of tasks`" + section in the Yocto Project Overview and Concepts Manual. + + See :term:`STAMPS_DIR`, + :term:`MULTIMACH_TARGET_SYS`, + :term:`PN`, :term:`EXTENDPE`, + :term:`PV`, and :term:`PR` for related variable + information. + + STAMPS_DIR + Specifies the base directory in which the OpenEmbedded build system + places stamps. The default directory is ``${TMPDIR}/stamps``. + + STRIP + The minimal command and arguments to run ``strip``, which is used to + strip symbols. + + SUMMARY + The short (72 characters or less) summary of the binary package for + packaging systems such as ``opkg``, ``rpm``, or ``dpkg``. By default, + ``SUMMARY`` is used to define the + :term:`DESCRIPTION` variable if ``DESCRIPTION`` is + not set in the recipe. + + SVNDIR + The directory in which files checked out of a Subversion system are + stored. + + SYSLINUX_DEFAULT_CONSOLE + Specifies the kernel boot default console. If you want to use a + console other than the default, set this variable in your recipe as + follows where "X" is the console number you want to use: + :: + + SYSLINUX_DEFAULT_CONSOLE = "console=ttyX" + + The :ref:`syslinux <ref-classes-syslinux>` class initially sets + this variable to null but then checks for a value later. + + SYSLINUX_OPTS + Lists additional options to add to the syslinux file. You need to set + this variable in your recipe. If you want to list multiple options, + separate the options with a semicolon character (``;``). + + The :ref:`syslinux <ref-classes-syslinux>` class uses this variable + to create a set of options. + + SYSLINUX_SERIAL + Specifies the alternate serial port or turns it off. To turn off + serial, set this variable to an empty string in your recipe. The + variable's default value is set in the + :ref:`syslinux <ref-classes-syslinux>` class as follows: + :: + + SYSLINUX_SERIAL ?= "0 115200" + + The class checks for and uses the variable as needed. + + SYSLINUX_SPLASH + An ``.LSS`` file used as the background for the VGA boot menu when + you use the boot menu. You need to set this variable in your recipe. + + The :ref:`syslinux <ref-classes-syslinux>` class checks for this + variable and if found, the OpenEmbedded build system installs the + splash screen. + + SYSLINUX_SERIAL_TTY + Specifies the alternate console=tty... kernel boot argument. The + variable's default value is set in the + :ref:`syslinux <ref-classes-syslinux>` class as follows: + :: + + SYSLINUX_SERIAL_TTY ?= "console=ttyS0,115200" + + The class checks for and uses the variable as needed. + + SYSROOT_DESTDIR + Points to the temporary directory under the work directory (default + "``${``\ :term:`WORKDIR`\ ``}/sysroot-destdir``") + where the files populated into the sysroot are assembled during the + :ref:`ref-tasks-populate_sysroot` task. + + SYSROOT_DIRS + Directories that are staged into the sysroot by the + :ref:`ref-tasks-populate_sysroot` task. By + default, the following directories are staged: + :: + + SYSROOT_DIRS = " \ + ${includedir} \ + ${libdir} \ + ${base_libdir} \ + ${nonarch_base_libdir} \ + ${datadir} \ + " + + SYSROOT_DIRS_BLACKLIST + Directories that are not staged into the sysroot by the + :ref:`ref-tasks-populate_sysroot` task. You + can use this variable to exclude certain subdirectories of + directories listed in :term:`SYSROOT_DIRS` from + staging. By default, the following directories are not staged: + :: + + SYSROOT_DIRS_BLACKLIST = " \ + ${mandir} \ + ${docdir} \ + ${infodir} \ + ${datadir}/locale \ + ${datadir}/applications \ + ${datadir}/fonts \ + ${datadir}/pixmaps \ + " + + SYSROOT_DIRS_NATIVE + Extra directories staged into the sysroot by the + :ref:`ref-tasks-populate_sysroot` task for + ``-native`` recipes, in addition to those specified in + :term:`SYSROOT_DIRS`. By default, the following + extra directories are staged: + :: + + SYSROOT_DIRS_NATIVE = " \ + ${bindir} \ + ${sbindir} \ + ${base_bindir} \ + ${base_sbindir} \ + ${libexecdir} \ + ${sysconfdir} \ + ${localstatedir} \ + " + + .. note:: + + Programs built by + -native + recipes run directly from the sysroot ( + STAGING_DIR_NATIVE + ), which is why additional directories containing program + executables and supporting files need to be staged. + + SYSROOT_PREPROCESS_FUNCS + A list of functions to execute after files are staged into the + sysroot. These functions are usually used to apply additional + processing on the staged files, or to stage additional files. + + SYSTEMD_AUTO_ENABLE + When inheriting the :ref:`systemd <ref-classes-systemd>` class, + this variable specifies whether the specified service in + :term:`SYSTEMD_SERVICE` should start + automatically or not. By default, the service is enabled to + automatically start at boot time. The default setting is in the + :ref:`systemd <ref-classes-systemd>` class as follows: + :: + + SYSTEMD_AUTO_ENABLE ??= "enable" + + You can disable the service by setting the variable to "disable". + + SYSTEMD_BOOT_CFG + When :term:`EFI_PROVIDER` is set to + "systemd-boot", the ``SYSTEMD_BOOT_CFG`` variable specifies the + configuration file that should be used. By default, the + :ref:`systemd-boot <ref-classes-systemd-boot>` class sets the + ``SYSTEMD_BOOT_CFG`` as follows: + :: + + SYSTEMD_BOOT_CFG ?= "${:term:`S`}/loader.conf" + + For information on Systemd-boot, see the `Systemd-boot + documentation <http://www.freedesktop.org/wiki/Software/systemd/systemd-boot/>`__. + + SYSTEMD_BOOT_ENTRIES + When :term:`EFI_PROVIDER` is set to + "systemd-boot", the ``SYSTEMD_BOOT_ENTRIES`` variable specifies a + list of entry files (``*.conf``) to install that contain one boot + entry per file. By default, the + :ref:`systemd-boot <ref-classes-systemd-boot>` class sets the + ``SYSTEMD_BOOT_ENTRIES`` as follows: + :: + + SYSTEMD_BOOT_ENTRIES ?= "" + + For information on Systemd-boot, see the `Systemd-boot + documentation <http://www.freedesktop.org/wiki/Software/systemd/systemd-boot/>`__. + + SYSTEMD_BOOT_TIMEOUT + When :term:`EFI_PROVIDER` is set to + "systemd-boot", the ``SYSTEMD_BOOT_TIMEOUT`` variable specifies the + boot menu timeout in seconds. By default, the + :ref:`systemd-boot <ref-classes-systemd-boot>` class sets the + ``SYSTEMD_BOOT_TIMEOUT`` as follows: + :: + + SYSTEMD_BOOT_TIMEOUT ?= "10" + + For information on Systemd-boot, see the `Systemd-boot + documentation <http://www.freedesktop.org/wiki/Software/systemd/systemd-boot/>`__. + + SYSTEMD_PACKAGES + When inheriting the :ref:`systemd <ref-classes-systemd>` class, + this variable locates the systemd unit files when they are not found + in the main recipe's package. By default, the ``SYSTEMD_PACKAGES`` + variable is set such that the systemd unit files are assumed to + reside in the recipes main package: + :: + + SYSTEMD_PACKAGES ?= "${PN}" + + If these unit files are not in this recipe's main package, you need + to use ``SYSTEMD_PACKAGES`` to list the package or packages in which + the build system can find the systemd unit files. + + SYSTEMD_SERVICE + When inheriting the :ref:`systemd <ref-classes-systemd>` class, + this variable specifies the systemd service name for a package. + + When you specify this file in your recipe, use a package name + override to indicate the package to which the value applies. Here is + an example from the connman recipe: + :: + + SYSTEMD_SERVICE_${PN} = "connman.service" + + SYSVINIT_ENABLED_GETTYS + When using + :ref:`SysVinit <dev-manual/dev-manual-common-tasks:enabling system services>`, + specifies a space-separated list of the virtual terminals that should + run a `getty <http://en.wikipedia.org/wiki/Getty_%28Unix%29>`__ + (allowing login), assuming :term:`USE_VT` is not set to + "0". + + The default value for ``SYSVINIT_ENABLED_GETTYS`` is "1" (i.e. only + run a getty on the first virtual terminal). + + T + This variable points to a directory were BitBake places temporary + files, which consist mostly of task logs and scripts, when building a + particular recipe. The variable is typically set as follows: + :: + + T = "${WORKDIR}/temp" + + The :term:`WORKDIR` is the directory into which + BitBake unpacks and builds the recipe. The default ``bitbake.conf`` + file sets this variable. + + The ``T`` variable is not to be confused with the + :term:`TMPDIR` variable, which points to the root of + the directory tree where BitBake places the output of an entire + build. + + TARGET_ARCH + The target machine's architecture. The OpenEmbedded build system + supports many architectures. Here is an example list of architectures + supported. This list is by no means complete as the architecture is + configurable: + + - arm + - i586 + - x86_64 + - powerpc + - powerpc64 + - mips + - mipsel + + For additional information on machine architectures, see the + :term:`TUNE_ARCH` variable. + + TARGET_AS_ARCH + Specifies architecture-specific assembler flags for the target + system. ``TARGET_AS_ARCH`` is initialized from + :term:`TUNE_ASARGS` by default in the BitBake + configuration file (``meta/conf/bitbake.conf``): + :: + + TARGET_AS_ARCH = "${TUNE_ASARGS}" + + TARGET_CC_ARCH + Specifies architecture-specific C compiler flags for the target + system. ``TARGET_CC_ARCH`` is initialized from + :term:`TUNE_CCARGS` by default. + + .. note:: + + It is a common workaround to append + LDFLAGS + to + TARGET_CC_ARCH + in recipes that build software for the target that would not + otherwise respect the exported + LDFLAGS + variable. + + TARGET_CC_KERNEL_ARCH + This is a specific kernel compiler flag for a CPU or Application + Binary Interface (ABI) tune. The flag is used rarely and only for + cases where a userspace :term:`TUNE_CCARGS` is not + compatible with the kernel compilation. The ``TARGET_CC_KERNEL_ARCH`` + variable allows the kernel (and associated modules) to use a + different configuration. See the + ``meta/conf/machine/include/arm/feature-arm-thumb.inc`` file in the + :term:`Source Directory` for an example. + + TARGET_CFLAGS + Specifies the flags to pass to the C compiler when building for the + target. When building in the target context, + :term:`CFLAGS` is set to the value of this variable by + default. + + Additionally, the SDK's environment setup script sets the ``CFLAGS`` + variable in the environment to the ``TARGET_CFLAGS`` value so that + executables built using the SDK also have the flags applied. + + TARGET_CPPFLAGS + Specifies the flags to pass to the C pre-processor (i.e. to both the + C and the C++ compilers) when building for the target. When building + in the target context, :term:`CPPFLAGS` is set to the + value of this variable by default. + + Additionally, the SDK's environment setup script sets the + ``CPPFLAGS`` variable in the environment to the ``TARGET_CPPFLAGS`` + value so that executables built using the SDK also have the flags + applied. + + TARGET_CXXFLAGS + Specifies the flags to pass to the C++ compiler when building for the + target. When building in the target context, + :term:`CXXFLAGS` is set to the value of this variable + by default. + + Additionally, the SDK's environment setup script sets the + ``CXXFLAGS`` variable in the environment to the ``TARGET_CXXFLAGS`` + value so that executables built using the SDK also have the flags + applied. + + TARGET_FPU + Specifies the method for handling FPU code. For FPU-less targets, + which include most ARM CPUs, the variable must be set to "soft". If + not, the kernel emulation gets used, which results in a performance + penalty. + + TARGET_LD_ARCH + Specifies architecture-specific linker flags for the target system. + ``TARGET_LD_ARCH`` is initialized from + :term:`TUNE_LDARGS` by default in the BitBake + configuration file (``meta/conf/bitbake.conf``): + :: + + TARGET_LD_ARCH = "${TUNE_LDARGS}" + + TARGET_LDFLAGS + Specifies the flags to pass to the linker when building for the + target. When building in the target context, + :term:`LDFLAGS` is set to the value of this variable + by default. + + Additionally, the SDK's environment setup script sets the + :term:`LDFLAGS` variable in the environment to the + ``TARGET_LDFLAGS`` value so that executables built using the SDK also + have the flags applied. + + TARGET_OS + Specifies the target's operating system. The variable can be set to + "linux" for glibc-based systems (GNU C Library) and to "linux-musl" + for musl libc. For ARM/EABI targets, "linux-gnueabi" and + "linux-musleabi" possible values exist. + + TARGET_PREFIX + Specifies the prefix used for the toolchain binary target tools. + + Depending on the type of recipe and the build target, + ``TARGET_PREFIX`` is set as follows: + + - For recipes building for the target machine, the value is + "${:term:`TARGET_SYS`}-". + + - For native recipes, the build system sets the variable to the + value of ``BUILD_PREFIX``. + + - For native SDK recipes (``nativesdk``), the build system sets the + variable to the value of ``SDK_PREFIX``. + + TARGET_SYS + Specifies the system, including the architecture and the operating + system, for which the build is occurring in the context of the + current recipe. + + The OpenEmbedded build system automatically sets this variable based + on :term:`TARGET_ARCH`, + :term:`TARGET_VENDOR`, and + :term:`TARGET_OS` variables. + + .. note:: + + You do not need to set the TARGET_SYS variable yourself. + + Consider these two examples: + + - Given a native recipe on a 32-bit, x86 machine running Linux, the + value is "i686-linux". + + - Given a recipe being built for a little-endian, MIPS target + running Linux, the value might be "mipsel-linux". + + TARGET_VENDOR + Specifies the name of the target vendor. + + TCLIBC + Specifies the GNU standard C library (``libc``) variant to use during + the build process. This variable replaces ``POKYLIBC``, which is no + longer supported. + + You can select "glibc", "musl", "newlib", or "baremetal" + + TCLIBCAPPEND + Specifies a suffix to be appended onto the + :term:`TMPDIR` value. The suffix identifies the + ``libc`` variant for building. When you are building for multiple + variants with the same :term:`Build Directory`, this + mechanism ensures that output for different ``libc`` variants is kept + separate to avoid potential conflicts. + + In the ``defaultsetup.conf`` file, the default value of + ``TCLIBCAPPEND`` is "-${TCLIBC}". However, distros such as poky, + which normally only support one ``libc`` variant, set + ``TCLIBCAPPEND`` to "" in their distro configuration file resulting + in no suffix being applied. + + TCMODE + Specifies the toolchain selector. ``TCMODE`` controls the + characteristics of the generated packages and images by telling the + OpenEmbedded build system which toolchain profile to use. By default, + the OpenEmbedded build system builds its own internal toolchain. The + variable's default value is "default", which uses that internal + toolchain. + + .. note:: + + If + TCMODE + is set to a value other than "default", then it is your + responsibility to ensure that the toolchain is compatible with the + default toolchain. Using older or newer versions of these + components might cause build problems. See the Release Notes for + the Yocto Project release for the specific components with which + the toolchain must be compatible. To access the Release Notes, go + to the + Downloads + page on the Yocto Project website and click on the "RELEASE + INFORMATION" link for the appropriate release. + + The ``TCMODE`` variable is similar to :term:`TCLIBC`, + which controls the variant of the GNU standard C library (``libc``) + used during the build process: ``glibc`` or ``musl``. + + With additional layers, it is possible to use a pre-compiled external + toolchain. One example is the Sourcery G++ Toolchain. The support for + this toolchain resides in the separate Mentor Graphics + ``meta-sourcery`` layer at + http://github.com/MentorEmbedded/meta-sourcery/. + + The layer's ``README`` file contains information on how to use the + Sourcery G++ Toolchain as an external toolchain. In summary, you must + be sure to add the layer to your ``bblayers.conf`` file in front of + the ``meta`` layer and then set the ``EXTERNAL_TOOLCHAIN`` variable + in your ``local.conf`` file to the location in which you installed + the toolchain. + + The fundamentals used for this example apply to any external + toolchain. You can use ``meta-sourcery`` as a template for adding + support for other external toolchains. + + TEST_EXPORT_DIR + The location the OpenEmbedded build system uses to export tests when + the :term:`TEST_EXPORT_ONLY` variable is set + to "1". + + The ``TEST_EXPORT_DIR`` variable defaults to + ``"${TMPDIR}/testimage/${PN}"``. + + TEST_EXPORT_ONLY + Specifies to export the tests only. Set this variable to "1" if you + do not want to run the tests but you want them to be exported in a + manner that you to run them outside of the build system. + + TEST_LOG_DIR + Holds the SSH log and the boot log for QEMU machines. The + ``TEST_LOG_DIR`` variable defaults to ``"${WORKDIR}/testimage"``. + + .. note:: + + Actual test results reside in the task log ( + log.do_testimage + ), which is in the + ${WORKDIR}/temp/ + directory. + + TEST_POWERCONTROL_CMD + For automated hardware testing, specifies the command to use to + control the power of the target machine under test. Typically, this + command would point to a script that performs the appropriate action + (e.g. interacting with a web-enabled power strip). The specified + command should expect to receive as the last argument "off", "on" or + "cycle" specifying to power off, on, or cycle (power off and then + power on) the device, respectively. + + TEST_POWERCONTROL_EXTRA_ARGS + For automated hardware testing, specifies additional arguments to + pass through to the command specified in + :term:`TEST_POWERCONTROL_CMD`. Setting + ``TEST_POWERCONTROL_EXTRA_ARGS`` is optional. You can use it if you + wish, for example, to separate the machine-specific and + non-machine-specific parts of the arguments. + + TEST_QEMUBOOT_TIMEOUT + The time in seconds allowed for an image to boot before automated + runtime tests begin to run against an image. The default timeout + period to allow the boot process to reach the login prompt is 500 + seconds. You can specify a different value in the ``local.conf`` + file. + + For more information on testing images, see the + ":ref:`dev-manual/dev-manual-common-tasks:performing automated runtime testing`" + section in the Yocto Project Development Tasks Manual. + + TEST_SERIALCONTROL_CMD + For automated hardware testing, specifies the command to use to + connect to the serial console of the target machine under test. This + command simply needs to connect to the serial console and forward + that connection to standard input and output as any normal terminal + program does. + + For example, to use the Picocom terminal program on serial device + ``/dev/ttyUSB0`` at 115200bps, you would set the variable as follows: + :: + + TEST_SERIALCONTROL_CMD = "picocom /dev/ttyUSB0 -b 115200" + + TEST_SERIALCONTROL_EXTRA_ARGS + For automated hardware testing, specifies additional arguments to + pass through to the command specified in + :term:`TEST_SERIALCONTROL_CMD`. Setting + ``TEST_SERIALCONTROL_EXTRA_ARGS`` is optional. You can use it if you + wish, for example, to separate the machine-specific and + non-machine-specific parts of the command. + + TEST_SERVER_IP + The IP address of the build machine (host machine). This IP address + is usually automatically detected. However, if detection fails, this + variable needs to be set to the IP address of the build machine (i.e. + where the build is taking place). + + .. note:: + + The + TEST_SERVER_IP + variable is only used for a small number of tests such as the + "dnf" test suite, which needs to download packages from + WORKDIR/oe-rootfs-repo + . + + TEST_TARGET + Specifies the target controller to use when running tests against a + test image. The default controller to use is "qemu": + :: + + TEST_TARGET = "qemu" + + A target controller is a class that defines how an image gets + deployed on a target and how a target is started. A layer can extend + the controllers by adding a module in the layer's + ``/lib/oeqa/controllers`` directory and by inheriting the + ``BaseTarget`` class, which is an abstract class that cannot be used + as a value of ``TEST_TARGET``. + + You can provide the following arguments with ``TEST_TARGET``: + + - *"qemu":* Boots a QEMU image and runs the tests. See the + ":ref:`qemu-image-enabling-tests`" section + in the Yocto Project Development Tasks Manual for more + information. + + - *"simpleremote":* Runs the tests on target hardware that is + already up and running. The hardware can be on the network or it + can be a device running an image on QEMU. You must also set + :term:`TEST_TARGET_IP` when you use + "simpleremote". + + .. note:: + + This argument is defined in + meta/lib/oeqa/controllers/simpleremote.py + . + + For information on running tests on hardware, see the + ":ref:`hardware-image-enabling-tests`" + section in the Yocto Project Development Tasks Manual. + + TEST_TARGET_IP + The IP address of your hardware under test. The ``TEST_TARGET_IP`` + variable has no effect when :term:`TEST_TARGET` is + set to "qemu". + + When you specify the IP address, you can also include a port. Here is + an example: + :: + + TEST_TARGET_IP = "192.168.1.4:2201" + + Specifying a port is + useful when SSH is started on a non-standard port or in cases when + your hardware under test is behind a firewall or network that is not + directly accessible from your host and you need to do port address + translation. + + TEST_SUITES + An ordered list of tests (modules) to run against an image when + performing automated runtime testing. + + The OpenEmbedded build system provides a core set of tests that can + be used against images. + + .. note:: + + Currently, there is only support for running these tests under + QEMU. + + Tests include ``ping``, ``ssh``, ``df`` among others. You can add + your own tests to the list of tests by appending ``TEST_SUITES`` as + follows: + :: + + TEST_SUITES_append = " mytest" + + Alternatively, you can + provide the "auto" option to have all applicable tests run against + the image. + :: + + TEST_SUITES_append = " auto" + + Using this option causes the + build system to automatically run tests that are applicable to the + image. Tests that are not applicable are skipped. + + The order in which tests are run is important. Tests that depend on + another test must appear later in the list than the test on which + they depend. For example, if you append the list of tests with two + tests (``test_A`` and ``test_B``) where ``test_B`` is dependent on + ``test_A``, then you must order the tests as follows: + :: + + TEST_SUITES = "test_A test_B" + + For more information on testing images, see the + ":ref:`dev-manual/dev-manual-common-tasks:performing automated runtime testing`" + section in the Yocto Project Development Tasks Manual. + + TESTIMAGE_AUTO + Automatically runs the series of automated tests for images when an + image is successfully built. Setting ``TESTIMAGE_AUTO`` to "1" causes + any image that successfully builds to automatically boot under QEMU. + Using the variable also adds in dependencies so that any SDK for + which testing is requested is automatically built first. + + These tests are written in Python making use of the ``unittest`` + module, and the majority of them run commands on the target system + over ``ssh``. You can set this variable to "1" in your ``local.conf`` + file in the :term:`Build Directory` to have the + OpenEmbedded build system automatically run these tests after an + image successfully builds: + + TESTIMAGE_AUTO = "1" + + For more information + on enabling, running, and writing these tests, see the + ":ref:`dev-manual/dev-manual-common-tasks:performing automated runtime testing`" + section in the Yocto Project Development Tasks Manual and the + ":ref:`testimage*.bbclass <ref-classes-testimage*>`" section. + + THISDIR + The directory in which the file BitBake is currently parsing is + located. Do not manually set this variable. + + TIME + The time the build was started. Times appear using the hour, minute, + and second (HMS) format (e.g. "140159" for one minute and fifty-nine + seconds past 1400 hours). + + TMPDIR + This variable is the base directory the OpenEmbedded build system + uses for all build output and intermediate files (other than the + shared state cache). By default, the ``TMPDIR`` variable points to + ``tmp`` within the :term:`Build Directory`. + + If you want to establish this directory in a location other than the + default, you can uncomment and edit the following statement in the + ``conf/local.conf`` file in the :term:`Source Directory`: + :: + + #TMPDIR = "${TOPDIR}/tmp" + + An example use for this scenario is to set ``TMPDIR`` to a local disk, + which does not use NFS, while having the Build Directory use NFS. + + The filesystem used by ``TMPDIR`` must have standard filesystem + semantics (i.e. mixed-case files are unique, POSIX file locking, and + persistent inodes). Due to various issues with NFS and bugs in some + implementations, NFS does not meet this minimum requirement. + Consequently, ``TMPDIR`` cannot be on NFS. + + TOOLCHAIN_HOST_TASK + This variable lists packages the OpenEmbedded build system uses when + building an SDK, which contains a cross-development environment. The + packages specified by this variable are part of the toolchain set + that runs on the :term:`SDKMACHINE`, and each + package should usually have the prefix ``nativesdk-``. For example, + consider the following command when building an SDK: + :: + + $ bitbake -c populate_sdk imagename + + In this case, a default list of packages is + set in this variable, but you can add additional packages to the + list. See the + ":ref:`sdk-manual/sdk-appendix-customizing-standard:adding individual packages to the standard sdk`" section + in the Yocto Project Application Development and the Extensible + Software Development Kit (eSDK) manual for more information. + + For background information on cross-development toolchains in the + Yocto Project development environment, see the + ":ref:`sdk-manual/sdk-intro:the cross-development toolchain`" + section in the Yocto Project Overview and Concepts Manual. For + information on setting up a cross-development environment, see the + :doc:`../sdk-manual/sdk-manual` manual. + + TOOLCHAIN_OUTPUTNAME + This variable defines the name used for the toolchain output. The + :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class sets + the ``TOOLCHAIN_OUTPUTNAME`` variable as follows: + :: + + TOOLCHAIN_OUTPUTNAME ?= "${SDK_NAME}-toolchain-${SDK_VERSION}" + + See + the :term:`SDK_NAME` and + :term:`SDK_VERSION` variables for additional + information. + + TOOLCHAIN_TARGET_TASK + This variable lists packages the OpenEmbedded build system uses when + it creates the target part of an SDK (i.e. the part built for the + target hardware), which includes libraries and headers. Use this + variable to add individual packages to the part of the SDK that runs + on the target. See the + ":ref:`sdk-manual/sdk-appendix-customizing-standard:adding individual packages to the standard sdk`" section + in the Yocto Project Application Development and the Extensible + Software Development Kit (eSDK) manual for more information. + + For background information on cross-development toolchains in the + Yocto Project development environment, see the + ":ref:`sdk-manual/sdk-intro:the cross-development toolchain`" + section in the Yocto Project Overview and Concepts Manual. For + information on setting up a cross-development environment, see the + :doc:`../sdk-manual/sdk-manual` manual. + + TOPDIR + The top-level :term:`Build Directory`. BitBake + automatically sets this variable when you initialize your build + environment using ````` <#structure-core-script>`__. + + TRANSLATED_TARGET_ARCH + A sanitized version of :term:`TARGET_ARCH`. This + variable is used where the architecture is needed in a value where + underscores are not allowed, for example within package filenames. In + this case, dash characters replace any underscore characters used in + ``TARGET_ARCH``. + + Do not edit this variable. + + TUNE_ARCH + The GNU canonical architecture for a specific architecture (i.e. + ``arm``, ``armeb``, ``mips``, ``mips64``, and so forth). BitBake uses + this value to setup configuration. + + ``TUNE_ARCH`` definitions are specific to a given architecture. The + definitions can be a single static definition, or can be dynamically + adjusted. You can see details for a given CPU family by looking at + the architecture's ``README`` file. For example, the + ``meta/conf/machine/include/mips/README`` file in the + :term:`Source Directory` provides information for + ``TUNE_ARCH`` specific to the ``mips`` architecture. + + ``TUNE_ARCH`` is tied closely to + :term:`TARGET_ARCH`, which defines the target + machine's architecture. The BitBake configuration file + (``meta/conf/bitbake.conf``) sets ``TARGET_ARCH`` as follows: + :: + + TARGET_ARCH = "${TUNE_ARCH}" + + The following list, which is by no means complete since architectures + are configurable, shows supported machine architectures: + + - arm + - i586 + - x86_64 + - powerpc + - powerpc64 + - mips + - mipsel + + TUNE_ASARGS + Specifies architecture-specific assembler flags for the target + system. The set of flags is based on the selected tune features. + ``TUNE_ASARGS`` is set using the tune include files, which are + typically under ``meta/conf/machine/include/`` and are influenced + through :term:`TUNE_FEATURES`. For example, the + ``meta/conf/machine/include/x86/arch-x86.inc`` file defines the flags + for the x86 architecture as follows: + :: + + TUNE_ASARGS += "${@bb.utils.contains("TUNE_FEATURES", "mx32", "-x32", "", d)}" + + .. note:: + + Board Support Packages (BSPs) select the tune. The selected tune, + in turn, affects the tune variables themselves (i.e. the tune can + supply its own set of flags). + + TUNE_CCARGS + Specifies architecture-specific C compiler flags for the target + system. The set of flags is based on the selected tune features. + ``TUNE_CCARGS`` is set using the tune include files, which are + typically under ``meta/conf/machine/include/`` and are influenced + through :term:`TUNE_FEATURES`. + + .. note:: + + Board Support Packages (BSPs) select the tune. The selected tune, + in turn, affects the tune variables themselves (i.e. the tune can + supply its own set of flags). + + TUNE_LDARGS + Specifies architecture-specific linker flags for the target system. + The set of flags is based on the selected tune features. + ``TUNE_LDARGS`` is set using the tune include files, which are + typically under ``meta/conf/machine/include/`` and are influenced + through :term:`TUNE_FEATURES`. For example, the + ``meta/conf/machine/include/x86/arch-x86.inc`` file defines the flags + for the x86 architecture as follows: + :: + + TUNE_LDARGS += "${@bb.utils.contains("TUNE_FEATURES", "mx32", "-m elf32_x86_64", "", d)}" + + .. note:: + + Board Support Packages (BSPs) select the tune. The selected tune, + in turn, affects the tune variables themselves (i.e. the tune can + supply its own set of flags). + + TUNE_FEATURES + Features used to "tune" a compiler for optimal use given a specific + processor. The features are defined within the tune files and allow + arguments (i.e. ``TUNE_*ARGS``) to be dynamically generated based on + the features. + + The OpenEmbedded build system verifies the features to be sure they + are not conflicting and that they are supported. + + The BitBake configuration file (``meta/conf/bitbake.conf``) defines + ``TUNE_FEATURES`` as follows: + :: + + TUNE_FEATURES ??= "${TUNE_FEATURES_tune-${DEFAULTTUNE}}" + + See the :term:`DEFAULTTUNE` variable for more information. + + TUNE_PKGARCH + The package architecture understood by the packaging system to define + the architecture, ABI, and tuning of output packages. The specific + tune is defined using the "_tune" override as follows: + :: + + TUNE_PKGARCH_tune-tune = "tune" + + These tune-specific package architectures are defined in the machine + include files. Here is an example of the "core2-32" tuning as used in + the ``meta/conf/machine/include/tune-core2.inc`` file: + :: + + TUNE_PKGARCH_tune-core2-32 = "core2-32" + + TUNEABI + An underlying Application Binary Interface (ABI) used by a particular + tuning in a given toolchain layer. Providers that use prebuilt + libraries can use the ``TUNEABI``, + :term:`TUNEABI_OVERRIDE`, and + :term:`TUNEABI_WHITELIST` variables to check + compatibility of tunings against their selection of libraries. + + If ``TUNEABI`` is undefined, then every tuning is allowed. See the + :ref:`sanity <ref-classes-sanity>` class to see how the variable is + used. + + TUNEABI_OVERRIDE + If set, the OpenEmbedded system ignores the + :term:`TUNEABI_WHITELIST` variable. + Providers that use prebuilt libraries can use the + ``TUNEABI_OVERRIDE``, ``TUNEABI_WHITELIST``, and + :term:`TUNEABI` variables to check compatibility of a + tuning against their selection of libraries. + + See the :ref:`sanity <ref-classes-sanity>` class to see how the + variable is used. + + TUNEABI_WHITELIST + A whitelist of permissible :term:`TUNEABI` values. If + ``TUNEABI_WHITELIST`` is not set, all tunes are allowed. Providers + that use prebuilt libraries can use the ``TUNEABI_WHITELIST``, + :term:`TUNEABI_OVERRIDE`, and ``TUNEABI`` + variables to check compatibility of a tuning against their selection + of libraries. + + See the :ref:`sanity <ref-classes-sanity>` class to see how the + variable is used. + + TUNECONFLICTS[feature] + Specifies CPU or Application Binary Interface (ABI) tuning features + that conflict with feature. + + Known tuning conflicts are specified in the machine include files in + the :term:`Source Directory`. Here is an example from + the ``meta/conf/machine/include/mips/arch-mips.inc`` include file + that lists the "o32" and "n64" features as conflicting with the "n32" + feature: + :: + + TUNECONFLICTS[n32] = "o32 n64" + + TUNEVALID[feature] + Specifies a valid CPU or Application Binary Interface (ABI) tuning + feature. The specified feature is stored as a flag. Valid features + are specified in the machine include files (e.g. + ``meta/conf/machine/include/arm/arch-arm.inc``). Here is an example + from that file: + :: + + TUNEVALID[bigendian] = "Enable big-endian mode." + + See the machine include files in the :term:`Source Directory` + for these features. + + UBOOT_CONFIG + Configures the :term:`UBOOT_MACHINE` and can + also define :term:`IMAGE_FSTYPES` for individual + cases. + + Following is an example from the ``meta-fsl-arm`` layer. :: + + UBOOT_CONFIG ??= "sd" + UBOOT_CONFIG[sd] = "mx6qsabreauto_config,sdcard" + UBOOT_CONFIG[eimnor] = "mx6qsabreauto_eimnor_config" + UBOOT_CONFIG[nand] = "mx6qsabreauto_nand_config,ubifs" + UBOOT_CONFIG[spinor] = "mx6qsabreauto_spinor_config" + + In this example, "sd" is selected as the configuration of the possible four for the + ``UBOOT_MACHINE``. The "sd" configuration defines + "mx6qsabreauto_config" as the value for ``UBOOT_MACHINE``, while the + "sdcard" specifies the ``IMAGE_FSTYPES`` to use for the U-boot image. + + For more information on how the ``UBOOT_CONFIG`` is handled, see the + :ref:`uboot-config <ref-classes-uboot-config>` + class. + + UBOOT_DTB_LOADADDRESS + Specifies the load address for the dtb image used by U-boot. During FIT + image creation, the ``UBOOT_DTB_LOADADDRESS`` variable is used in + :ref:`kernel-fitimage <ref-classes-kernel-fitimage>` class to specify + the load address to be used in + creating the dtb sections of Image Tree Source for the FIT image. + + UBOOT_DTBO_LOADADDRESS + Specifies the load address for the dtbo image used by U-boot. During FIT + image creation, the ``UBOOT_DTBO_LOADADDRESS`` variable is used in + :ref:`kernel-fitimage <ref-classes-kernel-fitimage>` class to specify the load address to be used in + creating the dtbo sections of Image Tree Source for the FIT image. + + UBOOT_ENTRYPOINT + Specifies the entry point for the U-Boot image. During U-Boot image + creation, the ``UBOOT_ENTRYPOINT`` variable is passed as a + command-line parameter to the ``uboot-mkimage`` utility. + + UBOOT_LOADADDRESS + Specifies the load address for the U-Boot image. During U-Boot image + creation, the ``UBOOT_LOADADDRESS`` variable is passed as a + command-line parameter to the ``uboot-mkimage`` utility. + + UBOOT_LOCALVERSION + Appends a string to the name of the local version of the U-Boot + image. For example, assuming the version of the U-Boot image built + was "2013.10", the full version string reported by U-Boot would be + "2013.10-yocto" given the following statement: + :: + + UBOOT_LOCALVERSION = "-yocto" + + UBOOT_MACHINE + Specifies the value passed on the ``make`` command line when building + a U-Boot image. The value indicates the target platform + configuration. You typically set this variable from the machine + configuration file (i.e. ``conf/machine/machine_name.conf``). + + Please see the "Selection of Processor Architecture and Board Type" + section in the U-Boot README for valid values for this variable. + + UBOOT_MAKE_TARGET + Specifies the target called in the ``Makefile``. The default target + is "all". + + UBOOT_MKIMAGE_DTCOPTS + Options for the device tree compiler passed to mkimage '-D' + feature while creating FIT image in :ref:`kernel-fitimage <ref-classes-kernel-fitimage>` class. + + UBOOT_RD_LOADADDRESS + Specifies the load address for the RAM disk image. + During FIT image creation, the + ``UBOOT_RD_LOADADDRESS`` variable is used + in :ref:`kernel-fitimage <ref-classes-kernel-fitimage>` class to specify the + load address to be used in creating the Image Tree Source for + the FIT image. + + UBOOT_RD_ENTRYPOINT + Specifies the entrypoint for the RAM disk image. + During FIT image creation, the + ``UBOOT_RD_ENTRYPOINT`` variable is used + in :ref:`kernel-fitimage <ref-classes-kernel-fitimage>` class to specify the + entrypoint to be used in creating the Image Tree Source for + the FIT image. + + UBOOT_SIGN_ENABLE + Enable signing of FIT image. The default value is "0". + + UBOOT_SIGN_KEYDIR + Location of the directory containing the RSA key and + certificate used for signing FIT image. + + UBOOT_SIGN_KEYNAME + The name of keys used for signing U-boot FIT image stored in + :term:`UBOOT_SIGN_KEYDIR` directory. For e.g. dev.key key and dev.crt + certificate stored in :term:`UBOOT_SIGN_KEYDIR` directory will have + :term:`UBOOT_SIGN_KEYNAME` set to "dev". + + UBOOT_SUFFIX + Points to the generated U-Boot extension. For example, ``u-boot.sb`` + has a ``.sb`` extension. + + The default U-Boot extension is ``.bin`` + + UBOOT_TARGET + Specifies the target used for building U-Boot. The target is passed + directly as part of the "make" command (e.g. SPL and AIS). If you do + not specifically set this variable, the OpenEmbedded build process + passes and uses "all" for the target during the U-Boot building + process. + + UNKNOWN_CONFIGURE_WHITELIST + Specifies a list of options that, if reported by the configure script + as being invalid, should not generate a warning during the + :ref:`ref-tasks-configure` task. Normally, invalid + configure options are simply not passed to the configure script (e.g. + should be removed from :term:`EXTRA_OECONF` or + :term:`PACKAGECONFIG_CONFARGS`). + However, common options, for example, exist that are passed to all + configure scripts at a class level that might not be valid for some + configure scripts. It follows that no benefit exists in seeing a + warning about these options. For these cases, the options are added + to ``UNKNOWN_CONFIGURE_WHITELIST``. + + The configure arguments check that uses + ``UNKNOWN_CONFIGURE_WHITELIST`` is part of the + :ref:`insane <ref-classes-insane>` class and is only enabled if the + recipe inherits the :ref:`autotools <ref-classes-autotools>` class. + + UPDATERCPN + For recipes inheriting the + :ref:`update-rc.d <ref-classes-update-rc.d>` class, ``UPDATERCPN`` + specifies the package that contains the initscript that is enabled. + + The default value is "${PN}". Given that almost all recipes that + install initscripts package them in the main package for the recipe, + you rarely need to set this variable in individual recipes. + + UPSTREAM_CHECK_GITTAGREGEX + You can perform a per-recipe check for what the latest upstream + source code version is by calling ``bitbake -c checkpkg`` recipe. If + the recipe source code is provided from Git repositories, the + OpenEmbedded build system determines the latest upstream version by + picking the latest tag from the list of all repository tags. + + You can use the ``UPSTREAM_CHECK_GITTAGREGEX`` variable to provide a + regular expression to filter only the relevant tags should the + default filter not work correctly. + :: + + UPSTREAM_CHECK_GITTAGREGEX = "git_tag_regex" + + UPSTREAM_CHECK_REGEX + Use the ``UPSTREAM_CHECK_REGEX`` variable to specify a different + regular expression instead of the default one when the package + checking system is parsing the page found using + :term:`UPSTREAM_CHECK_URI`. + :: + + UPSTREAM_CHECK_REGEX = "package_regex" + + UPSTREAM_CHECK_URI + You can perform a per-recipe check for what the latest upstream + source code version is by calling ``bitbake -c checkpkg`` recipe. If + the source code is provided from tarballs, the latest version is + determined by fetching the directory listing where the tarball is and + attempting to find a later tarball. When this approach does not work, + you can use ``UPSTREAM_CHECK_URI`` to provide a different URI that + contains the link to the latest tarball. + :: + + UPSTREAM_CHECK_URI = "recipe_url" + + USE_DEVFS + Determines if ``devtmpfs`` is used for ``/dev`` population. The + default value used for ``USE_DEVFS`` is "1" when no value is + specifically set. Typically, you would set ``USE_DEVFS`` to "0" for a + statically populated ``/dev`` directory. + + See the ":ref:`selecting-dev-manager`" section in + the Yocto Project Development Tasks Manual for information on how to + use this variable. + + USE_VT + When using + :ref:`SysVinit <new-recipe-enabling-system-services>`, + determines whether or not to run a + `getty <http://en.wikipedia.org/wiki/Getty_%28Unix%29>`__ on any + virtual terminals in order to enable logging in through those + terminals. + + The default value used for ``USE_VT`` is "1" when no default value is + specifically set. Typically, you would set ``USE_VT`` to "0" in the + machine configuration file for machines that do not have a graphical + display attached and therefore do not need virtual terminal + functionality. + + USER_CLASSES + A list of classes to globally inherit. These classes are used by the + OpenEmbedded build system to enable extra features (e.g. + ``buildstats``, ``image-mklibs``, and so forth). + + The default list is set in your ``local.conf`` file: + :: + + USER_CLASSES ?= "buildstats image-mklibs image-prelink" + + For more information, see + ``meta-poky/conf/local.conf.sample`` in the :term:`Source Directory`. + + USERADD_ERROR_DYNAMIC + If set to ``error``, forces the OpenEmbedded build system to produce + an error if the user identification (``uid``) and group + identification (``gid``) values are not defined in any of the files + listed in :term:`USERADD_UID_TABLES` and + :term:`USERADD_GID_TABLES`. If set to + ``warn``, a warning will be issued instead. + + The default behavior for the build system is to dynamically apply + ``uid`` and ``gid`` values. Consequently, the + ``USERADD_ERROR_DYNAMIC`` variable is by default not set. If you plan + on using statically assigned ``gid`` and ``uid`` values, you should + set the ``USERADD_ERROR_DYNAMIC`` variable in your ``local.conf`` + file as follows: + :: + + USERADD_ERROR_DYNAMIC = "error" + + Overriding the + default behavior implies you are going to also take steps to set + static ``uid`` and ``gid`` values through use of the + :term:`USERADDEXTENSION`, + :term:`USERADD_UID_TABLES`, and + :term:`USERADD_GID_TABLES` variables. + + .. note:: + + There is a difference in behavior between setting + USERADD_ERROR_DYNAMIC + to + error + and setting it to + warn + . When it is set to + warn + , the build system will report a warning for every undefined + uid + and + gid + in any recipe. But when it is set to + error + , it will only report errors for recipes that are actually built. + This saves you from having to add static IDs for recipes that you + know will never be built. + + USERADD_GID_TABLES + Specifies a password file to use for obtaining static group + identification (``gid``) values when the OpenEmbedded build system + adds a group to the system during package installation. + + When applying static group identification (``gid``) values, the + OpenEmbedded build system looks in :term:`BBPATH` for a + ``files/group`` file and then applies those ``uid`` values. Set the + variable as follows in your ``local.conf`` file: + :: + + + USERADD_GID_TABLES = "files/group" + + .. note:: + + Setting the + USERADDEXTENSION + variable to "useradd-staticids" causes the build system to use + static + gid + values. + + USERADD_PACKAGES + When inheriting the :ref:`useradd <ref-classes-useradd>` class, + this variable specifies the individual packages within the recipe + that require users and/or groups to be added. + + You must set this variable if the recipe inherits the class. For + example, the following enables adding a user for the main package in + a recipe: + :: + + USERADD_PACKAGES = "${PN}" + + .. note:: + + It follows that if you are going to use the + USERADD_PACKAGES + variable, you need to set one or more of the + USERADD_PARAM + , + GROUPADD_PARAM + , or + GROUPMEMS_PARAM + variables. + + USERADD_PARAM + When inheriting the :ref:`useradd <ref-classes-useradd>` class, + this variable specifies for a package what parameters should pass to + the ``useradd`` command if you add a user to the system when the + package is installed. + + Here is an example from the ``dbus`` recipe: + :: + + USERADD_PARAM_${PN} = "--system --home ${localstatedir}/lib/dbus \ + --no-create-home --shell /bin/false \ + --user-group messagebus" + + For information on the + standard Linux shell command ``useradd``, see + http://linux.die.net/man/8/useradd. + + USERADD_UID_TABLES + Specifies a password file to use for obtaining static user + identification (``uid``) values when the OpenEmbedded build system + adds a user to the system during package installation. + + When applying static user identification (``uid``) values, the + OpenEmbedded build system looks in :term:`BBPATH` for a + ``files/passwd`` file and then applies those ``uid`` values. Set the + variable as follows in your ``local.conf`` file: + :: + + USERADD_UID_TABLES = "files/passwd" + + .. note:: + + Setting the + USERADDEXTENSION + variable to "useradd-staticids" causes the build system to use + static + uid + values. + + USERADDEXTENSION + When set to "useradd-staticids", causes the OpenEmbedded build system + to base all user and group additions on a static ``passwd`` and + ``group`` files found in :term:`BBPATH`. + + To use static user identification (``uid``) and group identification + (``gid``) values, set the variable as follows in your ``local.conf`` + file: USERADDEXTENSION = "useradd-staticids" + + .. note:: + + Setting this variable to use static + uid + and + gid + values causes the OpenEmbedded build system to employ the + useradd-staticids + class. + + If you use static ``uid`` and ``gid`` information, you must also + specify the ``files/passwd`` and ``files/group`` files by setting the + :term:`USERADD_UID_TABLES` and + :term:`USERADD_GID_TABLES` variables. + Additionally, you should also set the + :term:`USERADD_ERROR_DYNAMIC` variable. + + VOLATILE_LOG_DIR + Specifies the persistence of the target's ``/var/log`` directory, + which is used to house postinstall target log files. + + By default, ``VOLATILE_LOG_DIR`` is set to "yes", which means the + file is not persistent. You can override this setting by setting the + variable to "no" to make the log directory persistent. + + WARN_QA + Specifies the quality assurance checks whose failures are reported as + warnings by the OpenEmbedded build system. You set this variable in + your distribution configuration file. For a list of the checks you + can control with this variable, see the + ":ref:`insane.bbclass <ref-classes-insane>`" section. + + WKS_FILE_DEPENDS + When placed in the recipe that builds your image, this variable lists + build-time dependencies. The ``WKS_FILE_DEPENDS`` variable is only + applicable when Wic images are active (i.e. when + :term:`IMAGE_FSTYPES` contains entries related + to Wic). If your recipe does not create Wic images, the variable has + no effect. + + The ``WKS_FILE_DEPENDS`` variable is similar to the + :term:`DEPENDS` variable. When you use the variable in + your recipe that builds the Wic image, dependencies you list in the + ``WIC_FILE_DEPENDS`` variable are added to the ``DEPENDS`` variable. + + With the ``WKS_FILE_DEPENDS`` variable, you have the possibility to + specify a list of additional dependencies (e.g. native tools, + bootloaders, and so forth), that are required to build Wic images. + Following is an example: + :: + + WKS_FILE_DEPENDS = "some-native-tool" + + In the + previous example, some-native-tool would be replaced with an actual + native tool on which the build would depend. + + WKS_FILE + Specifies the location of the Wic kickstart file that is used by the + OpenEmbedded build system to create a partitioned image + (image\ ``.wic``). For information on how to create a partitioned + image, see the + ":ref:`dev-manual/dev-manual-common-tasks:creating partitioned images using wic`" + section in the Yocto Project Development Tasks Manual. For details on + the kickstart file format, see the ":doc:`../ref-manual/ref-kickstart`" Chapter. + + WORKDIR + The pathname of the work directory in which the OpenEmbedded build + system builds a recipe. This directory is located within the + :term:`TMPDIR` directory structure and is specific to + the recipe being built and the system for which it is being built. + + The ``WORKDIR`` directory is defined as follows: + :: + + ${TMPDIR}/work/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR} + + The actual directory depends on several things: + + - TMPDIR + : The top-level build output directory + - MULTIMACH_TARGET_SYS + : The target system identifier + - PN + : The recipe name + - EXTENDPE + : The epoch - (if + PE + is not specified, which is usually the case for most recipes, then + EXTENDPE + is blank) + - PV + : The recipe version + - PR + : The recipe revision + + As an example, assume a Source Directory top-level folder name + ``poky``, a default Build Directory at ``poky/build``, and a + ``qemux86-poky-linux`` machine target system. Furthermore, suppose + your recipe is named ``foo_1.3.0-r0.bb``. In this case, the work + directory the build system uses to build the package would be as + follows: + :: + + poky/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0 + + XSERVER + Specifies the packages that should be installed to provide an X + server and drivers for the current machine, assuming your image + directly includes ``packagegroup-core-x11-xserver`` or, perhaps + indirectly, includes "x11-base" in + :term:`IMAGE_FEATURES`. + + The default value of ``XSERVER``, if not specified in the machine + configuration, is "xserver-xorg xf86-video-fbdev xf86-input-evdev". + diff --git a/poky/documentation/ref-manual/ref-variables.xml b/poky/documentation/ref-manual/ref-variables.xml index 657f6cf3d..a5064807e 100644 --- a/poky/documentation/ref-manual/ref-variables.xml +++ b/poky/documentation/ref-manual/ref-variables.xml @@ -1,6 +1,7 @@ <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > +<!--SPDX-License-Identifier: CC-BY-2.0-UK--> <!-- Dummy chapter --> <chapter id='ref-variables-glos'> @@ -4990,6 +4991,30 @@ </glossdef> </glossentry> + <glossentry id='var-FIT_HASH_ALG'><glossterm>FIT_HASH_ALG</glossterm> + <info> + FIT_HASH_ALG[doc] = "Specifies the hash algorithm used in creating the FIT Image." + </info> + <glossdef> + <para role="glossdeffirst"> + Specifies the hash algorithm used in creating the FIT Image. + For e.g. sha256. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-FIT_SIGN_ALG'><glossterm>FIT_SIGN_ALG</glossterm> + <info> + FIT_SIGN_ALG[doc] = "Specifies the signature algorithm used in creating the FIT Image." + </info> + <glossdef> + <para role="glossdeffirst"> + Specifies the signature algorithm used in creating the FIT Image. + For e.g. rsa2048. + </para> + </glossdef> + </glossentry> + <glossentry id='var-FONT_EXTRA_RDEPENDS'><glossterm>FONT_EXTRA_RDEPENDS</glossterm> <info> FONT_EXTRA_RDEPENDS[doc] = "When a recipe inherits the fontcache class, this variable specifies runtime dependencies for font packages. This variable defaults to 'fontconfig-utils'." @@ -5702,7 +5727,7 @@ <para role="glossdeffirst"> A space-separated list of files installed into the boot partition when preparing an image using the Wic tool - with the <filename>bootimg-partition</filename> source + with the <filename>bootimg-partition</filename> or <filename>bootimg-efi</filename> source plugin. By default, the files are installed under the same name as the source files. @@ -15959,6 +15984,38 @@ </glossdef> </glossentry> + <glossentry id='var-UBOOT_DTB_LOADADDRESS'><glossterm>UBOOT_DTB_LOADADDRESS</glossterm> + <info> + UBOOT_DTB_LOADADDRESS[doc] = "Specifies the load address for the dtb." + </info> + <glossdef> + <para role="glossdeffirst"> + Specifies the load address for the dtb image used by U-boot. + During FIT image creation, the + <filename>UBOOT_DTB_LOADADDRESS</filename> variable is used + in <filename>kernel-fitimage</filename> class to specify the + load address to be used in creating the dtb sections of + Image Tree Source for the FIT image. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-UBOOT_DTBO_LOADADDRESS'><glossterm>UBOOT_DTBO_LOADADDRESS</glossterm> + <info> + UBOOT_DTBO_LOADADDRESS[doc] = "Specifies the load address for the dtbo." + </info> + <glossdef> + <para role="glossdeffirst"> + Specifies the load address for the dtbo image used by U-boot. + During FIT image creation, the + <filename>UBOOT_DTBO_LOADADDRESS</filename> variable is used + in <filename>kernel-fitimage</filename> class to specify the + load address to be used in creating the dtbo sections of + Image Tree Source for the FIT image. + </para> + </glossdef> + </glossentry> + <glossentry id='var-UBOOT_ENTRYPOINT'><glossterm>UBOOT_ENTRYPOINT</glossterm> <info> UBOOT_ENTRYPOINT[doc] = "Specifies the entry point for the U-Boot image." @@ -16044,6 +16101,51 @@ </glossdef> </glossentry> + <glossentry id='var-UBOOT_MKIMAGE_DTCOPTS'><glossterm>UBOOT_MKIMAGE_DTCOPTS</glossterm> + <info> + UBOOT_MKIMAGE_DTCOPTS[doc] = "Options for the device tree compiler passed to mkimage '-D' feature." + </info> + <glossdef> + <para role="glossdeffirst"> + Options for the device tree compiler passed to mkimage '-D' + feature while creating FIT image in + <filename>kernel-fitimage</filename> class. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-UBOOT_RD_LOADADDRESS'><glossterm>UBOOT_RD_LOADADDRESS</glossterm> + <info> + UBOOT_RD_LOADADDRESS[doc] = "Specifies the load address for the ramdisk image." + </info> + <glossdef> + <para role="glossdeffirst"> + Specifies the load address for the RAM disk image. + During FIT image creation, the + <filename>UBOOT_RD_LOADADDRESS</filename> variable is used + in <filename>kernel-fitimage</filename> class to specify the + load address to be used in creating the Image Tree Source for + the FIT image. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-UBOOT_RD_ENTRYPOINT'><glossterm>UBOOT_RD_ENTRYPOINT</glossterm> + <info> + UBOOT_RD_ENTRYPOINT[doc] = "Specifies the entrypoint for the ramdisk image." + </info> + <glossdef> + <para role="glossdeffirst"> + Specifies the entrypoint for the RAM disk image. + During FIT image creation, the + <filename>UBOOT_RD_ENTRYPOINT</filename> variable is used + in <filename>kernel-fitimage</filename> class to specify the + entrypoint to be used in creating the Image Tree Source for + the FIT image. + </para> + </glossdef> + </glossentry> + <glossentry id='var-UBOOT_SUFFIX'><glossterm>UBOOT_SUFFIX</glossterm> <info> UBOOT_SUFFIX[doc] = "Points to the generated U-Boot extension." @@ -16062,6 +16164,47 @@ </glossdef> </glossentry> + <glossentry id='var-UBOOT_SIGN_ENABLE'><glossterm>UBOOT_SIGN_ENABLE</glossterm> + <info> + UBOOT_SIGN_KEYDIR[doc] = "Enable signing of FIT image." + </info> + <glossdef> + <para role="glossdeffirst"> + Enable signing of FIT image. The default value is "0". + </para> + </glossdef> + </glossentry> + + <glossentry id='var-UBOOT_SIGN_KEYDIR'><glossterm>UBOOT_SIGN_KEYDIR</glossterm> + <info> + UBOOT_SIGN_KEYDIR[doc] = "Location of the directory containing the RSA key and certificate used for signing FIT image." + </info> + <glossdef> + <para role="glossdeffirst"> + Location of the directory containing the RSA key and + certificate used for signing FIT image. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-UBOOT_SIGN_KEYNAME'><glossterm>UBOOT_SIGN_KEYNAME</glossterm> + <info> + UBOOT_SIGN_KEYNAME[doc] = "The name of keys used for signing U-boot FIT image" + </info> + <glossdef> + <para role="glossdeffirst"> + The name of keys used for signing U-boot FIT image stored in + <filename><link linkend='var-UBOOT_SIGN_KEYDIR'>UBOOT_SIGN_KEYDIR</link></filename> + directory. For e.g. dev.key key and dev.crt certificate + stored in + <filename><link linkend='var-UBOOT_SIGN_KEYDIR'>UBOOT_SIGN_KEYDIR</link></filename> + directory will have + <filename><link linkend='var-UBOOT_SIGN_KEYNAME'>UBOOT_SIGN_KEYNAME</link></filename> + set to "dev". + </para> + </glossdef> + </glossentry> + <glossentry id='var-UBOOT_TARGET'><glossterm>UBOOT_TARGET</glossterm> <info> UBOOT_TARGET[doc] = "Specifies the target used for building U-Boot." diff --git a/poky/documentation/ref-manual/ref-varlocality.rst b/poky/documentation/ref-manual/ref-varlocality.rst new file mode 100644 index 000000000..a95504b57 --- /dev/null +++ b/poky/documentation/ref-manual/ref-varlocality.rst @@ -0,0 +1,166 @@ +.. SPDX-License-Identifier: CC-BY-2.0-UK + +**************** +Variable Context +**************** + +While you can use most variables in almost any context such as +``.conf``, ``.bbclass``, ``.inc``, and ``.bb`` files, some variables are +often associated with a particular locality or context. This chapter +describes some common associations. + +.. _ref-varlocality-configuration: + +Configuration +============= + +The following subsections provide lists of variables whose context is +configuration: distribution, machine, and local. + +.. _ref-varlocality-config-distro: + +Distribution (Distro) +--------------------- + +This section lists variables whose configuration context is the +distribution, or distro. + +- :term:`DISTRO` + +- :term:`DISTRO_NAME` + +- :term:`DISTRO_VERSION` + +- :term:`MAINTAINER` + +- :term:`PACKAGE_CLASSES` + +- :term:`TARGET_OS` + +- :term:`TARGET_FPU` + +- :term:`TCMODE` + +- :term:`TCLIBC` + +.. _ref-varlocality-config-machine: + +Machine +------- + +This section lists variables whose configuration context is the machine. + +- :term:`TARGET_ARCH` + +- :term:`SERIAL_CONSOLES` + +- :term:`PACKAGE_EXTRA_ARCHS` + +- :term:`IMAGE_FSTYPES` + +- :term:`MACHINE_FEATURES` + +- :term:`MACHINE_EXTRA_RDEPENDS` + +- :term:`MACHINE_EXTRA_RRECOMMENDS` + +- :term:`MACHINE_ESSENTIAL_EXTRA_RDEPENDS` + +- :term:`MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS` + +.. _ref-varlocality-config-local: + +Local +----- + +This section lists variables whose configuration context is the local +configuration through the ``local.conf`` file. + +- :term:`DISTRO` + +- :term:`MACHINE` + +- :term:`DL_DIR` + +- :term:`BBFILES` + +- :term:`EXTRA_IMAGE_FEATURES` + +- :term:`PACKAGE_CLASSES` + +- :term:`BB_NUMBER_THREADS` + +- :term:`BBINCLUDELOGS` + +- :term:`ENABLE_BINARY_LOCALE_GENERATION` + +.. _ref-varlocality-recipes: + +Recipes +======= + +The following subsections provide lists of variables whose context is +recipes: required, dependencies, path, and extra build information. + +.. _ref-varlocality-recipe-required: + +Required +-------- + +This section lists variables that are required for recipes. + +- :term:`LICENSE` + +- :term:`LIC_FILES_CHKSUM` + +- :term:`SRC_URI` - used in recipes that fetch local or remote files. + +.. _ref-varlocality-recipe-dependencies: + +Dependencies +------------ + +This section lists variables that define recipe dependencies. + +- :term:`DEPENDS` + +- :term:`RDEPENDS` + +- :term:`RRECOMMENDS` + +- :term:`RCONFLICTS` + +- :term:`RREPLACES` + +.. _ref-varlocality-recipe-paths: + +Paths +----- + +This section lists variables that define recipe paths. + +- :term:`WORKDIR` + +- :term:`S` + +- :term:`FILES` + +.. _ref-varlocality-recipe-build: + +Extra Build Information +----------------------- + +This section lists variables that define extra build information for +recipes. + +- :term:`DEFAULT_PREFERENCE` + +- :term:`EXTRA_OECMAKE` + +- :term:`EXTRA_OECONF` + +- :term:`EXTRA_OEMAKE` + +- :term:`PACKAGECONFIG_CONFARGS` + +- :term:`PACKAGES` diff --git a/poky/documentation/ref-manual/ref-varlocality.xml b/poky/documentation/ref-manual/ref-varlocality.xml index 54524d5b6..a2436fb31 100644 --- a/poky/documentation/ref-manual/ref-varlocality.xml +++ b/poky/documentation/ref-manual/ref-varlocality.xml @@ -1,6 +1,7 @@ <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > +<!--SPDX-License-Identifier: CC-BY-2.0-UK--> <chapter id='ref-varlocality'> <title>Variable Context</title> diff --git a/poky/documentation/ref-manual/resources.rst b/poky/documentation/ref-manual/resources.rst new file mode 100644 index 000000000..2b82b7910 --- /dev/null +++ b/poky/documentation/ref-manual/resources.rst @@ -0,0 +1,197 @@ +.. SPDX-License-Identifier: CC-BY-2.0-UK + +**************************************** +Contributions and Additional Information +**************************************** + +.. _resources-intro: + +Introduction +============ + +The Yocto Project team is happy for people to experiment with the Yocto +Project. A number of places exist to find help if you run into +difficulties or find bugs. This presents information about contributing +and participating in the Yocto Project. + +.. _resources-contributions: + +Contributions +============= + +The Yocto Project gladly accepts contributions. You can submit changes +to the project either by creating and sending pull requests, or by +submitting patches through email. For information on how to do both as +well as information on how to identify the maintainer for each area of +code, see the ":ref:`how-to-submit-a-change`" section in the +Yocto Project Development Tasks Manual. + +.. _resources-bugtracker: + +Yocto Project Bugzilla +====================== + +The Yocto Project uses its own implementation of +:yocto_bugs:`Bugzilla <>` to track defects (bugs). +Implementations of Bugzilla work well for group development because they +track bugs and code changes, can be used to communicate changes and +problems with developers, can be used to submit and review patches, and +can be used to manage quality assurance. + +Sometimes it is helpful to submit, investigate, or track a bug against +the Yocto Project itself (e.g. when discovering an issue with some +component of the build system that acts contrary to the documentation or +your expectations). + +A general procedure and guidelines exist for when you use Bugzilla to +submit a bug. For information on how to use Bugzilla to submit a bug +against the Yocto Project, see the following: + +- The ":ref:`dev-manual/dev-manual-common-tasks:submitting a defect against the yocto project`" + section in the Yocto Project Development Tasks Manual. + +- The Yocto Project :yocto_wiki:`Bugzilla wiki page </wiki/Bugzilla_Configuration_and_Bug_Tracking>` + +For information on Bugzilla in general, see http://www.bugzilla.org/about/. + +.. _resources-mailinglist: + +Mailing lists +============= + +A number of mailing lists maintained by the Yocto Project exist as well +as related OpenEmbedded mailing lists for discussion, patch submission +and announcements. To subscribe to one of the following mailing lists, +click on the appropriate URL in the following list and follow the +instructions: + +- https://lists.yoctoproject.org/g/yocto - General Yocto Project + discussion mailing list. + +- https://lists.openembedded.org/g/openembedded-core - Discussion mailing + list about OpenEmbedded-Core (the core metadata). + +- https://lists.openembedded.org/g/openembedded-devel - Discussion + mailing list about OpenEmbedded. + +- https://lists.openembedded.org/g/bitbake-devel - Discussion mailing + list about the :term:`BitBake` build tool. + +- https://lists.yoctoproject.org/g/poky - Discussion mailing list + about `Poky <#poky>`__. + +- https://lists.yoctoproject.org/g/yocto-announce - Mailing list to + receive official Yocto Project release and milestone announcements. + +For more Yocto Project-related mailing lists, see the +Yocto Project Website +. +.. _resources-irc: + +Internet Relay Chat (IRC) +========================= + +Two IRC channels on freenode are available for the Yocto Project and +Poky discussions: + +- ``#yocto`` + +- ``#poky`` + +.. _resources-links-and-related-documentation: + +Links and Related Documentation +=============================== + +Here is a list of resources you might find helpful: + +- :yocto_home:`The Yocto Project Website <>`\ *:* The home site + for the Yocto Project. + +- :yocto_wiki:`The Yocto Project Main Wiki Page </wiki/Main_Page>`\ *:* The main wiki page for + the Yocto Project. This page contains information about project + planning, release engineering, QA & automation, a reference site map, + and other resources related to the Yocto Project. + +- `OpenEmbedded <http://www.openembedded.org/>`__\ *:* The build system used by the + Yocto Project. This project is the upstream, generic, embedded + distribution from which the Yocto Project derives its build system + (Poky) and to which it contributes. + +- `BitBake <http://www.openembedded.org/wiki/BitBake>`__\ *:* The tool + used to process metadata. + +- :doc:`BitBake User Manual <bitbake:index>`\ *:* A comprehensive + guide to the BitBake tool. If you want information on BitBake, see + this manual. + +- :doc:`../brief-yoctoprojectqs/brief-yoctoprojectqs` *:* This + short document lets you experience building an image using the Yocto + Project without having to understand any concepts or details. + +- :doc:`../overview-manual/overview-manual` *:* This manual provides overview + and conceptual information about the Yocto Project. + +- :doc:`../dev-manual/dev-manual` *:* This manual is a "how-to" guide + that presents procedures useful to both application and system + developers who use the Yocto Project. + +- :doc:`../sdk-manual/sdk-manual` *manual :* This + guide provides information that lets you get going with the standard + or extensible SDK. An SDK, with its cross-development toolchains, + allows you to develop projects inside or outside of the Yocto Project + environment. + +- :doc:`../bsp-guide/bsp` *:* This guide defines the structure + for BSP components. Having a commonly understood structure encourages + standardization. + +- :doc:`../kernel-dev/kernel-dev` *:* This manual describes + how to work with Linux Yocto kernels as well as provides a bit of + conceptual information on the construction of the Yocto Linux kernel + tree. + +- :doc:`../ref-manual/ref-manual` *:* This + manual provides reference material such as variable, task, and class + descriptions. + +- `Yocto Project Mega-Manual <https://docs.yoctoproject.org/singleindex.html>`__\ *:* This manual + is simply a single HTML file comprised of the bulk of the Yocto + Project manuals. The Mega-Manual primarily exists as a vehicle by + which you can easily search for phrases and terms used in the Yocto + Project documentation set. + +- :doc:`../profile-manual/profile-manual` *:* This manual presents a set of + common and generally useful tracing and profiling schemes along with + their applications (as appropriate) to each tool. + +- :doc:`../toaster-manual/toaster-manual` *:* This manual + introduces and describes how to set up and use Toaster. Toaster is an + Application Programming Interface (API) and web-based interface to + the :term:`OpenEmbedded Build System`, which uses + BitBake, that reports build information. + +- :yocto_wiki:`FAQ </wiki/FAQ>`\ *:* A list of commonly asked + questions and their answers. + +- *Release Notes:* Features, updates and known issues for the current + release of the Yocto Project. To access the Release Notes, go to the + :yocto_home:`Downloads </software-overview/downloads>` page on + the Yocto Project website and click on the "RELEASE INFORMATION" link + for the appropriate release. + +- `Bugzilla <https://bugzilla.yoctoproject.org>`__\ *:* The bug tracking application + the Yocto Project uses. If you find problems with the Yocto Project, + you should report them using this application. + +- :yocto_wiki:`Bugzilla Configuration and Bug Tracking Wiki Page </wiki/Bugzilla_Configuration_and_Bug_Tracking>`\ *:* + Information on how to get set up and use the Yocto Project + implementation of Bugzilla for logging and tracking Yocto Project + defects. + +- *Internet Relay Chat (IRC):* Two IRC channels on freenode are + available for Yocto Project and Poky discussions: ``#yocto`` and + ``#poky``, respectively. + +- `Quick EMUlator (QEMU) <http://wiki.qemu.org/Index.html>`__\ *:* An + open-source machine emulator and virtualizer. diff --git a/poky/documentation/ref-manual/resources.xml b/poky/documentation/ref-manual/resources.xml index afe8e288d..4899b2e59 100644 --- a/poky/documentation/ref-manual/resources.xml +++ b/poky/documentation/ref-manual/resources.xml @@ -1,6 +1,7 @@ <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > +<!--SPDX-License-Identifier: CC-BY-2.0-UK--> <chapter id='resources'> <title>Contributions and Additional Information</title> |