diff options
Diffstat (limited to 'poky/documentation/ref-manual/migration.xml')
| -rw-r--r-- | poky/documentation/ref-manual/migration.xml | 5684 |
1 files changed, 5684 insertions, 0 deletions
diff --git a/poky/documentation/ref-manual/migration.xml b/poky/documentation/ref-manual/migration.xml new file mode 100644 index 000000000..b06096800 --- /dev/null +++ b/poky/documentation/ref-manual/migration.xml @@ -0,0 +1,5684 @@ +<!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; ] > + +<chapter id='migration'> +<title>Migrating to a Newer Yocto Project Release</title> + + <para> + 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. + </para> + +<section id='general-migration-considerations'> + <title>General Migration Considerations</title> + + <para> + 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. + <itemizedlist> + <listitem><para><emphasis>Dealing with Customized Recipes</emphasis>: + 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. + </para> + + <para>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.</para> + + <para>The better solution (where practical) is to use append + files (<filename>*.bbappend</filename>) 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.</para> + </listitem> + <listitem><para><emphasis>Updating Append Files</emphasis>: + Since append files generally only contain your customizations, + they often do not need to be adjusted for new releases. + However, if the <filename>.bbappend</filename> 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 (<filename>.bb</filename>) will + trigger an error during parsing.</para> + <para>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. + </para></listitem> + </itemizedlist> + </para> +</section> + +<section id='moving-to-the-yocto-project-1.3-release'> + <title>Moving to the Yocto Project 1.3 Release</title> + + <para> + This section provides migration information for moving to the + Yocto Project 1.3 Release from the prior release. + </para> + + <section id='1.3-local-configuration'> + <title>Local Configuration</title> + + <para> + Differences include changes for + <link linkend='var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></link> + and <filename>bblayers.conf</filename>. + </para> + + <section id='migration-1.3-sstate-mirrors'> + <title>SSTATE_MIRRORS</title> + + <para> + The shared state cache (sstate-cache), as pointed to by + <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link>, + 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 + <link linkend='var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></link>, + 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: + <literallayout class='monospaced'> + SSTATE_MIRRORS = "file://.* http://<replaceable>someserver</replaceable>.tld/share/sstate/PATH" + </literallayout> + </para> + </section> + + <section id='migration-1.3-bblayers-conf'> + <title>bblayers.conf</title> + + <para> + The <filename>meta-yocto</filename> layer consists of two parts + that correspond to the Poky reference distribution and the + reference hardware Board Support Packages (BSPs), respectively: + <filename>meta-yocto</filename> and + <filename>meta-yocto-bsp</filename>. + When running BitBake for the first time after upgrading, + your <filename>conf/bblayers.conf</filename> file will be + updated to handle this change and you will be asked to + re-run or restart for the changes to take effect. + </para> + </section> + </section> + + <section id='1.3-recipes'> + <title>Recipes</title> + + <para> + Differences include changes for the following: + <itemizedlist> + <listitem><para>Python function whitespace</para></listitem> + <listitem><para><filename>proto=</filename> in <filename>SRC_URI</filename></para></listitem> + <listitem><para><filename>nativesdk</filename></para></listitem> + <listitem><para>Task recipes</para></listitem> + <listitem><para><filename>IMAGE_FEATURES</filename></para></listitem> + <listitem><para>Removed recipes</para></listitem> + </itemizedlist> + </para> + + <section id='migration-1.3-python-function-whitespace'> + <title>Python Function Whitespace</title> + + <para> + 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 + <filename>_append</filename> or <filename>_prepend</filename> + complicated given that Python treats whitespace as + syntactically significant. + If you are defining or extending any Python functions (e.g. + <filename>populate_packages</filename>, <filename>do_unpack</filename>, + <filename>do_patch</filename> and so forth) in custom recipes + or classes, you need to ensure you are using consistent + four-space indentation. + </para> + </section> + + <section id='migration-1.3-proto=-in-src-uri'> + <title>proto= in SRC_URI</title> + + <para> + Any use of <filename>proto=</filename> in + <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link> + needs to be changed to <filename>protocol=</filename>. + In particular, this applies to the following URIs: + <itemizedlist> + <listitem><para><filename>svn://</filename></para></listitem> + <listitem><para><filename>bzr://</filename></para></listitem> + <listitem><para><filename>hg://</filename></para></listitem> + <listitem><para><filename>osc://</filename></para></listitem> + </itemizedlist> + Other URIs were already using <filename>protocol=</filename>. + This change improves consistency. + </para> + </section> + + <section id='migration-1.3-nativesdk'> + <title>nativesdk</title> + + <para> + The suffix <filename>nativesdk</filename> is now implemented + as a prefix, which simplifies a lot of the packaging code for + <filename>nativesdk</filename> recipes. + All custom <filename>nativesdk</filename> recipes, which are + relocatable packages that are native to + <link linkend='var-SDK_ARCH'><filename>SDK_ARCH</filename></link>, + and any references need to be updated to use + <filename>nativesdk-*</filename> instead of + <filename>*-nativesdk</filename>. + </para> + </section> + + <section id='migration-1.3-task-recipes'> + <title>Task Recipes</title> + + <para> + "Task" recipes are now known as "Package groups" and have + been renamed from <filename>task-*.bb</filename> to + <filename>packagegroup-*.bb</filename>. + Existing references to the previous <filename>task-*</filename> + 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 <filename>task-*</filename> + recipes to <filename>packagegroup-*</filename>, and change + them to inherit <filename>packagegroup</filename> instead of + <filename>task</filename>, as well as taking the opportunity + to remove anything now handled by + <filename>packagegroup.bbclass</filename>, such as providing + <filename>-dev</filename> and <filename>-dbg</filename> + packages, setting + <link linkend='var-LIC_FILES_CHKSUM'><filename>LIC_FILES_CHKSUM</filename></link>, + and so forth. + See the + "<link linkend='ref-classes-packagegroup'><filename>packagegroup.bbclass</filename></link>" + section for further details. + </para> + </section> + + <section id='migration-1.3-image-features'> + <title>IMAGE_FEATURES</title> + + <para> + Image recipes that previously included "apps-console-core" + in <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link> + 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" + <filename>IMAGE_FEATURES</filename> features have been removed. + </para> + </section> + + <section id='migration-1.3-removed-recipes'> + <title>Removed Recipes</title> + + <para> + The following recipes have been removed. + For most of them, it is unlikely that you would have any + references to them in your own + <link linkend='metadata'>Metadata</link>. + However, you should check your metadata against this list to be sure: + <itemizedlist> + <listitem><para><emphasis><filename>libx11-trim</filename></emphasis>: + Replaced by <filename>libx11</filename>, which has a negligible + size difference with modern Xorg.</para></listitem> + <listitem><para><emphasis><filename>xserver-xorg-lite</filename></emphasis>: + Use <filename>xserver-xorg</filename>, which has a negligible + size difference when DRI and GLX modules are not installed.</para></listitem> + <listitem><para><emphasis><filename>xserver-kdrive</filename></emphasis>: + Effectively unmaintained for many years.</para></listitem> + <listitem><para><emphasis><filename>mesa-xlib</filename></emphasis>: + No longer serves any purpose.</para></listitem> + <listitem><para><emphasis><filename>galago</filename></emphasis>: + Replaced by telepathy.</para></listitem> + <listitem><para><emphasis><filename>gail</filename></emphasis>: + Functionality was integrated into GTK+ 2.13.</para></listitem> + <listitem><para><emphasis><filename>eggdbus</filename></emphasis>: + No longer needed.</para></listitem> + <listitem><para><emphasis><filename>gcc-*-intermediate</filename></emphasis>: + The build has been restructured to avoid the need for + this step.</para></listitem> + <listitem><para><emphasis><filename>libgsmd</filename></emphasis>: + Unmaintained for many years. + Functionality now provided by + <filename>ofono</filename> instead.</para></listitem> + <listitem><para><emphasis>contacts, dates, tasks, eds-tools</emphasis>: + Largely unmaintained PIM application suite. + It has been moved to <filename>meta-gnome</filename> + in <filename>meta-openembedded</filename>.</para></listitem> + </itemizedlist> + In addition to the previously listed changes, the + <filename>meta-demoapps</filename> 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 + <filename>meta-oe</filename> and <filename>meta-gnome</filename>. + For the remainder, you can now find them in the + <filename>meta-extras</filename> repository, which is in the + Yocto Project + <ulink url='&YOCTO_DOCS_OM_URL;#source-repositories'>Source Repositories</ulink>. + </para> + </section> + </section> + + <section id='1.3-linux-kernel-naming'> + <title>Linux Kernel Naming</title> + + <para> + The naming scheme for kernel output binaries has been changed to + now include + <link linkend='var-PE'><filename>PE</filename></link> as part of the + filename: + <literallayout class='monospaced'> + KERNEL_IMAGE_BASE_NAME ?= "${KERNEL_IMAGETYPE}-${PE}-${PV}-${PR}-${MACHINE}-${DATETIME}" + </literallayout> + </para> + + <para> + Because the <filename>PE</filename> variable is not set by default, + these binary files could result with names that include two dash + characters. + Here is an example: + <literallayout class='monospaced'> + bzImage--3.10.9+git0+cd502a8814_7144bcc4b8-r0-qemux86-64-20130830085431.bin + </literallayout> + </para> + </section> +</section> + +<section id='moving-to-the-yocto-project-1.4-release'> + <title>Moving to the Yocto Project 1.4 Release</title> + + <para> + This section provides migration information for moving to the + Yocto Project 1.4 Release from the prior release. + </para> + + <section id='migration-1.4-bitbake'> + <title>BitBake</title> + + <para> + Differences include the following: + <itemizedlist> + <listitem><para><emphasis>Comment Continuation:</emphasis> + 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. + </para></listitem> + <listitem><para><emphasis>Package Name Overrides:</emphasis> + The runtime package specific variables + <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>, + <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>, + <link linkend='var-RSUGGESTS'><filename>RSUGGESTS</filename></link>, + <link linkend='var-RPROVIDES'><filename>RPROVIDES</filename></link>, + <link linkend='var-RCONFLICTS'><filename>RCONFLICTS</filename></link>, + <link linkend='var-RREPLACES'><filename>RREPLACES</filename></link>, + <link linkend='var-FILES'><filename>FILES</filename></link>, + <link linkend='var-ALLOW_EMPTY'><filename>ALLOW_EMPTY</filename></link>, + and the pre, post, install, and uninstall script functions + <filename>pkg_preinst</filename>, + <filename>pkg_postinst</filename>, + <filename>pkg_prerm</filename>, and + <filename>pkg_postrm</filename> should always have a + package name override. + For example, use <filename>RDEPENDS_${PN}</filename> for + the main package instead of <filename>RDEPENDS</filename>. + BitBake uses more strict checks when it parses recipes. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-1.4-build-behavior'> + <title>Build Behavior</title> + + <para> + Differences include the following: + <itemizedlist> + <listitem><para><emphasis>Shared State Code:</emphasis> + 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: + <literallayout class='monospaced'> + $ bitbake -c rootfs <replaceable>some-image</replaceable> + </literallayout> + 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. + </para></listitem> + <listitem><para><emphasis>Scanning Directory Names:</emphasis> + When scanning for files in + <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>, + the build system now uses + <link linkend='var-FILESOVERRIDES'><filename>FILESOVERRIDES</filename></link> + instead of <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link> + for the directory names. + In general, the values previously in + <filename>OVERRIDES</filename> are now in + <filename>FILESOVERRIDES</filename> as well. + However, if you relied upon an additional value + you previously added to <filename>OVERRIDES</filename>, + you might now need to add it to + <filename>FILESOVERRIDES</filename> unless you are already + adding it through the + <link linkend='var-MACHINEOVERRIDES'><filename>MACHINEOVERRIDES</filename></link> + or <link linkend='var-DISTROOVERRIDES'><filename>DISTROOVERRIDES</filename></link> + variables, as appropriate. + For more related changes, see the + "<link linkend='migration-1.4-variables'>Variables</link>" + section. + </para></listitem> + </itemizedlist> + </para> + </section> + + + <section id='migration-1.4-proxies-and-fetching-source'> + <title>Proxies and Fetching Source</title> + + <para> + A new <filename>oe-git-proxy</filename> script has been added to + replace previous methods of handling proxies and fetching source + from Git. + See the <filename>meta-yocto/conf/site.conf.sample</filename> file + for information on how to use this script. + </para> + </section> + + <section id='migration-1.4-custom-interfaces-file-netbase-change'> + <title>Custom Interfaces File (netbase change)</title> + + <para> + If you have created your own custom + <filename>etc/network/interfaces</filename> file by creating + an append file for the <filename>netbase</filename> recipe, + you now need to create an append file for the + <filename>init-ifupdown</filename> recipe instead, which you can + find in the + <link linkend='source-directory'>Source Directory</link> + at <filename>meta/recipes-core/init-ifupdown</filename>. + For information on how to use append files, see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#using-bbappend-files'>Using .bbappend Files</ulink>" + section in the Yocto Project Development Tasks Manual. + </para> + </section> + + <section id='migration-1.4-remote-debugging'> + <title>Remote Debugging</title> + + <para> + Support for remote debugging with the Eclipse IDE is now + separated into an image feature + (<filename>eclipse-debug</filename>) that corresponds to the + <filename>packagegroup-core-eclipse-debug</filename> package group. + Previously, the debugging feature was included through the + <filename>tools-debug</filename> image feature, which corresponds + to the <filename>packagegroup-core-tools-debug</filename> + package group. + </para> + </section> + + <section id='migration-1.4-variables'> + <title>Variables</title> + + <para> + The following variables have changed: + <itemizedlist> + <listitem><para><emphasis><filename>SANITY_TESTED_DISTROS</filename>:</emphasis> + This variable now uses a distribution ID, which is composed + of the host distributor ID followed by the release. + Previously, + <link linkend='var-SANITY_TESTED_DISTROS'><filename>SANITY_TESTED_DISTROS</filename></link> + 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 "". + </para></listitem> + <listitem><para><emphasis><filename>SRC_URI</filename>:</emphasis> + The <filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}</filename>, + <filename>${</filename><link linkend='var-PF'><filename>PF</filename></link><filename>}</filename>, + <filename>${</filename><link linkend='var-P'><filename>P</filename></link><filename>}</filename>, + and <filename>FILE_DIRNAME</filename> directories have been + dropped from the default value of the + <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link> + variable, which is used as the search path for finding files + referred to in + <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>. + 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 + <filename>${BP}</filename>, <filename>${BPN}</filename>, + and "files", which all remain in the default value of + <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-target-package-management-with-rpm'> + <title>Target Package Management with RPM</title> + + <para> + 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: + <literallayout class='monospaced'> + smart --help + </literallayout> + </para> + </section> + + <section id='migration-1.4-recipes-moved'> + <title>Recipes Moved</title> + + <para> + The following recipes were moved from their previous locations + because they are no longer used by anything in + the OpenEmbedded-Core: + <itemizedlist> + <listitem><para><emphasis><filename>clutter-box2d</filename>:</emphasis> + Now resides in the <filename>meta-oe</filename> layer. + </para></listitem> + <listitem><para><emphasis><filename>evolution-data-server</filename>:</emphasis> + Now resides in the <filename>meta-gnome</filename> layer. + </para></listitem> + <listitem><para><emphasis><filename>gthumb</filename>:</emphasis> + Now resides in the <filename>meta-gnome</filename> layer. + </para></listitem> + <listitem><para><emphasis><filename>gtkhtml2</filename>:</emphasis> + Now resides in the <filename>meta-oe</filename> layer. + </para></listitem> + <listitem><para><emphasis><filename>gupnp</filename>:</emphasis> + Now resides in the <filename>meta-multimedia</filename> layer. + </para></listitem> + <listitem><para><emphasis><filename>gypsy</filename>:</emphasis> + Now resides in the <filename>meta-oe</filename> layer. + </para></listitem> + <listitem><para><emphasis><filename>libcanberra</filename>:</emphasis> + Now resides in the <filename>meta-gnome</filename> layer. + </para></listitem> + <listitem><para><emphasis><filename>libgdata</filename>:</emphasis> + Now resides in the <filename>meta-gnome</filename> layer. + </para></listitem> + <listitem><para><emphasis><filename>libmusicbrainz</filename>:</emphasis> + Now resides in the <filename>meta-multimedia</filename> layer. + </para></listitem> + <listitem><para><emphasis><filename>metacity</filename>:</emphasis> + Now resides in the <filename>meta-gnome</filename> layer. + </para></listitem> + <listitem><para><emphasis><filename>polkit</filename>:</emphasis> + Now resides in the <filename>meta-oe</filename> layer. + </para></listitem> + <listitem><para><emphasis><filename>zeroconf</filename>:</emphasis> + Now resides in the <filename>meta-networking</filename> layer. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-1.4-removals-and-renames'> + <title>Removals and Renames</title> + + <para> + The following list shows what has been removed or renamed: + <itemizedlist> + <listitem><para><emphasis><filename>evieext</filename>:</emphasis> + Removed because it has been removed from + <filename>xserver</filename> since 2008. + </para></listitem> + <listitem><para><emphasis>Gtk+ DirectFB:</emphasis> + Removed support because upstream Gtk+ no longer supports it + as of version 2.18. + </para></listitem> + <listitem><para><emphasis><filename>libxfontcache / xfontcacheproto</filename>:</emphasis> + Removed because they were removed from the Xorg server in 2008. + </para></listitem> + <listitem><para><emphasis><filename>libxp / libxprintapputil / libxprintutil / printproto</filename>:</emphasis> + Removed because the XPrint server was removed from + Xorg in 2008. + </para></listitem> + <listitem><para><emphasis><filename>libxtrap / xtrapproto</filename>:</emphasis> + Removed because their functionality was broken upstream. + </para></listitem> + <listitem><para><emphasis>linux-yocto 3.0 kernel:</emphasis> + 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. + </para></listitem> + <listitem><para><emphasis><filename>lsbsetup</filename>:</emphasis> + Removed with functionality now provided by + <filename>lsbtest</filename>. + </para></listitem> + <listitem><para><emphasis><filename>matchbox-stroke</filename>:</emphasis> + Removed because it was never more than a proof-of-concept. + </para></listitem> + <listitem><para><emphasis><filename>matchbox-wm-2 / matchbox-theme-sato-2</filename>:</emphasis> + Removed because they are not maintained. + However, <filename>matchbox-wm</filename> and + <filename>matchbox-theme-sato</filename> are still + provided. + </para></listitem> + <listitem><para><emphasis><filename>mesa-dri</filename>:</emphasis> + Renamed to <filename>mesa</filename>. + </para></listitem> + <listitem><para><emphasis><filename>mesa-xlib</filename>:</emphasis> + Removed because it was no longer useful. + </para></listitem> + <listitem><para><emphasis><filename>mutter</filename>:</emphasis> + Removed because nothing ever uses it and the recipe is + very old. + </para></listitem> + <listitem><para><emphasis><filename>orinoco-conf</filename>:</emphasis> + Removed because it has become obsolete. + </para></listitem> + <listitem><para><emphasis><filename>update-modules</filename>:</emphasis> + Removed because it is no longer used. + The kernel module <filename>postinstall</filename> and + <filename>postrm</filename> scripts can now do the same + task without the use of this script. + </para></listitem> + <listitem><para><emphasis><filename>web</filename>:</emphasis> + Removed because it is not maintained. Superseded by + <filename>web-webkit</filename>. + </para></listitem> + <listitem><para><emphasis><filename>xf86bigfontproto</filename>:</emphasis> + Removed because upstream it has been disabled by default + since 2007. + Nothing uses <filename>xf86bigfontproto</filename>. + </para></listitem> + <listitem><para><emphasis><filename>xf86rushproto</filename>:</emphasis> + Removed because its dependency in + <filename>xserver</filename> was spurious and it was + removed in 2005. + </para></listitem> + <listitem><para><emphasis><filename>zypper / libzypp / sat-solver</filename>:</emphasis> + Removed and been functionally replaced with Smart + (<filename>python-smartpm</filename>) when RPM packaging + is used and package management is enabled on the target. + </para></listitem> + </itemizedlist> + </para> + </section> +</section> + +<section id='moving-to-the-yocto-project-1.5-release'> + <title>Moving to the Yocto Project 1.5 Release</title> + + <para> + This section provides migration information for moving to the + Yocto Project 1.5 Release from the prior release. + </para> + + <section id='migration-1.5-host-dependency-changes'> + <title>Host Dependency Changes</title> + + <para> + The OpenEmbedded build system now has some additional requirements + on the host system: + <itemizedlist> + <listitem><para>Python 2.7.3+</para></listitem> + <listitem><para>Tar 1.24+</para></listitem> + <listitem><para>Git 1.7.8+</para></listitem> + <listitem><para>Patched version of Make if you are using + 3.82. + Most distributions that provide Make 3.82 use the patched + version.</para></listitem> + </itemizedlist> + 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. + </para> + + <para> + For more information on this requirement, see the + "<link linkend='required-git-tar-and-python-versions'>Required Git, tar, and Python Versions</link>" + section. + </para> + </section> + + <section id='migration-1.5-atom-pc-bsp'> + <title><filename>atom-pc</filename> Board Support Package (BSP)</title> + + <para> + The <filename>atom-pc</filename> hardware reference BSP has been + replaced by a <filename>genericx86</filename> 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 + <filename>atom-pc</filename> did. + <note> + Additionally, a <filename>genericx86-64</filename> BSP has + been added for 64-bit Atom systems. + </note> + </para> + </section> + + <section id='migration-1.5-bitbake'> + <title>BitBake</title> + + <para> + The following changes have been made that relate to BitBake: + <itemizedlist> + <listitem><para> + BitBake now supports a <filename>_remove</filename> + operator. + The addition of this operator means you will have to + rename any items in recipe space (functions, variables) + whose names currently contain + <filename>_remove_</filename> or end with + <filename>_remove</filename> to avoid unexpected behavior. + </para></listitem> + <listitem><para> + 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.</para></listitem> + <listitem><para> + The "none" server backend has been removed. + The "process" server backend has been serving well as the + default for a long time now.</para></listitem> + <listitem><para> + The <filename>bitbake-runtask</filename> script has been + removed.</para></listitem> + <listitem><para> + <filename>${</filename><link linkend='var-P'><filename>P</filename></link><filename>}</filename> + and + <filename>${</filename><link linkend='var-PF'><filename>PF</filename></link><filename>}</filename> + are no longer added to + <link linkend='var-PROVIDES'><filename>PROVIDES</filename></link> + by default in <filename>bitbake.conf</filename>. + These version-specific <filename>PROVIDES</filename> + 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.</para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-1.5-qa-warnings'> + <title>QA Warnings</title> + + <para> + The following changes have been made to the package QA checks: + <itemizedlist> + <listitem><para> + If you have customized + <link linkend='var-ERROR_QA'><filename>ERROR_QA</filename></link> + or <link linkend='var-WARN_QA'><filename>WARN_QA</filename></link> + 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 <filename>ERROR_QA</filename> + or <filename>WARN_QA</filename> would be treated as a + warning. + Consequently, several important items were not already in + the default value of <filename>WARN_QA</filename>. + All of the possible QA checks are now documented in the + "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>" + section.</para></listitem> + <listitem><para> + An additional QA check has been added to check if + <filename>/usr/share/info/dir</filename> is being installed. + Your recipe should delete this file within + <link linkend='ref-tasks-install'><filename>do_install</filename></link> + if "make install" is installing it. + </para></listitem> + <listitem><para> + 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 + <filename>ERROR_QA</filename> or + <filename>WARN_QA</filename> 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 + "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>" + section. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-1.5-directory-layout-changes'> + <title>Directory Layout Changes</title> + + <para> + The following directory changes exist: + <itemizedlist> + <listitem><para> + Output SDK installer files are now named to include the + image name and tuning architecture through the + <link linkend='var-SDK_NAME'><filename>SDK_NAME</filename></link> + variable.</para></listitem> + <listitem><para> + 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 + <link linkend='var-DEPLOY_DIR_IMAGE'><filename>DEPLOY_DIR_IMAGE</filename></link> + variable continues to point to the directory containing + images for the current + <link linkend='var-MACHINE'><filename>MACHINE</filename></link> + and should be used anywhere there is a need to refer to + this directory. + The <filename>runqemu</filename> script now uses this + variable to find images and kernel binaries and will use + BitBake to determine the directory. + Alternatively, you can set the + <filename>DEPLOY_DIR_IMAGE</filename> variable in the + external environment.</para></listitem> + <listitem><para> + When buildhistory is enabled, its output is now written + under the + <link linkend='build-directory'>Build Directory</link> + rather than + <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>. + Doing so makes it easier to delete + <filename>TMPDIR</filename> and preserve the build history. + Additionally, data for produced SDKs is now split by + <link linkend='var-IMAGE_NAME'><filename>IMAGE_NAME</filename></link>. + </para></listitem> + <listitem><para> + The <filename>pkgdata</filename> directory produced as + part of the packaging process has been collapsed into a + single machine-specific directory. + This directory is located under + <filename>sysroots</filename> and uses a machine-specific + name (i.e. + <filename>tmp/sysroots/<replaceable>machine</replaceable>/pkgdata</filename>). + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-1.5-shortened-git-srcrev-values'> + <title>Shortened Git <filename>SRCREV</filename> Values</title> + + <para> + BitBake will now shorten revisions from Git repositories from the + normal 40 characters down to 10 characters within + <link linkend='var-SRCPV'><filename>SRCPV</filename></link> + 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. + </para> + </section> + + <section id='migration-1.5-image-features'> + <title><filename>IMAGE_FEATURES</filename></title> + + <para> + The following changes have been made that relate to + <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>: + <itemizedlist> + <listitem><para> + The value of <filename>IMAGE_FEATURES</filename> is now + validated to ensure invalid feature items are not added. + Some users mistakenly add package names to this variable + instead of using + <link linkend='var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></link> + 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 <filename>IMAGE_FEATURES</filename> are drawn from + <link linkend='var-PACKAGE_GROUP'><filename>PACKAGE_GROUP</filename></link> + definitions, + <link linkend='var-COMPLEMENTARY_GLOB'><filename>COMPLEMENTARY_GLOB</filename></link> + and a new "validitems" varflag on + <filename>IMAGE_FEATURES</filename>. + The "validitems" varflag change allows additional features + to be added if they are not provided using the previous + two mechanisms. + </para></listitem> + <listitem><para> + The previously deprecated "apps-console-core" + <filename>IMAGE_FEATURES</filename> item is no longer + supported. + Add "splash" to <filename>IMAGE_FEATURES</filename> if you + wish to have the splash screen enabled, since this is + all that apps-console-core was doing.</para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-1.5-run'> + <title><filename>/run</filename></title> + + <para> + The <filename>/run</filename> directory from the Filesystem + Hierarchy Standard 3.0 has been introduced. + You can find some of the implications for this change + <ulink url='http://cgit.openembedded.org/openembedded-core/commit/?id=0e326280a15b0f2c4ef2ef4ec441f63f55b75873'>here</ulink>. + The change also means that recipes that install files to + <filename>/var/run</filename> must be changed. + You can find a guide on how to make these changes + <ulink url='http://permalink.gmane.org/gmane.comp.handhelds.openembedded/58530'>here</ulink>. + </para> + </section> + + <section id='migration-1.5-removal-of-package-manager-database-within-image-recipes'> + <title>Removal of Package Manager Database Within Image Recipes</title> + + <para> + The image <filename>core-image-minimal</filename> no longer adds + <filename>remove_packaging_data_files</filename> to + <link linkend='var-ROOTFS_POSTPROCESS_COMMAND'><filename>ROOTFS_POSTPROCESS_COMMAND</filename></link>. + This addition is now handled automatically when "package-management" + is not in + <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>. + 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. + </para> + </section> + + <section id='migration-1.5-images-now-rebuild-only-on-changes-instead-of-every-time'> + <title>Images Now Rebuild Only on Changes Instead of Every Time</title> + + <para> + The + <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link> + 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. + </para> + </section> + + <section id='migration-1.5-task-recipes'> + <title>Task Recipes</title> + + <para> + The previously deprecated <filename>task.bbclass</filename> has + now been dropped. + For recipes that previously inherited from this class, you should + rename them from <filename>task-*</filename> to + <filename>packagegroup-*</filename> and inherit packagegroup + instead. + </para> + + <para> + For more information, see the + "<link linkend='ref-classes-packagegroup'><filename>packagegroup.bbclass</filename></link>" + section. + </para> + </section> + + <section id='migration-1.5-busybox'> + <title>BusyBox</title> + + <para> + 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 + <filename>tinylogin</filename> recipe as recommended by upstream. + You can disable this split by setting + <link linkend='var-BUSYBOX_SPLIT_SUID'><filename>BUSYBOX_SPLIT_SUID</filename></link> + to "0". + </para> + </section> + + <section id='migration-1.5-automated-image-testing'> + <title>Automated Image Testing</title> + + <para> + A new automated image testing framework has been added + through the + <link linkend='ref-classes-testimage*'><filename>testimage.bbclass</filename></link> + class. + This framework replaces the older + <filename>imagetest-qemu</filename> framework. + </para> + + <para> + You can learn more about performing automated image tests in the + "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>" + section in the Yocto Project Development Tasks Manual. + </para> + </section> + + <section id='migration-1.5-build-history'> + <title>Build History</title> + + <para> + Following are changes to Build History: + <itemizedlist> + <listitem><para> + Installed package sizes: + <filename>installed-package-sizes.txt</filename> for an + image now records the size of the files installed by each + package instead of the size of each compressed package + archive file.</para></listitem> + <listitem><para> + The dependency graphs (<filename>depends*.dot</filename>) + now use the actual package names instead of replacing + dashes, dots and plus signs with underscores. + </para></listitem> + <listitem><para> + The <filename>buildhistory-diff</filename> and + <filename>buildhistory-collect-srcrevs</filename> + utilities have improved command-line handling. + Use the <filename>--help</filename> option for + each utility for more information on the new syntax. + </para></listitem> + </itemizedlist> + For more information on Build History, see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-build-output-quality'>Maintaining Build Output Quality</ulink>" + section in the Yocto Project Development Tasks Manual. + </para> + </section> + + <section id='migration-1.5-udev'> + <title><filename>udev</filename></title> + + <para> + Following are changes to <filename>udev</filename>: + <itemizedlist> + <listitem><para> + <filename>udev</filename> no longer brings in + <filename>udev-extraconf</filename> automatically + through + <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>, + since this was originally intended to be optional. + If you need the extra rules, then add + <filename>udev-extraconf</filename> to your image. + </para></listitem> + <listitem><para> + <filename>udev</filename> no longer brings in + <filename>pciutils-ids</filename> or + <filename>usbutils-ids</filename> through + <filename>RRECOMMENDS</filename>. + These are not needed by <filename>udev</filename> itself + and removing them saves around 350KB. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-1.5-removed-renamed-recipes'> + <title>Removed and Renamed Recipes</title> + + <itemizedlist> + <listitem><para> + The <filename>linux-yocto</filename> 3.2 kernel has been + removed.</para></listitem> + <listitem><para> + <filename>libtool-nativesdk</filename> has been renamed to + <filename>nativesdk-libtool</filename>.</para></listitem> + <listitem><para> + <filename>tinylogin</filename> has been removed. + It has been replaced by a suid portion of Busybox. + See the + "<link linkend='migration-1.5-busybox'>BusyBox</link>" section + for more information.</para></listitem> + <listitem><para> + <filename>external-python-tarball</filename> has been renamed + to <filename>buildtools-tarball</filename>. + </para></listitem> + <listitem><para> + <filename>web-webkit</filename> has been removed. + It has been functionally replaced by + <filename>midori</filename>.</para></listitem> + <listitem><para> + <filename>imake</filename> has been removed. + It is no longer needed by any other recipe. + </para></listitem> + <listitem><para> + <filename>transfig-native</filename> has been removed. + It is no longer needed by any other recipe. + </para></listitem> + <listitem><para> + <filename>anjuta-remote-run</filename> has been removed. + Anjuta IDE integration has not been officially supported for + several releases.</para></listitem> + </itemizedlist> + </section> + + <section id='migration-1.5-other-changes'> + <title>Other Changes</title> + + <para> + Following is a list of short entries describing other changes: + <itemizedlist> + <listitem><para> + <filename>run-postinsts</filename>: Make this generic. + </para></listitem> + <listitem><para> + <filename>base-files</filename>: Remove the unnecessary + <filename>media/</filename><replaceable>xxx</replaceable> directories. + </para></listitem> + <listitem><para> + <filename>alsa-state</filename>: Provide an empty + <filename>asound.conf</filename> by default. + </para></listitem> + <listitem><para> + <filename>classes/image</filename>: Ensure + <link linkend='var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></link> + supports pre-renamed package names.</para></listitem> + <listitem><para> + <filename>classes/rootfs_rpm</filename>: Implement + <filename>BAD_RECOMMENDATIONS</filename> for RPM. + </para></listitem> + <listitem><para> + <filename>systemd</filename>: Remove + <filename>systemd_unitdir</filename> if + <filename>systemd</filename> is not in + <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>. + </para></listitem> + <listitem><para> + <filename>systemd</filename>: Remove + <filename>init.d</filename> dir if + <filename>systemd</filename> unit file is present and + <filename>sysvinit</filename> is not a distro feature. + </para></listitem> + <listitem><para> + <filename>libpam</filename>: Deny all services for the + <filename>OTHER</filename> entries. + </para></listitem> + <listitem><para> + <filename>image.bbclass</filename>: Move + <filename>runtime_mapping_rename</filename> to avoid + conflict with <filename>multilib</filename>. + See + <ulink url='https://bugzilla.yoctoproject.org/show_bug.cgi?id=4993'><filename>YOCTO #4993</filename></ulink> + in Bugzilla for more information. + </para></listitem> + <listitem><para> + <filename>linux-dtb</filename>: Use kernel build system + to generate the <filename>dtb</filename> files. + </para></listitem> + <listitem><para> + <filename>kern-tools</filename>: Switch from guilt to + new <filename>kgit-s2q</filename> tool. + </para></listitem> + </itemizedlist> + </para> + </section> +</section> + +<section id='moving-to-the-yocto-project-1.6-release'> + <title>Moving to the Yocto Project 1.6 Release</title> + + <para> + This section provides migration information for moving to the + Yocto Project 1.6 Release from the prior release. + </para> + + + <section id='migration-1.6-archiver-class'> + <title><filename>archiver</filename> Class</title> + + <para> + The + <link linkend='ref-classes-archiver'><filename>archiver</filename></link> + class has been rewritten and its configuration has been simplified. + For more details on the source archiver, see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-open-source-license-compliance-during-your-products-lifecycle'>Maintaining Open Source License Compliance During Your Product's Lifecycle</ulink>" + section in the Yocto Project Development Tasks Manual. + </para> + </section> + + <section id='migration-1.6-packaging-changes'> + <title>Packaging Changes</title> + + <para> + The following packaging changes have been made: + <itemizedlist> + <listitem><para> + The <filename>binutils</filename> recipe no longer produces + a <filename>binutils-symlinks</filename> package. + <filename>update-alternatives</filename> is now used to + handle the preferred <filename>binutils</filename> + variant on the target instead. + </para></listitem> + <listitem><para> + The tc (traffic control) utilities have been split out of + the main <filename>iproute2</filename> package and put + into the <filename>iproute2-tc</filename> package. + </para></listitem> + <listitem><para> + The <filename>gtk-engines</filename> schemas have been + moved to a dedicated + <filename>gtk-engines-schemas</filename> package. + </para></listitem> + <listitem><para> + The <filename>armv7a</filename> 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. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-1.6-bitbake'> + <title>BitBake</title> + + <para> + The following changes have been made to + <link linkend='bitbake-term'>BitBake</link>. + </para> + + <section id='migration-1.6-matching-branch-requirement-for-git-fetching'> + <title>Matching Branch Requirement for Git Fetching</title> + + <para> + When fetching source from a Git repository using + <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>, + BitBake will now validate the + <link linkend='var-SRCREV'><filename>SRCREV</filename></link> + value against the branch. + You can specify the branch using the following form: + <literallayout class='monospaced'> + SRC_URI = "git://server.name/repository;branch=<replaceable>branchname</replaceable>" + </literallayout> + If you do not specify a branch, BitBake looks + in the default "master" branch. + </para> + + <para> + 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 <filename>SRC_URI</filename>. + </para> + </section> + + <section id='migration-1.6-bitbake-deps'> + <title>Python Definition substitutions</title> + + <para> + BitBake had some previously deprecated Python definitions + within its <filename>bb</filename> module removed. + You should use their sub-module counterparts instead: + <itemizedlist> + <listitem><para><filename>bb.MalformedUrl</filename>: + Use <filename>bb.fetch.MalformedUrl</filename>. + </para></listitem> + <listitem><para><filename>bb.encodeurl</filename>: + Use <filename>bb.fetch.encodeurl</filename>. + </para></listitem> + <listitem><para><filename>bb.decodeurl</filename>: + Use <filename>bb.fetch.decodeurl</filename> + </para></listitem> + <listitem><para><filename>bb.mkdirhier</filename>: + Use <filename>bb.utils.mkdirhier</filename>. + </para></listitem> + <listitem><para><filename>bb.movefile</filename>: + Use <filename>bb.utils.movefile</filename>. + </para></listitem> + <listitem><para><filename>bb.copyfile</filename>: + Use <filename>bb.utils.copyfile</filename>. + </para></listitem> + <listitem><para><filename>bb.which</filename>: + Use <filename>bb.utils.which</filename>. + </para></listitem> + <listitem><para><filename>bb.vercmp_string</filename>: + Use <filename>bb.utils.vercmp_string</filename>. + </para></listitem> + <listitem><para><filename>bb.vercmp</filename>: + Use <filename>bb.utils.vercmp</filename>. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-1.6-bitbake-fetcher'> + <title>SVK Fetcher</title> + + <para> + The SVK fetcher has been removed from BitBake. + </para> + </section> + + <section id='migration-1.6-bitbake-console-output'> + <title>Console Output Error Redirection</title> + + <para> + The BitBake console UI will now output errors to + <filename>stderr</filename> instead of + <filename>stdout</filename>. + Consequently, if you are piping or redirecting the output of + <filename>bitbake</filename> to somewhere else, and you wish + to retain the errors, you will need to add + <filename>2>&1</filename> (or something similar) to the + end of your <filename>bitbake</filename> command line. + </para> + </section> + + <section id='migration-1.6-task-taskname-overrides'> + <title><filename>task-</filename><replaceable>taskname</replaceable> Overrides</title> + + <para> + <filename>task-</filename><replaceable>taskname</replaceable> 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 + <link linkend='ref-tasks-populate_sdk'><filename>do_populate_sdk</filename></link> + is <filename>task-populate-sdk</filename>. + </para> + </section> + </section> + + <section id='migration-1.6-variable-changes'> + <title>Changes to Variables</title> + + <para> + The following variables have changed. + For information on the OpenEmbedded build system variables, see the + "<link linkend='ref-variables-glos'>Variables Glossary</link>" Chapter. + </para> + + <section id='migration-1.6-variable-changes-TMPDIR'> + <title><filename>TMPDIR</filename></title> + + <para> + <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link> + 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 + <filename>TMPDIR</filename>. + </para> + + <para> + The check for this occurs on startup. + If <filename>TMPDIR</filename> is detected on an NFS mount, + an error occurs. + </para> + </section> + + <section id='migration-1.6-variable-changes-PRINC'> + <title><filename>PRINC</filename></title> + + <para> + The <filename>PRINC</filename> + variable has been deprecated and triggers a warning if + detected during a build. + For + <link linkend='var-PR'><filename>PR</filename></link> + increments on changes, use the PR service instead. + You can find out more about this service in the + "<ulink url='&YOCTO_DOCS_DEV_URL;#working-with-a-pr-service'>Working With a PR Service</ulink>" + section in the Yocto Project Development Tasks Manual. + </para> + </section> + + <section id='migration-1.6-variable-changes-IMAGE_TYPES'> + <title><filename>IMAGE_TYPES</filename></title> + + <para> + The "sum.jffs2" option for + <link linkend='var-IMAGE_TYPES'><filename>IMAGE_TYPES</filename></link> + has been replaced by the "jffs2.sum" option, which fits the + processing order. + </para> + </section> + + <section id='migration-1.6-variable-changes-COPY_LIC_MANIFEST'> + <title><filename>COPY_LIC_MANIFEST</filename></title> + + <para> + The + <link linkend='var-COPY_LIC_MANIFEST'><filename>COPY_LIC_MANIFEST</filename></link> + variable must + now be set to "1" rather than any value in order to enable + it. + </para> + </section> + + <section id='migration-1.6-variable-changes-COPY_LIC_DIRS'> + <title><filename>COPY_LIC_DIRS</filename></title> + + <para> + The + <link linkend='var-COPY_LIC_DIRS'><filename>COPY_LIC_DIRS</filename></link> + variable must + now be set to "1" rather than any value in order to enable + it. + </para> + </section> + + <section id='migration-1.6-variable-changes-PACKAGE_GROUP'> + <title><filename>PACKAGE_GROUP</filename></title> + + <para> + The + <link linkend='var-PACKAGE_GROUP'><filename>PACKAGE_GROUP</filename></link> + variable has been renamed to + <link linkend='var-FEATURE_PACKAGES'><filename>FEATURE_PACKAGES</filename></link> + to more accurately reflect its purpose. + You can still use <filename>PACKAGE_GROUP</filename> but + the OpenEmbedded build system produces a warning message when + it encounters the variable. + </para> + </section> + + <section id='migration-1.6-variable-changes-variable-entry-behavior'> + <title>Preprocess and Post Process Command Variable Behavior</title> + + <para> + The following variables now expect a semicolon separated + list of functions to call and not arbitrary shell commands: + <literallayout class='monospaced'> + <link linkend='var-ROOTFS_PREPROCESS_COMMAND'>ROOTFS_PREPROCESS_COMMAND</link> + <link linkend='var-ROOTFS_POSTPROCESS_COMMAND'>ROOTFS_POSTPROCESS_COMMAND</link> + <link linkend='var-SDK_POSTPROCESS_COMMAND'>SDK_POSTPROCESS_COMMAND</link> + <link linkend='var-POPULATE_SDK_POST_TARGET_COMMAND'>POPULATE_SDK_POST_TARGET_COMMAND</link> + <link linkend='var-POPULATE_SDK_POST_HOST_COMMAND'>POPULATE_SDK_POST_HOST_COMMAND</link> + <link linkend='var-IMAGE_POSTPROCESS_COMMAND'>IMAGE_POSTPROCESS_COMMAND</link> + <link linkend='var-IMAGE_PREPROCESS_COMMAND'>IMAGE_PREPROCESS_COMMAND</link> + <link linkend='var-ROOTFS_POSTUNINSTALL_COMMAND'>ROOTFS_POSTUNINSTALL_COMMAND</link> + <link linkend='var-ROOTFS_POSTINSTALL_COMMAND'>ROOTFS_POSTINSTALL_COMMAND</link> + </literallayout> + For migration purposes, you can simply wrap shell commands in + a shell function and then call the function. + Here is an example: + <literallayout class='monospaced'> + my_postprocess_function() { + echo "hello" > ${IMAGE_ROOTFS}/hello.txt + } + ROOTFS_POSTPROCESS_COMMAND += "my_postprocess_function; " + </literallayout> + </para> + </section> + </section> + + <section id='migration-1.6-package-test-ptest'> + <title>Package Test (ptest)</title> + + <para> + Package Tests (ptest) are built but not installed by default. + For information on using Package Tests, see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#testing-packages-with-ptest'>Testing Packages with ptest</ulink>" + section in the Yocto Project Development Tasks Manual. + For information on the <filename>ptest</filename> class, see the + "<link linkend='ref-classes-ptest'><filename>ptest.bbclass</filename></link>" + section. + </para> + </section> + + <section id='migration-1.6-build-changes'> + <title>Build Changes</title> + + <para> + 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 + <link linkend='ref-classes-cmake'><filename>cmake</filename></link> + class. + In future releases the + <link linkend='ref-classes-autotools'><filename>autotools</filename></link> + 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 + <link linkend='ref-classes-autotools'><filename>autotools-brokensep</filename></link> + class instead of the <filename>autotools</filename> or + <filename>autotools_stage</filename>classes. + </para> + </section> + + <section id='migration-1.6-building-qemu-native'> + <title><filename>qemu-native</filename></title> + + <para> + <filename>qemu-native</filename> now builds without + SDL-based graphical output support by default. + The following additional lines are needed in your + <filename>local.conf</filename> to enable it: + <literallayout class='monospaced'> + PACKAGECONFIG_pn-qemu-native = "sdl" + ASSUME_PROVIDED += "libsdl-native" + </literallayout> + <note> + The default <filename>local.conf</filename> + contains these statements. + Consequently, if you are building a headless system and using + a default <filename>local.conf</filename> file, you will need + comment these two lines out. + </note> + </para> + </section> + + <section id='migration-1.6-core-image-basic'> + <title><filename>core-image-basic</filename></title> + + <para> + <filename>core-image-basic</filename> has been renamed to + <filename>core-image-full-cmdline</filename>. + </para> + + <para> + In addition to <filename>core-image-basic</filename> being renamed, + <filename>packagegroup-core-basic</filename> has been renamed to + <filename>packagegroup-core-full-cmdline</filename> to match. + </para> + </section> + + <section id='migration-1.6-licensing'> + <title>Licensing</title> + + <para> + The top-level <filename>LICENSE</filename> file has been changed + to better describe the license of the various components of + <link linkend='oe-core'>OE-Core</link>. + However, the licensing itself remains unchanged. + </para> + + <para> + Normally, this change would not cause any side-effects. + However, some recipes point to this file within + <link linkend='var-LIC_FILES_CHKSUM'><filename>LIC_FILES_CHKSUM</filename></link> + (as <filename>${COREBASE}/LICENSE</filename>) and thus the + accompanying checksum must be changed from + 3f40d7994397109285ec7b81fdeb3b58 to + 4d92cd373abda3937c2bc47fbc49d690. + A better alternative is to have + <filename>LIC_FILES_CHKSUM</filename> point to a file + describing the license that is distributed with the source + that the recipe is building, if possible, rather than pointing + to <filename>${COREBASE}/LICENSE</filename>. + </para> + </section> + + <section id='migration-1.6-cflags-options'> + <title><filename>CFLAGS</filename> Options</title> + + <para> + The "-fpermissive" option has been removed from the default + <link linkend='var-CFLAGS'><filename>CFLAGS</filename></link> + 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 + <filename>CFLAGS</filename> in the recipes. + </para> + </section> + + <section id='migration-1.6-custom-images'> + <title>Custom Image Output Types</title> + + <para> + Custom image output types, as selected using + <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>, + must declare their dependencies on other image types (if any) using + a new + <link linkend='var-IMAGE_TYPEDEP'><filename>IMAGE_TYPEDEP</filename></link> + variable. + </para> + </section> + + <section id='migration-1.6-do-package-write-task'> + <title>Tasks</title> + + <para> + The <filename>do_package_write</filename> task has been removed. + The task is no longer needed. + </para> + </section> + + <section id='migration-1.6-update-alternatives-provider'> + <title><filename>update-alternative</filename> Provider</title> + + <para> + The default <filename>update-alternatives</filename> provider has + been changed from <filename>opkg</filename> to + <filename>opkg-utils</filename>. + This change resolves some troublesome circular dependencies. + The runtime package has also been renamed from + <filename>update-alternatives-cworth</filename> + to <filename>update-alternatives-opkg</filename>. + </para> + </section> + + <section id='migration-1.6-virtclass-overrides'> + <title><filename>virtclass</filename> Overrides</title> + + <para> + The <filename>virtclass</filename> overrides are now deprecated. + Use the equivalent class overrides instead (e.g. + <filename>virtclass-native</filename> becomes + <filename>class-native</filename>.) + </para> + </section> + + <section id='migration-1.6-removed-renamed-recipes'> + <title>Removed and Renamed Recipes</title> + + <para> + The following recipes have been removed: + <itemizedlist> + <listitem><para><filename>packagegroup-toolset-native</filename> - + This recipe is largely unused. + </para></listitem> + <listitem><para><filename>linux-yocto-3.8</filename> - + 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 <filename>linux-yocto-3.10</filename> and + <filename>linux-yocto-3.14</filename> recipes. + </para></listitem> + <listitem><para><filename>ocf-linux</filename> - + This recipe has been functionally replaced using + <filename>cryptodev-linux</filename>. + </para></listitem> + <listitem><para><filename>genext2fs</filename> - + <filename>genext2fs</filename> is no longer used by the + build system and is unmaintained upstream. + </para></listitem> + <listitem><para><filename>js</filename> - + This provided an ancient version of Mozilla's javascript + engine that is no longer needed. + </para></listitem> + <listitem><para><filename>zaurusd</filename> - + The recipe has been moved to the + <filename>meta-handheld</filename> layer. + </para></listitem> + <listitem><para><filename>eglibc 2.17</filename> - + Replaced by the <filename>eglibc 2.19</filename> + recipe. + </para></listitem> + <listitem><para><filename>gcc 4.7.2</filename> - + Replaced by the now stable + <filename>gcc 4.8.2</filename>. + </para></listitem> + <listitem><para><filename>external-sourcery-toolchain</filename> - + this recipe is now maintained in the + <filename>meta-sourcery</filename> layer. + </para></listitem> + <listitem><para><filename>linux-libc-headers-yocto 3.4+git</filename> - + Now using version 3.10 of the + <filename>linux-libc-headers</filename> by default. + </para></listitem> + <listitem><para><filename>meta-toolchain-gmae</filename> - + This recipe is obsolete. + </para></listitem> + <listitem><para><filename>packagegroup-core-sdk-gmae</filename> - + This recipe is obsolete. + </para></listitem> + <listitem><para><filename>packagegroup-core-standalone-gmae-sdk-target</filename> - + This recipe is obsolete. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-1.6-removed-classes'> + <title>Removed Classes</title> + + <para> + The following classes have become obsolete and have been removed: + <itemizedlist> + <listitem><para><filename>module_strip</filename> + </para></listitem> + <listitem><para><filename>pkg_metainfo</filename> + </para></listitem> + <listitem><para><filename>pkg_distribute</filename> + </para></listitem> + <listitem><para><filename>image-empty</filename> + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-1.6-reference-bsps'> + <title>Reference Board Support Packages (BSPs)</title> + + <para> + The following reference BSPs changes occurred: + <itemizedlist> + <listitem><para>The BeagleBoard + (<filename>beagleboard</filename>) ARM reference hardware + has been replaced by the BeagleBone + (<filename>beaglebone</filename>) hardware. + </para></listitem> + <listitem><para>The RouterStation Pro + (<filename>routerstationpro</filename>) MIPS reference + hardware has been replaced by the EdgeRouter Lite + (<filename>edgerouter</filename>) hardware. + </para></listitem> + </itemizedlist> + The previous reference BSPs for the + <filename>beagleboard</filename> and + <filename>routerstationpro</filename> machines are still available + in a new <filename>meta-yocto-bsp-old</filename> layer in the + <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink> + at + <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/meta-yocto-bsp-old/'>http://git.yoctoproject.org/cgit/cgit.cgi/meta-yocto-bsp-old/</ulink>. + </para> + </section> +</section> + +<section id='moving-to-the-yocto-project-1.7-release'> + <title>Moving to the Yocto Project 1.7 Release</title> + + <para> + This section provides migration information for moving to the + Yocto Project 1.7 Release from the prior release. + </para> + + <section id='migration-1.7-changes-to-setting-qemu-packageconfig-options'> + <title>Changes to Setting QEMU <filename>PACKAGECONFIG</filename> Options in <filename>local.conf</filename></title> + + <para> + The QEMU recipe now uses a number of + <link linkend='var-PACKAGECONFIG'><filename>PACKAGECONFIG</filename></link> + options to enable various optional features. + The method used to set defaults for these options means that + existing + <filename>local.conf</filename> files will need to be be + modified to append to <filename>PACKAGECONFIG</filename> for + <filename>qemu-native</filename> and + <filename>nativesdk-qemu</filename> instead of setting it. + In other words, to enable graphical output for QEMU, you should + now have these lines in <filename>local.conf</filename>: + <literallayout class='monospaced'> + PACKAGECONFIG_append_pn-qemu-native = " sdl" + PACKAGECONFIG_append_pn-nativesdk-qemu = " sdl" + </literallayout> + </para> + </section> + + <section id='migration-1.7-minimum-git-version'> + <title>Minimum Git version</title> + + <para> + The minimum + <ulink url='&YOCTO_DOCS_OM_URL;#git'>Git</ulink> version + required on the build host is now 1.7.8 because the + <filename>--list</filename> 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 + <filename>buildtools-tarball</filename> that does. + See the + "<link linkend='required-git-tar-and-python-versions'>Required Git, tar, and Python Versions</link>" + section for more information. + </para> + </section> + + <section id='migration-1.7-autotools-class-changes'> + <title>Autotools Class Changes</title> + + <para> + The following + <link linkend='ref-classes-autotools'><filename>autotools</filename></link> + class changes occurred: + <itemizedlist> + <listitem><para><emphasis> + A separate build directory is now used by default:</emphasis> + The <filename>autotools</filename> class has been changed + to use a directory for building + (<link linkend='var-B'><filename>B</filename></link>), + which is separate from the source directory + (<link linkend='var-S'><filename>S</filename></link>). + This is commonly referred to as + <filename>B != S</filename>, or an out-of-tree build.</para> + <para>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 + <link linkend='ref-classes-autotools'><filename>autotools-brokensep</filename></link> + class instead of the <filename>autotools</filename> or + <filename>autotools_stage</filename> classes. + </para></listitem> + <listitem><para><emphasis> + The <filename>--foreign</filename> option is + no longer passed to <filename>automake</filename> when + running <filename>autoconf</filename>:</emphasis> + This option tells <filename>automake</filename> that a + particular software package does not follow the GNU + standards and therefore should not be expected + to distribute certain files such as + <filename>ChangeLog</filename>, + <filename>AUTHORS</filename>, and so forth. + Because the majority of upstream software packages already + tell <filename>automake</filename> 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 + <filename>configure.ac</filename> so that it passes + "foreign" to <filename>AM_INIT_AUTOMAKE()</filename>. + See + <ulink url='http://cgit.openembedded.org/openembedded-core/commit/?id=01943188f85ce6411717fb5bf702d609f55813f2'>this commit</ulink> + for an example showing how to make the patch. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-1.7-binary-configuration-scripts-disabled'> + <title>Binary Configuration Scripts Disabled</title> + + <para> + 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 <filename>pkg-config</filename> + instead. + The list of recipes changed in this version (and their + configuration scripts) is as follows: + <literallayout class='monospaced'> + 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) + </literallayout> + Additionally, support for <filename>pkg-config</filename> has been + added to some recipes in the previous list in the rare cases + where the upstream software package does not already provide + it. + </para> + </section> + + <section id='migration-1.7-glibc-replaces-eglibc'> + <title><filename>eglibc 2.19</filename> Replaced with <filename>glibc 2.20</filename></title> + + <para> + Because <filename>eglibc</filename> and + <filename>glibc</filename> were already fairly close, this + replacement should not require any significant changes to other + software that links to <filename>eglibc</filename>. + However, there were a number of minor changes in + <filename>glibc 2.20</filename> upstream that could require + patching some software (e.g. the removal of the + <filename>_BSD_SOURCE</filename> feature test macro). + </para> + + <para> + <filename>glibc 2.20</filename> requires version 2.6.32 or greater + of the Linux kernel. + Thus, older kernels will no longer be usable in conjunction with it. + </para> + + <para> + For full details on the changes in <filename>glibc 2.20</filename>, + see the upstream release notes + <ulink url='https://sourceware.org/ml/libc-alpha/2014-09/msg00088.html'>here</ulink>. + </para> + </section> + + <section id='migration-1.7-kernel-module-autoloading'> + <title>Kernel Module Autoloading</title> + + <para> + The + <link linkend='var-module_autoload'><filename>module_autoload_*</filename></link> + variable is now deprecated and a new + <link linkend='var-KERNEL_MODULE_AUTOLOAD'><filename>KERNEL_MODULE_AUTOLOAD</filename></link> + variable should be used instead. + Also, + <link linkend='var-module_conf'><filename>module_conf_*</filename></link> + must now be used in conjunction with a new + <link linkend='var-KERNEL_MODULE_PROBECONF'><filename>KERNEL_MODULE_PROBECONF</filename></link> + 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 + <filename>module_autoload_*</filename> with + <filename>KERNEL_MODULE_AUTOLOAD</filename>, and add any modules + for which <filename>module_conf_*</filename> is specified to + <filename>KERNEL_MODULE_PROBECONF</filename>. + </para> + </section> + + <section id='migration-1.7-qa-check-changes'> + <title>QA Check Changes</title> + + <para> + The following changes have occurred to the QA check process: + <itemizedlist> + <listitem><para> + Additional QA checks <filename>file-rdeps</filename> + and <filename>build-deps</filename> have been added in + order to verify that file dependencies are satisfied + (e.g. package contains a script requiring + <filename>/bin/bash</filename>) and build-time dependencies + are declared, respectively. + For more information, please see the + "<link linkend='ref-qa-checks'>QA Error and Warning Messages</link>" + chapter. + </para></listitem> + <listitem><para> + Package QA checks are now performed during a new + <link linkend='ref-tasks-package_qa'><filename>do_package_qa</filename></link> + task rather than being part of the + <link linkend='ref-tasks-package'><filename>do_package</filename></link> + 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 <filename>noexec</filename>. + For those packages, you will need to disable the + <filename>do_package_qa</filename> task as well. + </para></listitem> + <listitem><para> + Files being overwritten during the + <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link> + 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.</para> + <para>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 + <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link> + 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. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-1.7-removed-recipes'> + <title>Removed Recipes</title> + + <para> + The following recipes have been removed: + <itemizedlist> + <listitem><para> + <filename>x-load</filename>: + This recipe has been superseded by + U-boot SPL for all Cortex-based TI SoCs. + For legacy boards, the <filename>meta-ti</filename> + layer, which contains a maintained recipe, should be used + instead. + </para></listitem> + <listitem><para> + <filename>ubootchart</filename>: + This recipe is obsolete. + A <filename>bootchart2</filename> recipe has been added + to functionally replace it. + </para></listitem> + <listitem><para> + <filename>linux-yocto 3.4</filename>: + 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. + </para></listitem> + <listitem><para> + <filename>eglibc</filename> has been removed in favor of + <filename>glibc</filename>. + See the + "<link linkend='migration-1.7-glibc-replaces-eglibc'><filename>eglibc 2.19</filename> Replaced with <filename>glibc 2.20</filename></link>" + section for more information. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-1.7-miscellaneous-changes'> + <title>Miscellaneous Changes</title> + + <para> + The following miscellaneous change occurred: + <itemizedlist> + <listitem><para> + The build history feature now writes + <filename>build-id.txt</filename> instead of + <filename>build-id</filename>. + Additionally, <filename>build-id.txt</filename> + 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 + "<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-build-output-quality'>Maintaining Build Output Quality</ulink>" + section in the Yocto Project Development Tasks Manual. + </para></listitem> + </itemizedlist> + </para> + </section> +</section> + +<section id='moving-to-the-yocto-project-1.8-release'> + <title>Moving to the Yocto Project 1.8 Release</title> + + <para> + This section provides migration information for moving to the + Yocto Project 1.8 Release from the prior release. + </para> + + <section id='migration-1.8-removed-recipes'> + <title>Removed Recipes</title> + + <para> + The following recipes have been removed: + <itemizedlist> + <listitem><para><filename>owl-video</filename>: + Functionality replaced by <filename>gst-player</filename>. + </para></listitem> + <listitem><para><filename>gaku</filename>: + Functionality replaced by <filename>gst-player</filename>. + </para></listitem> + <listitem><para><filename>gnome-desktop</filename>: + This recipe is now available in + <filename>meta-gnome</filename> and is no longer needed. + </para></listitem> + <listitem><para><filename>gsettings-desktop-schemas</filename>: + This recipe is now available in + <filename>meta-gnome</filename> and is no longer needed. + </para></listitem> + <listitem><para><filename>python-argparse</filename>: + The <filename>argparse</filename> module is already + provided in the default Python distribution in a + package named <filename>python-argparse</filename>. + Consequently, the separate + <filename>python-argparse</filename> recipe is no + longer needed. + </para></listitem> + <listitem><para><filename>telepathy-python, libtelepathy, telepathy-glib, telepathy-idle, telepathy-mission-control</filename>: + All these recipes have moved to + <filename>meta-oe</filename> and are consequently no + longer needed by any recipes in OpenEmbedded-Core. + </para></listitem> + <listitem><para><filename>linux-yocto_3.10</filename> and <filename>linux-yocto_3.17</filename>: + 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. + </para></listitem> + <listitem><para><filename>poky-feed-config-opkg</filename>: + This recipe has become obsolete and is no longer needed. + Use <filename>distro-feed-config</filename> from + <filename>meta-oe</filename> instead. + </para></listitem> + <listitem><para><filename>libav 0.8.x</filename>: + <filename>libav 9.x</filename> is now used. + </para></listitem> + <listitem><para><filename>sed-native</filename>: + No longer needed. + A working version of <filename>sed</filename> is expected + to be provided by the host distribution. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-1.8-bluez'> + <title>BlueZ 4.x / 5.x Selection</title> + + <para> + 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 + <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link> + value. + If you had previously added append files + (<filename>*.bbappend</filename>) to make this selection, you can + now remove them. + </para> + + <para> + Additionally, a + <link linkend='ref-classes-bluetooth'><filename>bluetooth</filename></link> + 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: + <literallayout class='monospaced'> + 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" + </literallayout> + </para> + </section> + + <section id='migration-1.8-kernel-build-changes'> + <title>Kernel Build Changes</title> + + <para> + 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 + <filename>${S}</filename> (source files) and + <filename>${B}</filename> (build artifacts) are used + correctly in functions such as + <link linkend='ref-tasks-configure'><filename>do_configure</filename></link> + and + <link linkend='ref-tasks-install'><filename>do_install</filename></link>. + For kernel recipes that do not inherit from + <filename>kernel-yocto</filename> or include + <filename>linux-yocto.inc</filename>, you might wish to + refer to the <filename>linux.inc</filename> file in the + <filename>meta-oe</filename> layer for the kinds of changes you + need to make. + For reference, here is the + <ulink url='http://cgit.openembedded.org/meta-openembedded/commit/meta-oe/recipes-kernel/linux/linux.inc?id=fc7132ede27ac67669448d3d2845ce7d46c6a1ee'>commit</ulink> + where the <filename>linux.inc</filename> file in + <filename>meta-oe</filename> was updated. + </para> + + <para> + Recipes that rely on the kernel source code and do not inherit + the module classes might need to add explicit dependencies on + the <filename>do_shared_workdir</filename> kernel task, for example: + <literallayout class='monospaced'> + do_configure[depends] += "virtual/kernel:do_shared_workdir" + </literallayout> + </para> + </section> + + <section id='migration-1.8-ssl'> + <title>SSL 3.0 is Now Disabled in OpenSSL</title> + + <para> + 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 (<filename>*.bbappend</filename>) for the + <filename>openssl</filename> recipe to remove "-no-ssl3" + from + <link linkend='var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></link>. + </para> + </section> + + <section id='migration-1.8-default-sysroot-poisoning'> + <title>Default Sysroot Poisoning</title> + + <para> + <filename>gcc's</filename> 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. + </para> + + <para> + 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. + </para> + </section> + + <section id='migration-1.8-rebuild-improvements'> + <title>Rebuild Improvements</title> + + <para> + Changes have been made to the + <link linkend='ref-classes-base'><filename>base</filename></link>, + <link linkend='ref-classes-autotools'><filename>autotools</filename></link>, + and + <link linkend='ref-classes-cmake'><filename>cmake</filename></link> + classes to clean out generated files when the + <link linkend='ref-tasks-configure'><filename>do_configure</filename></link> + task needs to be re-executed. + </para> + + <para> + One of the improvements is to attempt to run "make clean" during + the <filename>do_configure</filename> task if a + <filename>Makefile</filename> exists. + Some software packages do not provide a working clean target + within their make files. + If you have such recipes, you need to set + <link linkend='var-CLEANBROKEN'><filename>CLEANBROKEN</filename></link> + to "1" within the recipe, for example: + <literallayout class='monospaced'> + CLEANBROKEN = "1" + </literallayout> + </para> + </section> + + <section id='migration-1.8-qa-check-and-validation-changes'> + <title>QA Check and Validation Changes</title> + + <para> + The following QA Check and Validation Changes have occurred: + <itemizedlist> + <listitem><para> + Usage of <filename>PRINC</filename> + previously triggered a warning. + It now triggers an error. + You should remove any remaining usage of + <filename>PRINC</filename> in any recipe or append file. + </para></listitem> + <listitem><para> + An additional QA check has been added to detect usage of + <filename>${D}</filename> in + <link linkend='var-FILES'><filename>FILES</filename></link> + values where + <link linkend='var-D'><filename>D</filename></link> values + should not be used at all. + The same check ensures that <filename>$D</filename> is used + in + <filename>pkg_preinst/pkg_postinst/pkg_prerm/pkg_postrm</filename> + functions instead of <filename>${D}</filename>. + </para></listitem> + <listitem><para> + <link linkend='var-S'><filename>S</filename></link> now + needs to be set to a valid value within a recipe. + If <filename>S</filename> is not set in the recipe, the + directory is not automatically created. + If <filename>S</filename> does not point to a directory + that exists at the time the + <link linkend='ref-tasks-unpack'><filename>do_unpack</filename></link> + task finishes, a warning will be shown. + </para></listitem> + <listitem><para> + <link linkend='var-LICENSE'><filename>LICENSE</filename></link> + 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. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-1.8-miscellaneous-changes'> + <title>Miscellaneous Changes</title> + + <para> + The following miscellaneous changes have occurred: + <itemizedlist> + <listitem><para> + The <filename>send-error-report</filename> script now + expects a "-s" option to be specified before the server + address. + This assumes a server address is being specified. + </para></listitem> + <listitem><para> + The <filename>oe-pkgdata-util</filename> script now + expects a "-p" option to be specified before the + <filename>pkgdata</filename> directory, which is now + optional. + If the <filename>pkgdata</filename> directory is not + specified, the script will run BitBake to query + <link linkend='var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></link> + from the build environment. + </para></listitem> + </itemizedlist> + </para> + </section> +</section> + +<section id='moving-to-the-yocto-project-2.0-release'> + <title>Moving to the Yocto Project 2.0 Release</title> + + <para> + This section provides migration information for moving to the + Yocto Project 2.0 Release from the prior release. + </para> + + <section id='migration-2.0-gcc-5'> + <title>GCC 5</title> + + <para> + The default compiler is now GCC 5.2. + This change has required fixes for compilation errors in a number + of other recipes. + </para> + + <para> + 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 + <ulink url='https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/commit?id=a077224fd35b2f7fbc93f14cf67074fc792fbac2'>patch</ulink>. + The standard <filename>linux-yocto</filename> kernel source tree + already has a workaround for the same issue. + </para> + + <para> + For further details, see + <ulink url='https://gcc.gnu.org/gcc-5/changes.html'></ulink> and + the porting guide at + <ulink url='https://gcc.gnu.org/gcc-5/porting_to.html'></ulink>. + </para> + + <para> + Alternatively, you can switch back to GCC 4.9 or 4.8 by + setting <filename>GCCVERSION</filename> in your configuration, + as follows: + <literallayout class='monospaced'> + GCCVERSION = "4.9%" + </literallayout> + </para> + </section> + + <section id='migration-2.0-Gstreamer-0.10-removed'> + <title>Gstreamer 0.10 Removed</title> + + <para> + 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 <filename>meta-multimedia</filename>. + This change results in Qt4 having Phonon and Gstreamer + support in QtWebkit disabled by default. + </para> + </section> + + <section id='migration-2.0-removed-recipes'> + <title>Removed Recipes</title> + + <para> + The following recipes have been moved or removed: + <itemizedlist> + <listitem><para> + <filename>bluez4</filename>: The recipe is obsolete and + has been moved due to <filename>bluez5</filename> + becoming fully integrated. + The <filename>bluez4</filename> recipe now resides in + <filename>meta-oe</filename>. + </para></listitem> + <listitem><para> + <filename>gamin</filename>: The recipe is obsolete and + has been removed. + </para></listitem> + <listitem><para> + <filename>gnome-icon-theme</filename>: The recipe's + functionally has been replaced by + <filename>adwaita-icon-theme</filename>. + </para></listitem> + <listitem><para> + Gstreamer 0.10 Recipes: Recipes for Gstreamer 0.10 have + been removed in favor of the recipes for Gstreamer 1.x. + </para></listitem> + <listitem><para> + <filename>insserv</filename>: The recipe is obsolete and + has been removed. + </para></listitem> + <listitem><para> + <filename>libunique</filename>: The recipe is no longer + used and has been moved to <filename>meta-oe</filename>. + </para></listitem> + <listitem><para> + <filename>midori</filename>: The recipe's functionally + has been replaced by <filename>epiphany</filename>. + </para></listitem> + <listitem><para> + <filename>python-gst</filename>: The recipe is obsolete + and has been removed since it only contains bindings for + Gstreamer 0.10. + </para></listitem> + <listitem><para> + <filename>qt-mobility</filename>: The recipe is obsolete and + has been removed since it requires + <filename>Gstreamer 0.10</filename>, which has been + replaced. + </para></listitem> + <listitem><para> + <filename>subversion</filename>: All 1.6.x versions of this + recipe have been removed. + </para></listitem> + <listitem><para> + <filename>webkit-gtk</filename>: The older 1.8.3 version + of this recipe has been removed in favor of + <filename>webkitgtk</filename>. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-2.0-bitbake-datastore-improvements'> + <title>BitBake datastore improvements</title> + + <para> + The method by which BitBake's datastore handles overrides has + changed. + Overrides are now applied dynamically and + <filename>bb.data.update_data()</filename> is now a no-op. + Thus, <filename>bb.data.update_data()</filename> 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: + <itemizedlist> + <listitem><para> + All potential overrides are now visible in the variable + history as seen when you run the following: + <literallayout class='monospaced'> + $ bitbake -e + </literallayout> + </para></listitem> + <listitem><para> + <filename>d.delVar('</filename><replaceable>VARNAME</replaceable><filename>')</filename> and + <filename>d.setVar('</filename><replaceable>VARNAME</replaceable><filename>', None)</filename> + result in the variable and all of its overrides being + cleared out. + Before the change, only the non-overridden values + were cleared. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-2.0-shell-message-function-changes'> + <title>Shell Message Function Changes</title> + + <para> + The shell versions of the BitBake message functions (i.e. + <filename>bbdebug</filename>, <filename>bbnote</filename>, + <filename>bbwarn</filename>, <filename>bbplain</filename>, + <filename>bberror</filename>, and <filename>bbfatal</filename>) + are now connected through to their BitBake equivalents + <filename>bb.debug()</filename>, <filename>bb.note()</filename>, + <filename>bb.warn()</filename>, <filename>bb.plain()</filename>, + <filename>bb.error()</filename>, and + <filename>bb.fatal()</filename>, 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: + <itemizedlist> + <listitem><para> + 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 + <filename>bbwarn</filename>, <filename>bberror</filename>, + and so forth. + Or, you might want to simply remove the calls. + </para></listitem> + <listitem><para> + The <filename>bbfatal</filename> message function now + suppresses the full error log in the UI, which means any + calls to <filename>bbfatal</filename> where you still + wish to see the full error log should be replaced by + <filename>die</filename> or + <filename>bbfatal_log</filename>. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-2.0-extra-development-debug-package-cleanup'> + <title>Extra Development/Debug Package Cleanup</title> + + <para> + The following recipes have had extra + <filename>dev/dbg</filename> packages removed: + <itemizedlist> + <listitem><para> + <filename>acl</filename> + </para></listitem> + <listitem><para> + <filename>apmd</filename> + </para></listitem> + <listitem><para> + <filename>aspell</filename> + </para></listitem> + <listitem><para> + <filename>attr</filename> + </para></listitem> + <listitem><para> + <filename>augeas</filename> + </para></listitem> + <listitem><para> + <filename>bzip2</filename> + </para></listitem> + <listitem><para> + <filename>cogl</filename> + </para></listitem> + <listitem><para> + <filename>curl</filename> + </para></listitem> + <listitem><para> + <filename>elfutils</filename> + </para></listitem> + <listitem><para> + <filename>gcc-target</filename> + </para></listitem> + <listitem><para> + <filename>libgcc</filename> + </para></listitem> + <listitem><para> + <filename>libtool</filename> + </para></listitem> + <listitem><para> + <filename>libxmu</filename> + </para></listitem> + <listitem><para> + <filename>opkg</filename> + </para></listitem> + <listitem><para> + <filename>pciutils</filename> + </para></listitem> + <listitem><para> + <filename>rpm</filename> + </para></listitem> + <listitem><para> + <filename>sysfsutils</filename> + </para></listitem> + <listitem><para> + <filename>tiff</filename> + </para></listitem> + <listitem><para> + <filename>xz</filename> + </para></listitem> + </itemizedlist> + All of the above recipes now conform to the standard packaging + scheme where a single <filename>-dev</filename>, + <filename>-dbg</filename>, and <filename>-staticdev</filename> + package exists per recipe. + </para> + </section> + + <section id='migration-2.0-recipe-maintenance-tracking-data-moved-to-oe-core'> + <title>Recipe Maintenance Tracking Data Moved to OE-Core</title> + + <para> + Maintenance tracking data for recipes that was previously part + of <filename>meta-yocto</filename> has been moved to + <link linkend='oe-core'>OE-Core</link>. + The change includes <filename>package_regex.inc</filename> and + <filename>distro_alias.inc</filename>, which are typically enabled + when using the + <link linkend='ref-classes-distrodata'><filename>distrodata</filename></link> + class. + Additionally, the contents of + <filename>upstream_tracking.inc</filename> has now been split out + to the relevant recipes. + </para> + </section> + + <section id='migration-2.0-automatic-stale-sysroot-file-cleanup'> + <title>Automatic Stale Sysroot File Cleanup</title> + + <para> + 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 + <filename>bblayers.conf</filename>, and + <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link> + changes. + </para> + + <para> + 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: + <literallayout class='monospaced'> + SSTATE_PRUNE_OBSOLETEWORKDIR = "0" + </literallayout> + </para> + </section> + + <section id='migration-2.0-linux-yocto-kernel-metadata-repository-now-split-from-source'> + <title><filename>linux-yocto</filename> Kernel Metadata Repository Now Split from Source</title> + + <para> + The <filename>linux-yocto</filename> 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. + </para> + + <para> + Metadata processing has now been removed from the + <link linkend='ref-classes-kernel-yocto'><filename>kernel-yocto</filename></link> + class and the external Metadata repository + <filename>yocto-kernel-cache</filename>, which has always been used + to seed the <filename>linux-yocto</filename> "meta" branch. + This separate <filename>linux-yocto</filename> cache repository + is now the primary location for this data. + Due to this change, <filename>linux-yocto</filename> 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 <filename>meta/recipes-kernel/linux/linux-yocto_4.1.bb</filename> + recipe for an example. + </para> + </section> + + <section id='migration-2.0-additional-qa-checks'> + <title>Additional QA checks</title> + + <para> + The following QA checks have been added: + <itemizedlist> + <listitem><para> + Added a "host-user-contaminated" check for ownership + issues for packaged files outside of + <filename>/home</filename>. + 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. + </para></listitem> + <listitem><para> + Added an "invalid-chars" check for invalid (non-UTF8) + characters in recipe metadata variable values + (i.e. + <link linkend='var-DESCRIPTION'><filename>DESCRIPTION</filename></link>, + <link linkend='var-SUMMARY'><filename>SUMMARY</filename></link>, + <link linkend='var-LICENSE'><filename>LICENSE</filename></link>, + and + <link linkend='var-SECTION'><filename>SECTION</filename></link>). + Some package managers do not support these characters. + </para></listitem> + <listitem><para> + Added an "invalid-packageconfig" check for any options + specified in + <link linkend='var-PACKAGECONFIG'><filename>PACKAGECONFIG</filename></link> + that do not match any <filename>PACKAGECONFIG</filename> + option defined for the recipe. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-2.0-miscellaneous'> + <title>Miscellaneous Changes</title> + + <para> + These additional changes exist: + <itemizedlist> + <listitem><para> + <filename>gtk-update-icon-cache</filename> has been + renamed to <filename>gtk-icon-utils</filename>. + </para></listitem> + <listitem><para> + The <filename>tools-profile</filename> + <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link> + item as well as its corresponding packagegroup and + <filename>packagegroup-core-tools-profile</filename> no + longer bring in <filename>oprofile</filename>. + Bringing in <filename>oprofile</filename> 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. + </para></listitem> + <listitem><para> + The + <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link> + variable's default value now specifies + <filename>ext4</filename> instead of + <filename>ext3</filename>. + </para></listitem> + <listitem><para> + All support for the <filename>PRINC</filename> + variable has been removed. + </para></listitem> + <listitem><para> + The <filename>packagegroup-core-full-cmdline</filename> + packagegroup no longer brings in + <filename>lighttpd</filename> due to the fact that + bringing in <filename>lighttpd</filename> 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 <filename>busybox</filename>. + </para></listitem> + </itemizedlist> + </para> + </section> +</section> + +<section id='moving-to-the-yocto-project-2.1-release'> + <title>Moving to the Yocto Project 2.1 Release</title> + + <para> + This section provides migration information for moving to the + Yocto Project 2.1 Release from the prior release. + </para> + + <section id='migration-2.1-variable-expansion-in-python-functions'> + <title>Variable Expansion in Python Functions</title> + + <para> + Variable expressions, such as + <filename>${</filename><replaceable>VARNAME</replaceable><filename>}</filename> + 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 <filename>d.getVar()</filename>. + To alternatively expand more complex expressions, + use <filename>d.expand()</filename>. + </para> + </section> + + <section id='migration-2.1-overrides-must-now-be-lower-case'> + <title>Overrides Must Now be Lower-Case</title> + + <para> + 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 + <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link> + must now appear in lower-case characters (e.g. values for + <filename>MACHINE</filename>, <filename>TARGET_ARCH</filename>, + <filename>DISTRO</filename>, and also recipe names if + <filename>_pn-</filename><replaceable>recipename</replaceable> + overrides are to be effective). + </para> + </section> + + <section id='migration-2.1-expand-parameter-to-getvar-and-getvarflag-now-mandatory'> + <title>Expand Parameter to <filename>getVar()</filename> and + <filename>getVarFlag()</filename> is Now Mandatory</title> + + <para> + The expand parameter to <filename>getVar()</filename> and + <filename>getVarFlag()</filename> previously defaulted to + False if not specified. + Now, however, no default exists so one must be specified. + You must change any <filename>getVar()</filename> calls that + do not specify the final expand parameter to calls that do specify + the parameter. + You can run the following <filename>sed</filename> command at the + base of a layer to make this change: + <literallayout class='monospaced'> + sed -e 's:\(\.getVar([^,()]*\)):\1, False):g' -i `grep -ril getVar *` + sed -e 's:\(\.getVarFlag([^,()]*, [^,()]*\)):\1, False):g' -i `grep -ril getVarFlag *` + </literallayout> + <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. + </note> + </para> + </section> + + <section id='migration-2.1-makefile-environment-changes'> + <title>Makefile Environment Changes</title> + + <para> + <link linkend='var-EXTRA_OEMAKE'><filename>EXTRA_OEMAKE</filename></link> + now defaults to "" instead of "-e MAKEFLAGS=". + Setting <filename>EXTRA_OEMAKE</filename> to "-e MAKEFLAGS=" by + default was a historical accident that has required many classes + (e.g. <filename>autotools</filename>, <filename>module</filename>) + 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 + <filename>EXTRA_OEMAKE</filename> back to "-e MAKEFLAGS=" or by + explicitly setting any required variable value overrides using + <filename>EXTRA_OEMAKE</filename>, 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. + </para> + </section> + + <section id='migration-2.1-libexecdir-reverted-to-prefix-libexec'> + <title><filename>libexecdir</filename> Reverted to <filename>${prefix}/libexec</filename></title> + + <para> + The use of <filename>${libdir}/${BPN}</filename> as + <filename>libexecdir</filename> is different as compared to all + other mainstream distributions, which either uses + <filename>${prefix}/libexec</filename> or + <filename>${libdir}</filename>. + The use is also contrary to the GNU Coding Standards + (i.e. <ulink url='https://www.gnu.org/prep/standards/html_node/Directory-Variables.html'></ulink>) + that suggest <filename>${prefix}/libexec</filename> and also + notes that any package-specific nesting should be done by the + package itself. + Finally, having <filename>libexecdir</filename> change between + recipes makes it very difficult for different recipes to invoke + binaries that have been installed into + <filename>libexecdir</filename>. + The Filesystem Hierarchy Standard + (i.e. <ulink url='http://refspecs.linuxfoundation.org/FHS_3.0/fhs/ch04s07.html'></ulink>) + now recognizes the use of <filename>${prefix}/libexec/</filename>, + giving distributions the choice between + <filename>${prefix}/lib</filename> or + <filename>${prefix}/libexec</filename> without breaking FHS. + </para> + </section> + + <section id='migration-2.1-ac-cv-sizeof-off-t-no-longer-cached-in-site-files'> + <title><filename>ac_cv_sizeof_off_t</filename> is No Longer Cached in Site Files</title> + + <para> + For recipes inheriting the + <link linkend='ref-classes-autotools'><filename>autotools</filename></link> + class, <filename>ac_cv_sizeof_off_t</filename> is no longer cached + in the site files for <filename>autoconf</filename>. + The reason for this change is because the + <filename>ac_cv_sizeof_off_t</filename> 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 <filename>autoconf</filename>, this + change should not be a problem. + However, if you have a recipe that bypasses the standard + <link linkend='ref-tasks-configure'><filename>do_configure</filename></link> + task from the <filename>autotools</filename> class and the software + the recipe is building uses a very old version of + <filename>autoconf</filename>, the recipe might be incapable of + determining the correct size of <filename>off_t</filename> during + <filename>do_configure</filename>. + </para> + + <para> + The best course of action is to patch the software as necessary + to allow the default implementation from the + <filename>autotools</filename> class to work such that + <filename>autoreconf</filename> succeeds and produces a working + configure script, and to remove the + overridden <filename>do_configure</filename> task such that the + default implementation does get used. + </para> + </section> + + <section id='migration-2.1-image-generation-split-out-from-filesystem-generation'> + <title>Image Generation is Now Split Out from Filesystem Generation</title> + + <para> + Previously, for image recipes the + <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link> + task assembled the filesystem and then from that filesystem + generated images. + With this Yocto Project release, image generation is split into + separate + <link linkend='ref-tasks-image'><filename>do_image_*</filename></link> + tasks for clarity both in operation and in the code. + </para> + + <para> + For most cases, this change does not present any problems. + However, if you have made customizations that directly modify the + <filename>do_rootfs</filename> task or that mention + <filename>do_rootfs</filename>, you might need to update those + changes. + In particular, if you had added any tasks after + <filename>do_rootfs</filename>, you should make edits so that + those tasks are after the + <link linkend='ref-tasks-image-complete'><filename>do_image_complete</filename></link> + task rather than after <filename>do_rootfs</filename> + so that the your added tasks + run at the correct time. + </para> + + <para> + A minor part of this restructuring is that the post-processing + definitions and functions have been moved from the + <link linkend='ref-classes-image'><filename>image</filename></link> + class to the + <link linkend='ref-classes-rootfs*'><filename>rootfs-postcommands</filename></link> + class. + Functionally, however, they remain unchanged. + </para> + </section> + + <section id='migration-2.1-removed-recipes'> + <title>Removed Recipes</title> + + <para> + The following recipes have been removed in the 2.1 release: + <itemizedlist> + <listitem><para><filename>gcc</filename> version 4.8: + Versions 4.9 and 5.3 remain. + </para></listitem> + <listitem><para><filename>qt4</filename>: + All support for Qt 4.x has been moved out to a separate + <filename>meta-qt4</filename> layer because Qt 4 is no + longer supported upstream. + </para></listitem> + <listitem><para><filename>x11vnc</filename>: + Moved to the <filename>meta-oe</filename> layer. + </para></listitem> + <listitem><para><filename>linux-yocto-3.14</filename>: + No longer supported. + </para></listitem> + <listitem><para><filename>linux-yocto-3.19</filename>: + No longer supported. + </para></listitem> + <listitem><para><filename>libjpeg</filename>: + Replaced by the <filename>libjpeg-turbo</filename> recipe. + </para></listitem> + <listitem><para><filename>pth</filename>: + Became obsolete. + </para></listitem> + <listitem><para><filename>liboil</filename>: + Recipe is no longer needed and has been moved to the + <filename>meta-multimedia</filename> layer. + </para></listitem> + <listitem><para><filename>gtk-theme-torturer</filename>: + Recipe is no longer needed and has been moved to the + <filename>meta-gnome</filename> layer. + </para></listitem> + <listitem><para><filename>gnome-mime-data</filename>: + Recipe is no longer needed and has been moved to the + <filename>meta-gnome</filename> layer. + </para></listitem> + <listitem><para><filename>udev</filename>: + Replaced by the <filename>eudev</filename> recipe for + compatibility when using <filename>sysvinit</filename> + with newer kernels. + </para></listitem> + <listitem><para><filename>python-pygtk</filename>: + Recipe became obsolete. + </para></listitem> + <listitem><para><filename>adt-installer</filename>: + Recipe became obsolete. + See the + "<link linkend='migration-2.1-adt-removed'>ADT Removed</link>" + section for more information. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-2.1-class-changes'> + <title>Class Changes</title> + + <para> + The following classes have changed: + <itemizedlist> + <listitem><para><filename>autotools_stage</filename>: + Removed because the + <link linkend='ref-classes-autotools'><filename>autotools</filename></link> + class now provides its functionality. + Recipes that inherited from + <filename>autotools_stage</filename> should now inherit + from <filename>autotools</filename> instead. + </para></listitem> + <listitem><para><filename>boot-directdisk</filename>: + Merged into the <filename>image-vm</filename> + class. + The <filename>boot-directdisk</filename> class was rarely + directly used. + Consequently, this change should not cause any issues. + </para></listitem> + <listitem><para><filename>bootimg</filename>: + Merged into the + <link linkend='ref-classes-image-live'><filename>image-live</filename></link> + class. + The <filename>bootimg</filename> class was rarely + directly used. + Consequently, this change should not cause any issues. + </para></listitem> + <listitem><para><filename>packageinfo</filename>: + Removed due to its limited use by the Hob UI, which has + itself been removed. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-2.1-build-system-ui-changes'> + <title>Build System User Interface Changes</title> + + <para> + The following changes have been made to the build system user + interface: + <itemizedlist> + <listitem><para><emphasis>Hob GTK+-based UI</emphasis>: + 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 + "<ulink url='&YOCTO_DOCS_TOAST_URL;#using-the-toaster-web-interface'>Using the Toaster Web Interface</ulink>" + section in the Toaster User Manual for more + information on this interface. + </para></listitem> + <listitem><para><emphasis>"puccho" BitBake UI</emphasis>: + Removed because is unmaintained and no longer useful. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-2.1-adt-removed'> + <title>ADT Removed</title> + + <para> + The Application Development Toolkit (ADT) has been removed + because its functionality almost completely overlapped with the + <ulink url='&YOCTO_DOCS_SDK_URL;#sdk-using-the-standard-sdk'>standard SDK</ulink> + and the + <ulink url='&YOCTO_DOCS_SDK_URL;#sdk-extensible'>extensible SDK</ulink>. + For information on these SDKs and how to build and use them, see the + <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink> + manual. + <note> + The Yocto Project Eclipse IDE Plug-in is still supported and + is not affected by this change. + </note> + </para> + </section> + + <section id='migration-2.1-poky-reference-distribution-changes'> + <title>Poky Reference Distribution Changes</title> + + <para> + The following changes have been made for the Poky distribution: + <itemizedlist> + <listitem><para> + The <filename>meta-yocto</filename> layer has been renamed + to <filename>meta-poky</filename> to better match its + purpose, which is to provide the Poky reference + distribution. + The <filename>meta-yocto-bsp</filename> layer retains its + original name since it provides reference machines for + the Yocto Project and it is otherwise unrelated to Poky. + References to <filename>meta-yocto</filename> in your + <filename>conf/bblayers.conf</filename> should + automatically be updated, so you should not need to change + anything unless you are relying on this naming elsewhere. + </para></listitem> + <listitem><para> + The + <link linkend='ref-classes-uninative'><filename>uninative</filename></link> + 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.</para> + + <para>The <filename>uninative</filename> class is enabled + through the + <filename>meta/conf/distro/include/yocto-uninative.inc</filename> + file, which for those not using the Poky distribution, can + include to easily enable the same functionality.</para> + + <para>Alternatively, if you wish to build your own + <filename>uninative</filename> tarball, you can do so by + building the <filename>uninative-tarball</filename> recipe, + making it available to your build machines + (e.g. over HTTP/HTTPS) and setting a similar configuration + as the one set by <filename>yocto-uninative.inc</filename>. + </para></listitem> + <listitem><para> + 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.</para> + + <para>Disabling this library generation is accomplished + through a + <filename>meta/conf/distro/include/no-static-libs.inc</filename>, + which for those not using the Poky distribution can + easily include to enable the same functionality.</para> + + <para>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: + <literallayout class='monospaced'> + DISABLE_STATIC = "" + </literallayout> + </para></listitem> + <listitem><para> + The separate <filename>poky-tiny</filename> distribution + now uses the musl C library instead of a heavily pared + down <filename>glibc</filename>. + Using musl results in a smaller + distribution and facilitates much greater maintainability + because musl is designed to have a small footprint.</para> + + <para>If you have used <filename>poky-tiny</filename> and + have customized the <filename>glibc</filename> + configuration you will need to redo those customizations + with musl when upgrading to the new release. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-2.1-packaging-changes'> + <title>Packaging Changes</title> + + <para> + The following changes have been made to packaging: + <itemizedlist> + <listitem><para> + The <filename>runuser</filename> and + <filename>mountpoint</filename> binaries, which were + previously in the main <filename>util-linux</filename> + package, have been split out into the + <filename>util-linux-runuser</filename> and + <filename>util-linux-mountpoint</filename> packages, + respectively. + </para></listitem> + <listitem><para> + The <filename>python-elementtree</filename> package has + been merged into the <filename>python-xml</filename> + package. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-2.1-tuning-file-changes'> + <title>Tuning File Changes</title> + + <para> + The following changes have been made to the tuning files: + <itemizedlist> + <listitem><para> + 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. + </note> + </para></listitem> + <listitem><para> + The <filename>tune-cortexm*.inc</filename> and + <filename>tune-cortexr4.inc</filename> 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. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-2.1-supporting-gobject-introspection'> + <title>Supporting GObject Introspection</title> + + <para> + 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 + "<ulink url='&YOCTO_DOCS_DEV_URL;#enabling-gobject-introspection-support'>Enabling GObject Introspection Support</ulink>" + section in the Yocto Project Development Tasks Manual + for more information. + </para> + </section> + + <section id='migration-2.1-miscellaneous-changes'> + <title>Miscellaneous Changes</title> + + <para> + These additional changes exist: + <itemizedlist> + <listitem><para> + 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 + "<link linkend='required-git-tar-and-python-versions'>Required Git, tar, and Python Versions</link>" + section for more information on the buildtools tarball. + </para></listitem> + <listitem><para> + 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. + </para></listitem> + <listitem><para> + Previously, the following list of packages were removed + if package-management was not in + <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>, + regardless of any dependencies: + <literallayout class='monospaced'> + update-rc.d + base-passwd + shadow + update-alternatives + run-postinsts + </literallayout> + With the Yocto Project 2.1 release, these packages are only + removed if "read-only-rootfs" is in + <filename>IMAGE_FEATURES</filename>, 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). + </para></listitem> + <listitem><para> + The + <ulink url='&YOCTO_DOCS_SDK_URL;#sdk-devtool-use-devtool-modify-to-modify-the-source-of-an-existing-component'><filename>devtool modify</filename></ulink> + 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 + <filename>devtool modify</filename>. + </para></listitem> + <listitem><para> + 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. + </para></listitem> + <listitem><para> + The <filename>.debug</filename> 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 + <filename>FILES_${PN}-dbg</filename> to pick up the + resulting <filename>.debug</filename> directories as these + directories are automatically found and added. + </para></listitem> + <listitem><para> + Inaccurate disk and CPU percentage data has been dropped + from <filename>buildstats</filename> output. + This data has been replaced with + <filename>getrusage()</filename> data and corrected IO + statistics. + You will probably need to update any custom code that reads + the <filename>buildstats</filename> data. + </para></listitem> + <listitem><para> + The + <filename>meta/conf/distro/include/package_regex.inc</filename> + is now deprecated. + The contents of this file have been moved to individual + recipes. + <note><title>Tip</title> + 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. + </note> + </para></listitem> + <listitem><para> + The <filename>v86d/uvesafb</filename> has been removed from + the <filename>genericx86</filename> and + <filename>genericx86-64</filename> reference machines, + which are provided by the + <filename>meta-yocto-bsp</filename> 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 + <filename>uvesafb</filename>, you can + simply add <filename>v86d</filename> to your image. + </para></listitem> + <listitem><para> + 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 <filename>IMAGE_GEN_DEBUGFS</filename> to "1", + which will generate a companion debug image + containing unstripped binaries and associated debug + sources alongside the image. + </para></listitem> + </itemizedlist> + </para> + </section> +</section> + +<section id='moving-to-the-yocto-project-2.2-release'> + <title>Moving to the Yocto Project 2.2 Release</title> + + <para> + This section provides migration information for moving to the + Yocto Project 2.2 Release from the prior release. + </para> + + <section id='migration-2.2-minimum-kernel-version'> + <title>Minimum Kernel Version</title> + + <para> + The minimum kernel version for the target system and for SDK + is now 3.2.0, due to the upgrade + to <filename>glibc 2.24</filename>. + 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 + <link linkend='var-OLDEST_KERNEL'><filename>OLDEST_KERNEL</filename></link> + to anything down to 2.6.32 if desired. + </note> + </para> + </section> + + <section id='migration-2.2-staging-directories-in-sysroot-simplified'> + <title>Staging Directories in Sysroot Has Been Simplified</title> + + <para> + The way directories are staged in sysroot has been simplified and + introduces the new + <link linkend='var-SYSROOT_DIRS'><filename>SYSROOT_DIRS</filename></link>, + <link linkend='var-SYSROOT_DIRS_NATIVE'><filename>SYSROOT_DIRS_NATIVE</filename></link>, + and + <link linkend='var-SYSROOT_DIRS_BLACKLIST'><filename>SYSROOT_DIRS_BLACKLIST</filename></link>. + See the + <ulink url='http://lists.openembedded.org/pipermail/openembedded-core/2016-May/121365.html'>v2 patch series on the OE-Core Mailing List</ulink> + for additional information. + </para> + </section> + + <section id='migration-2.2-removal-of-old-images-from-tmp-deploy-now-enabled'> + <title>Removal of Old Images and Other Files in <filename>tmp/deploy</filename> Now Enabled</title> + + <para> + Removal of old images and other files in + <filename>tmp/deploy/</filename> is now enabled by default due + to a new staging method used for those files. + As a result of this change, the + <filename>RM_OLD_IMAGE</filename> variable is now redundant. + </para> + </section> + + <section id='migration-2.2-python-changes'> + <title>Python Changes</title> + + <para> + The following changes for Python occurred: + </para> + + <section id='migration-2.2-bitbake-now-requires-python-3.4'> + <title>BitBake Now Requires Python 3.4+</title> + + <para> + BitBake requires Python 3.4 or greater. + </para> + </section> + + <section id='migration-2.2-utf-8-locale-required-on-build-host'> + <title>UTF-8 Locale Required on Build Host</title> + + <para> + 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. + </para> + </section> + + <section id='migration-2.2-metadata-now-must-use-python-3-syntax'> + <title>Metadata Must Now Use Python 3 Syntax</title> + + <para> + 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 + <link linkend='oe-core'>OE-Core</link> as a guide for changes. + Following are particular areas of interest: + <literallayout class='monospaced'> + * subprocess command-line pipes needing locale decoding + * the syntax for octal values changed + * the <filename>iter*()</filename> functions changed name + * iterators now return views, not lists + * changed names for Python modules + </literallayout> + </para> + </section> + + <section id='migration-2.2-target-python-recipes-switched-to-python-3'> + <title>Target Python Recipes Switched to Python 3</title> + + <para> + 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. + </note> + </para> + </section> + + <section id='migration-2.2-buildtools-tarball-includes-python-3'> + <title><filename>buildtools-tarball</filename> Includes Python 3</title> + + <para> + <filename>buildtools-tarball</filename> now includes Python 3. + </para> + </section> + </section> + + <section id='migration-2.2-uclibc-replaced-by-musl'> + <title>uClibc Replaced by musl</title> + + <para> + 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. + </para> + </section> + + <section id='migration-2.2-B-no-longer-default-working-directory-for-tasks'> + <title><filename>${B}</filename> No Longer Default Working Directory for Tasks</title> + + <para> + <filename>${</filename><link linkend='var-B'><filename>B</filename></link><filename>}</filename> + is no longer the default working directory for tasks. + Consequently, any custom tasks you define now need to either + have the + <filename>[</filename><ulink url='&YOCTO_DOCS_BB_URL;#variable-flags'><filename>dirs</filename></ulink><filename>]</filename> flag set, or the task needs to change into the + appropriate working directory manually (e.g using + <filename>cd</filename> for a shell task). + <note> + The preferred method is to use the + <filename>[dirs]</filename> flag. + </note> + </para> + </section> + + <section id='migration-2.2-runqemu-ported-to-python'> + <title><filename>runqemu</filename> Ported to Python</title> + + <para> + <filename>runqemu</filename> has been ported to Python and has + changed behavior in some cases. + Previous usage patterns continue to be supported. + </para> + + <para> + The new <filename>runqemu</filename> is a Python script. + Machine knowledge is no longer hardcoded into + <filename>runqemu</filename>. + You can choose to use the <filename>qemuboot</filename> + configuration file to define the BSP's own arguments and to make + it bootable with <filename>runqemu</filename>. + If you use a configuration file, use the following form: + <literallayout class='monospaced'> + <replaceable>image-name</replaceable>-<replaceable>machine</replaceable>.qemuboot.conf + </literallayout> + The configuration file enables fine-grained tuning of options + passed to QEMU without the <filename>runqemu</filename> 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 + <filename>qemu*</filename> machines in + <link linkend='oe-core'>OE-Core</link>. + The <filename>qemuboot.conf</filename> file is generated by the + <filename>qemuboot</filename> + 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 <filename>qemuboot</filename> class will save them to + <filename>qemuboot.conf</filename>. + </para> + + + <para> + If you want to use <filename>runqemu</filename> without a + configuration file, use the following command form: + <literallayout class='monospaced'> + $ runqemu <replaceable>machine</replaceable> <replaceable>rootfs</replaceable> <replaceable>kernel</replaceable> [<replaceable>options</replaceable>] + </literallayout> + Supported <replaceable>machines</replaceable> are as follows: + <literallayout class='monospaced'> + qemuarm + qemuarm64 + qemux86 + qemux86-64 + qemuppc + qemumips + qemumips64 + qemumipsel + qemumips64el + </literallayout> + Consider the following example, which uses the + <filename>qemux86-64</filename> machine, + provides a root filesystem, provides an image, and uses + the <filename>nographic</filename> option: + <literallayout class='monospaced'> +$ runqemu qemux86-64 tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64.ext4 tmp/deploy/images/qemux86-64/bzImage nographic + </literallayout> + </para> + + <para> + Following is a list of variables that can be set in configuration + files such as <filename>bsp.conf</filename> to enable the BSP + to be booted by <filename>runqemu</filename>: + <note> + "QB" means "QEMU Boot". + </note> + <literallayout class='monospaced'> + 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. + </literallayout> + </para> + + <para> + To use <filename>runqemu</filename>, set + <link linkend='var-IMAGE_CLASSES'><filename>IMAGE_CLASSES</filename></link> + as follows and run <filename>runqemu</filename>: + <note> + For command-line syntax, use + <filename>runqemu help</filename>. + </note> + <literallayout class='monospaced'> + IMAGE_CLASSES += "qemuboot" + </literallayout> + </para> + </section> + + <section id='migration-2.2-default-linker-hash-style-changed'> + <title>Default Linker Hash Style Changed</title> + + <para> + The default linker hash style for <filename>gcc-cross</filename> + is now "sysv" in order to catch recipes that are building software + without using the OpenEmbedded + <link linkend='var-LDFLAGS'><filename>LDFLAGS</filename></link>. + 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 + <filename>LDFLAGS</filename>. + 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: + <literallayout class='monospaced'> + TARGET_CC_ARCH += "${LDFLAGS}" + </literallayout> + </para> + </section> + + <section id='migration-2.2-kernel-image-base-name-no-longer-uses-kernel-imagetype'> + <title><filename>KERNEL_IMAGE_BASE_NAME</filename> no Longer Uses <filename>KERNEL_IMAGETYPE</filename></title> + + <para> + The + <link linkend='var-KERNEL_IMAGE_BASE_NAME'><filename>KERNEL_IMAGE_BASE_NAME</filename></link> + variable no longer uses the + <link linkend='var-KERNEL_IMAGETYPE'><filename>KERNEL_IMAGETYPE</filename></link> + 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: + <literallayout class='monospaced'> + KERNEL_IMAGE_BASE_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}-${DATETIME} + </literallayout> + If you have recipes or classes that use + <filename>KERNEL_IMAGE_BASE_NAME</filename> directly, you might + need to update the references to ensure they continue to work. + </para> + </section> + + <section id='migration-2.2-bitbake-changes'> + <title>BitBake Changes</title> + + <para> + The following changes took place for BitBake: + <itemizedlist> + <listitem><para> + The "goggle" UI and standalone image-writer tool have + been removed as they both require GTK+ 2.0 and + were not being maintained. + </para></listitem> + <listitem><para> + The Perforce fetcher now supports + <link linkend='var-SRCREV'><filename>SRCREV</filename></link> + for specifying the source revision to use, be it + <filename>${</filename><link linkend='var-AUTOREV'><filename>AUTOREV</filename></link><filename>}</filename>, + changelist number, p4date, or label, in preference to + separate + <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link> + 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 <filename>SRCREV</filename> in place of specifying + the source revision within + <filename>SRC_URI</filename>. + </para></listitem> + <listitem><para> + 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: + <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/poky/commit/?id=189371f8393971d00bca0fceffd67cc07784f6ee'>1</ulink> + and + <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/poky/commit/?id=4a5aa7ea4d07c2c90a1654b174873abb018acc67'>2</ulink>. + </para></listitem> + <listitem><para> + 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 <filename>BB_SETSCENE_VERIFY_FUNCTION</filename> + needed to change signature. + Consequently, a new variable named + <filename>BB_SETSCENE_VERIFY_FUNCTION2</filename> + 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. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-2.2-swabber-has-been-removed'> + <title>Swabber has Been Removed</title> + + <para> + 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. + </para> + </section> + + <section id='migration-2.2-removed-recipes'> + <title>Removed Recipes</title> + + <para> + The following recipes have been removed: + <itemizedlist> + <listitem><para> + <filename>augeas</filename>: + No longer needed and has been moved to + <filename>meta-oe</filename>. + </para></listitem> + <listitem><para> + <filename>directfb</filename>: + Unmaintained and has been moved to + <filename>meta-oe</filename>. + </para></listitem> + <listitem><para> + <filename>gcc</filename>: + Removed 4.9 version. + Versions 5.4 and 6.2 are still present. + </para></listitem> + <listitem><para> + <filename>gnome-doc-utils</filename>: + No longer needed. + </para></listitem> + <listitem><para> + <filename>gtk-doc-stub</filename>: + Replaced by <filename>gtk-doc</filename>. + </para></listitem> + <listitem><para> + <filename>gtk-engines</filename>: + No longer needed and has been moved to + <filename>meta-gnome</filename>. + </para></listitem> + <listitem><para> + <filename>gtk-sato-engine</filename>: + Became obsolete. + </para></listitem> + <listitem><para> + <filename>libglade</filename>: + No longer needed and has been moved to + <filename>meta-oe</filename>. + </para></listitem> + <listitem><para> + <filename>libmad</filename>: + Unmaintained and functionally replaced by + <filename>libmpg123</filename>. + <filename>libmad</filename> has been moved to + <filename>meta-oe</filename>. + </para></listitem> + <listitem><para> + <filename>libowl</filename>: + Became obsolete. + </para></listitem> + <listitem><para> + <filename>libxsettings-client</filename>: + No longer needed. + </para></listitem> + <listitem><para> + <filename>oh-puzzles</filename>: + Functionally replaced by + <filename>puzzles</filename>. + </para></listitem> + <listitem><para> + <filename>oprofileui</filename>: + Became obsolete. + OProfile has been largely supplanted by perf. + </para></listitem> + <listitem><para> + <filename>packagegroup-core-directfb.bb</filename>: + Removed. + </para></listitem> + <listitem><para> + <filename>core-image-directfb.bb</filename>: + Removed. + </para></listitem> + <listitem><para> + <filename>pointercal</filename>: + No longer needed and has been moved to + <filename>meta-oe</filename>. + </para></listitem> + <listitem><para> + <filename>python-imaging</filename>: + No longer needed and moved to + <filename>meta-python</filename> + </para></listitem> + <listitem><para> + <filename>python-pyrex</filename>: + No longer needed and moved to + <filename>meta-python</filename>. + </para></listitem> + <listitem><para> + <filename>sato-icon-theme</filename>: + Became obsolete. + </para></listitem> + <listitem><para> + <filename>swabber-native</filename>: + Swabber has been removed. + See the + <link linkend='migration-2.2-swabber-has-been-removed'>entry on Swabber</link>. + </para></listitem> + <listitem><para> + <filename>tslib</filename>: + No longer needed and has been moved to + <filename>meta-oe</filename>. + </para></listitem> + <listitem><para> + <filename>uclibc</filename>: + Removed in favor of musl. + </para></listitem> + <listitem><para> + <filename>xtscal</filename>: + No longer needed and moved to + <filename>meta-oe</filename> + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-2.2-removed-classes'> + <title>Removed Classes</title> + + <para> + The following classes have been removed: + <itemizedlist> + <listitem><para> + <filename>distutils-native-base</filename>: + No longer needed. + </para></listitem> + <listitem><para> + <filename>distutils3-native-base</filename>: + No longer needed. + </para></listitem> + <listitem><para> + <filename>sdl</filename>: + Only set + <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link> + and + <link linkend='var-SECTION'><filename>SECTION</filename></link>, + which are better set within the recipe instead. + </para></listitem> + <listitem><para> + <filename>sip</filename>: + Mostly unused. + </para></listitem> + <listitem><para> + <filename>swabber</filename>: + See the + <link linkend='migration-2.2-swabber-has-been-removed'>entry on Swabber</link>. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-2.2-minor-packaging-changes'> + <title>Minor Packaging Changes</title> + + <para> + The following minor packaging changes have occurred: + <itemizedlist> + <listitem><para> + <filename>grub</filename>: + Split <filename>grub-editenv</filename> into its own + package. + </para></listitem> + <listitem><para> + <filename>systemd</filename>: + Split container and vm related units into a new package, + systemd-container. + </para></listitem> + <listitem><para> + <filename>util-linux</filename>: + Moved <filename>prlimit</filename> to a separate + <filename>util-linux-prlimit</filename> package. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-2.2-miscellaneous-changes'> + <title>Miscellaneous Changes</title> + + <para> + The following miscellaneous changes have occurred: + <itemizedlist> + <listitem><para> + <filename>package_regex.inc</filename>: + Removed because the definitions + <filename>package_regex.inc</filename> previously contained + have been moved to their respective recipes. + </para></listitem> + <listitem><para> + Both <filename>devtool add</filename> and + <filename>recipetool create</filename> now use a fixed + <link linkend='var-SRCREV'><filename>SRCREV</filename></link> + by default when fetching from a Git repository. + You can override this in either case to use + <filename>${</filename><link linkend='var-AUTOREV'><filename>AUTOREV</filename></link><filename>}</filename> + instead by using the <filename>-a</filename> or + <filename>‐‐autorev</filename> command-line + option + </para></listitem> + <listitem><para> + <filename>distcc</filename>: + GTK+ UI is now disabled by default. + </para></listitem> + <listitem><para> + <filename>packagegroup-core-tools-testapps</filename>: + Removed Piglit. + </para></listitem> + <listitem><para> + <filename>image.bbclass</filename>: + Renamed COMPRESS(ION) to CONVERSION. + This change means that + <filename>COMPRESSIONTYPES</filename>, + <filename>COMPRESS_DEPENDS</filename> and + <filename>COMPRESS_CMD</filename> are deprecated in favor + of <filename>CONVERSIONTYPES</filename>, + <filename>CONVERSION_DEPENDS</filename> and + <filename>CONVERSION_CMD</filename>. + The <filename>COMPRESS*</filename> 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 <filename>COMPRESS*</filename> + ones will be removed in a future release. + </para></listitem> + <listitem><para> + <filename>gtk-doc</filename>: + A full version of <filename>gtk-doc</filename> is now + made available. + However, some old software might not be capable of using + the current version of <filename>gtk-doc</filename> + to build documentation. + You need to change recipes that build such software so that + they explicitly disable building documentation with + <filename>gtk-doc</filename>. + </para></listitem> + </itemizedlist> + </para> + </section> +</section> + +<section id='moving-to-the-yocto-project-2.3-release'> + <title>Moving to the Yocto Project 2.3 Release</title> + + <para> + This section provides migration information for moving to the + Yocto Project 2.3 Release from the prior release. + </para> + + <section id='migration-2.3-recipe-specific-sysroots'> + <title>Recipe-specific Sysroots</title> + + <para> + 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. + </para> + + <para> + Consider the following: + <itemizedlist> + <listitem><para> + <emphasis>Declare Build-Time Dependencies:</emphasis> + 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. + </para></listitem> + <listitem><para> + <emphasis>Specify Pre-Installation and Post-Installation + Native Tool Dependencies:</emphasis> + You must specifically specify any special native tool + dependencies of <filename>pkg_preinst</filename> and + <filename>pkg_postinst</filename> scripts by using the + <link linkend='var-PACKAGE_WRITE_DEPS'><filename>PACKAGE_WRITE_DEPS</filename></link> + variable. + Specifying these dependencies ensures that these tools + are available if these scripts need to be run on the + build host during the + <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link> + task.</para> + + <para>As an example, see the <filename>dbus</filename> + recipe. + You will see that this recipe has a + <filename>pkg_postinst</filename> that calls + <filename>systemctl</filename> if "systemd" is in + <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>. + In the example, + <filename>systemd-systemctl-native</filename> is added to + <filename>PACKAGE_WRITE_DEPS</filename>, which is also + conditional on "systemd" being in + <filename>DISTRO_FEATURES</filename>. + </para></listitem> + <listitem><para> + <emphasis>Examine Recipes that Use + <filename>SSTATEPOSTINSTFUNCS</filename>:</emphasis> + You need to examine any recipe that uses + <filename>SSTATEPOSTINSTFUNCS</filename> and determine + steps to take.</para> + + <para>Functions added to + <filename>SSTATEPOSTINSTFUNCS</filename> 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 <filename>SSTATEPOSTINSTFUNCS</filename> are + doing relocation, then you will need to change these + to use a post-installation script that is installed by a + function added to + <link linkend='var-SYSROOT_PREPROCESS_FUNCS'><filename>SYSROOT_PREPROCESS_FUNCS</filename></link>. + </para> + + <para>For an example, see the + <filename>pixbufcache</filename> class in + <filename>meta/classes/</filename> in the Yocto Project + <ulink url='&YOCTO_DOCS_OM_URL;#source-repositories'>Source Repositories</ulink>. + <note> + The <filename>SSTATEPOSTINSTFUNCS</filename> variable + itself is now deprecated in favor of the + <filename>do_populate_sysroot[postfuncs]</filename> + 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 + <filename>SSTATEPOSTINSTFUNCS</filename> is + removed in a future Yocto Project release. + </note> + </para></listitem> + <listitem><para> + <emphasis>Specify the Sysroot when Using Certain + External Scripts:</emphasis> + Because the shared sysroot is now gone, the scripts + <filename>oe-find-native-sysroot</filename> and + <filename>oe-run-native</filename> have been changed such + that you need to specify which recipe's + <link linkend='var-STAGING_DIR_NATIVE'><filename>STAGING_DIR_NATIVE</filename></link> + is used. + </para></listitem> + </itemizedlist> + <note> + You can find more information on how recipe-specific sysroots + work in the + "<link linkend='ref-classes-staging'><filename>staging.bbclass</filename></link>" + section. + </note> + </para> + </section> + + <section id='migration-2.3-path-variable'> + <title><filename>PATH</filename> Variable</title> + + <para> + Within the environment used to run build tasks, the environment + variable <filename>PATH</filename> is now sanitized such that + the normal native binary paths + (<filename>/bin</filename>, <filename>/sbin</filename>, + <filename>/usr/bin</filename> and so forth) are + removed and a directory containing symbolic links linking only + to the binaries from the host mentioned in the + <link linkend='var-HOSTTOOLS'><filename>HOSTTOOLS</filename></link> + and + <link linkend='var-HOSTTOOLS_NONFATAL'><filename>HOSTTOOLS_NONFATAL</filename></link> + variables is added to <filename>PATH</filename>. + </para> + + <para> + 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. + </para> + + <para> + Alternatively, you can add a native recipe (i.e. + <filename>-native</filename>) that provides the + binary to the recipe's + <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link> + value. + <note> + <filename>PATH</filename> is not sanitized in the same way + within <filename>devshell</filename>. + If it were, you would have difficulty running host tools for + development and debugging within the shell. + </note> + </para> + </section> + + <section id='migration-2.3-scripts'> + <title>Changes to Scripts</title> + + <para> + The following changes to scripts took place: + <itemizedlist> + <listitem><para> + <emphasis><filename>oe-find-native-sysroot</filename>:</emphasis> + The usage for the + <filename>oe-find-native-sysroot</filename> script has + changed to the following: + <literallayout class='monospaced'> + $ . oe-find-native-sysroot <replaceable>recipe</replaceable> + </literallayout> + You must now supply a recipe for + <replaceable>recipe</replaceable> as part of the command. + Prior to the Yocto Project &DISTRO; release, it was not + necessary to provide the script with the command. + </para></listitem> + <listitem><para> + <emphasis><filename>oe-run-native</filename>:</emphasis> + The usage for the + <filename>oe-run-native</filename> script has changed + to the following: + <literallayout class='monospaced'> + $ oe-run-native <replaceable>native_recipe</replaceable> <replaceable>tool</replaceable> + </literallayout> + 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. + </para></listitem> + <listitem><para> + <emphasis><filename>cleanup-workdir</filename>:</emphasis> + The <filename>cleanup-workdir</filename> 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 + <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link> + and getting it wrong, it is recommended that you + delete <filename>TMPDIR</filename> and have it restored + from shared state (sstate) on subsequent builds. + </para></listitem> + <listitem><para> + <emphasis><filename>wipe-sysroot</filename>:</emphasis> + The <filename>wipe-sysroot</filename> script has been + removed as it is no longer needed with recipe-specific + sysroots. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-2.3-functions'> + <title>Changes to Functions</title> + + <para> + The previously deprecated + <filename>bb.data.getVar()</filename>, + <filename>bb.data.setVar()</filename>, and + related functions have been removed in favor of + <filename>d.getVar()</filename>, + <filename>d.setVar()</filename>, and so forth. + </para> + + <para> + You need to fix any references to these old functions. + </para> + </section> + + <section id='migration-2.3-bitbake-changes'> + <title>BitBake Changes</title> + + <para> + The following changes took place for BitBake: + <itemizedlist> + <listitem><para> + <emphasis>BitBake's Graphical Dependency Explorer UI Replaced:</emphasis> + BitBake's graphical dependency explorer UI + <filename>depexp</filename> was replaced by + <filename>taskexp</filename> ("Task Explorer"), which + provides a graphical way of exploring the + <filename>task-depends.dot</filename> file. + The data presented by Task Explorer is much more + accurate than the data that was presented by + <filename>depexp</filename>. + Being able to visualize the data is an often requested + feature as standard <filename>*.dot</filename> file + viewers cannot usual cope with the size of + the <filename>task-depends.dot</filename> file. + </para></listitem> + <listitem><para> + <emphasis>BitBake "-g" Output Changes:</emphasis> + The <filename>package-depends.dot</filename> and + <filename>pn-depends.dot</filename> files as previously + generated using the <filename>bitbake -g</filename> command + have been removed. + A <filename>recipe-depends.dot</filename> file + is now generated as a collapsed version of + <filename>task-depends.dot</filename> instead. + </para> + + <para>The reason for this change is because + <filename>package-depends.dot</filename> and + <filename>pn-depends.dot</filename> 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. + </para></listitem> + <listitem><para> + <emphasis>Mirror Variable Splitting Changes:</emphasis> + Mirror variables including + <link linkend='var-MIRRORS'><filename>MIRRORS</filename></link>, + <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>, + and + <link linkend='var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></link> + 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. + </para></listitem> + <listitem><para> + <emphasis>The Subversion (SVN) Fetcher Uses an "ssh" Parameter and Not an "rsh" Parameter:</emphasis> + 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 + <filename>ssh</filename> program used by SVN. + The SVN fetcher passes the new parameter through the + <filename>SVN_SSH</filename> environment variable during + the + <link linkend='ref-tasks-fetch'><filename>do_fetch</filename></link> + task.</para> + + <para>See the + "<ulink url='&YOCTO_DOCS_BB_URL;#svn-fetcher'>Subversion (SVN) Fetcher (svn://)</ulink>" + section in the BitBake User Manual for additional + information. + </para></listitem> + <listitem><para> + <emphasis><filename>BB_SETSCENE_VERIFY_FUNCTION</filename> + and <filename>BB_SETSCENE_VERIFY_FUNCTION2</filename> + Removed:</emphasis> + Because the mechanism they were part of is no longer + necessary with recipe-specific sysroots, the + <filename>BB_SETSCENE_VERIFY_FUNCTION</filename> and + <filename>BB_SETSCENE_VERIFY_FUNCTION2</filename> + variables have been removed. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-2.3-absolute-symlinks'> + <title>Absolute Symbolic Links</title> + + <para> + Absolute symbolic links (symlinks) within staged files are no + longer permitted and now trigger an error. + Any explicit creation of symlinks can use the + <filename>lnr</filename> script, which is a replacement for + <filename>ln -r</filename>. + </para> + + <para> + 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 + <filename>relative_symlinks</filename> within the recipe to turn + those absolute symlinks into relative symlinks. + </para> + </section> + + <section id='migration-2.3-gplv2-and-gplv3-moves'> + <title>GPLv2 Versions of GPLv3 Recipes Moved</title> + + <para> + Older GPLv2 versions of GPLv3 recipes have moved to a + separate <filename>meta-gplv2</filename> layer. + </para> + + <para> + If you use + <link linkend='var-INCOMPATIBLE_LICENSE'><filename>INCOMPATIBLE_LICENSE</filename></link> + to exclude GPLv3 or set + <link linkend='var-PREFERRED_VERSION'><filename>PREFERRED_VERSION</filename></link> + to substitute a GPLv2 version of a GPLv3 recipe, then you must add + the <filename>meta-gplv2</filename> layer to your configuration. + <note> + You can find <filename>meta-gplv2</filename> layer in the + OpenEmbedded layer index at + <ulink url='https://layers.openembedded.org/layerindex/branch/master/layer/meta-gplv2/'></ulink>. + </note> + </para> + + <para> + 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. + </note> + </para> + </section> + + <section id='migration-2.3-package-management-changes'> + <title>Package Management Changes</title> + + <para> + The following package management changes took place: + <itemizedlist> + <listitem><para> + 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.</para> + <para>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.</para> + <para>For more information, see the + <ulink url='http://dnf.readthedocs.io/en/latest/'>DNF Documentation</ulink>. + </para></listitem> + <listitem><para> + Rpm 5.x is replaced with Rpm 4.x. + This is done for two major reasons: + <itemizedlist> + <listitem><para> + DNF is API-incompatible with Rpm 5.x and porting + it and maintaining the port is non-trivial. + </para></listitem> + <listitem><para> + Rpm 5.x itself has limited maintenance upstream, + and the Yocto Project is one of the very few + remaining users. + </para></listitem> + </itemizedlist> + </para></listitem> + <listitem><para> + Berkeley DB 6.x is removed and Berkeley DB 5.x becomes + the default: + <itemizedlist> + <listitem><para> + 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. + </para></listitem> + <listitem><para> + 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. + </para></listitem> + </itemizedlist> + </para></listitem> + <listitem><para> + <filename>createrepo</filename> is replaced with + <filename>createrepo_c</filename>.</para> + <para><filename>createrepo_c</filename> is the current + incarnation of the tool that generates remote repository + metadata. + It is written in C as compared to + <filename>createrepo</filename>, which is written in + Python. + <filename>createrepo_c</filename> is faster and is + maintained. + </para></listitem> + <listitem><para> + Architecture-independent RPM packages are "noarch" + instead of "all".</para> + <para>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 + <link linkend='ref-classes-allarch'><filename>allarch.bbclass</filename></link> + class. + </para></listitem> + <listitem><para> + Signing of remote package feeds using + <filename>PACKAGE_FEED_SIGN</filename> + is not currently supported. + This issue will be fully addressed in a future + Yocto Project release. + See <ulink url='https://bugzilla.yoctoproject.org/show_bug.cgi?id=11209'>defect 11209</ulink> + for more information on a solution to package feed + signing with RPM in the Yocto Project 2.3 release. + </para></listitem> + <listitem><para> + 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 + <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/poky/commit/? +id=f4d4f99cfbc2396e49c1613a7d237b9e57f06f81'>commit message</ulink>. + </note> + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-2.3-removed-recipes'> + <title>Removed Recipes</title> + + <para> + The following recipes have been removed: + <itemizedlist> + <listitem><para> + <emphasis><filename>linux-yocto 4.8:</filename></emphasis> + Version 4.8 has been removed. + Versions 4.1 (LTSI), 4.4 (LTS), 4.9 (LTS/LTSI) and 4.10 + are now present. + </para></listitem> + <listitem><para> + <emphasis><filename>python-smartpm:</filename></emphasis> + Functionally replaced by <filename>dnf</filename>. + </para></listitem> + <listitem><para> + <emphasis><filename>createrepo:</filename></emphasis> + Replaced by the <filename>createrepo-c</filename> recipe. + </para></listitem> + <listitem><para> + <emphasis><filename>rpmresolve:</filename></emphasis> + No longer needed with the move to RPM 4 as RPM itself is + used instead. + </para></listitem> + <listitem><para> + <emphasis><filename>gstreamer:</filename></emphasis> + Removed the GStreamer Git version recipes as they have + been stale. + <filename>1.10.</filename><replaceable>x</replaceable> + recipes are still present. + </para></listitem> + <listitem><para> + <emphasis><filename>alsa-conf-base:</filename></emphasis> + Merged into <filename>alsa-conf</filename> since + <filename>libasound</filename> depended on both. + Essentially, no way existed to install only one of these. + </para></listitem> + <listitem><para> + <emphasis><filename>tremor:</filename></emphasis> + Moved to <filename>meta-multimedia</filename>. + 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 + <filename>tremor</filename> recipe in + <link linkend='oe-core'>OE-Core</link>. + </para></listitem> + <listitem><para> + <emphasis><filename>gummiboot:</filename></emphasis> + Replaced by <filename>systemd-boot</filename>. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-2.3-wic-changes'> + <title>Wic Changes</title> + + <para> + The following changes have been made to Wic: + <note> + For more information on Wic, see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-partitioned-images-using-wic'>Creating Partitioned Images Using Wic</ulink>" + section in the Yocto Project Development Tasks Manual. + </note> + <itemizedlist> + <listitem><para> + <emphasis>Default Output Directory Changed:</emphasis> + Wic's default output directory is now the current directory + by default instead of the unusual + <filename>/var/tmp/wic</filename>.</para> + + <para>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. + </para></listitem> + <listitem><para> + <emphasis>fsimage Plug-in Removed:</emphasis> + The Wic fsimage plug-in has been removed as it duplicates + functionality of the rawcopy plug-in. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-2.3-qa-changes'> + <title>QA Changes</title> + + <para> + The following QA checks have changed: + <itemizedlist> + <listitem><para> + <emphasis><filename>unsafe-references-in-binaries</filename>:</emphasis> + The <filename>unsafe-references-in-binaries</filename> + QA check, which was disabled by default, has now been + removed. + This check was intended to detect binaries in + <filename>/bin</filename> that link to libraries in + <filename>/usr/lib</filename> and have the case where + the user has <filename>/usr</filename> on a separate + filesystem to <filename>/</filename>.</para> + + <para>The removed QA check was buggy. + Additionally, <filename>/usr</filename> residing on a + separate partition from <filename>/</filename> is now + a rare configuration. + Consequently, + <filename>unsafe-references-in-binaries</filename> was + removed. + </para></listitem> + <listitem><para> + <emphasis><filename>file-rdeps</filename>:</emphasis> + The <filename>file-rdeps</filename> 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.</para> + + <para>For additional information, see the + <link linkend='ref-classes-insane'><filename>insane</filename></link> + class and the + "<link linkend='qa-errors-and-warnings'>Errors and Warnings</link>" + section. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-2.3-miscellaneous-changes'> + <title>Miscellaneous Changes</title> + + <para> + The following miscellaneous changes have occurred: + <itemizedlist> + <listitem><para> + In this release, a number of recipes have been changed to + ignore the <filename>largefile</filename> + <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link> + 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 + <filename>largefile</filename> feature, + which would make it unconditionally enabled everywhere. + </note> + </para></listitem> + <listitem><para> + If the + <link linkend='var-DISTRO_VERSION'><filename>DISTRO_VERSION</filename></link> + value contains the value of the + <link linkend='var-DATE'><filename>DATE</filename></link> + variable, which is the default between Poky releases, + the <filename>DATE</filename> value is explicitly excluded + from <filename>/etc/issue</filename> and + <filename>/etc/issue.net</filename>, which is displayed at + the login prompt, in order to avoid conflicts with + Multilib enabled. + Regardless, the <filename>DATE</filename> value is + inaccurate if the <filename>base-files</filename> + recipe is restored from shared state (sstate) rather + than rebuilt.</para> + + <para>If you need the build date recorded in + <filename>/etc/issue*</filename> 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 + <link linkend='var-ROOTFS_POSTPROCESS_COMMAND'><filename>ROOTFS_POSTPROCESS_COMMAND</filename></link>. + Doing so ensures the value is always up-to-date with the + created image. + </para></listitem> + <listitem><para> + Dropbear's <filename>init</filename> 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. + </para></listitem> + <listitem><para> + The + <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link> + class now correctly uses tabs as separators between all + columns in <filename>installed-package-sizes.txt</filename> + in order to aid import into other tools. + </para></listitem> + <listitem><para> + The <filename>USE_LDCONFIG</filename> variable has been + replaced with the "ldconfig" + <filename>DISTRO_FEATURES</filename> feature. + Distributions that previously set: + <literallayout class='monospaced'> + USE_LDCONFIG = "0" + </literallayout> + should now instead use the following: + <literallayout class='monospaced'> + DISTRO_FEATURES_BACKFILL_CONSIDERED_append = " ldconfig" + </literallayout> + </para></listitem> + <listitem><para> + The default value of + <link linkend='var-COPYLEFT_LICENSE_INCLUDE'><filename>COPYLEFT_LICENSE_INCLUDE</filename></link> + 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. + </note> + </para></listitem> + <listitem><para> + 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: + <literallayout class='monospaced'> + KERNEL_MODULE_PACKAGE_SUFFIX to "" + </literallayout> + </para></listitem> + <listitem><para> + Removal of <filename>libtool</filename> + <filename>*.la</filename> files is now enabled by default. + The <filename>*.la</filename> files are not actually + needed on Linux and relocating them is an unnecessary + burden.</para> + + <para>If you need to preserve these + <filename>.la</filename> files (e.g. in a custom + distribution), you must change + <link linkend='var-INHERIT_DISTRO'><filename>INHERIT_DISTRO</filename></link> + such that "remove-libtool" is not included in the value. + </para></listitem> + <listitem><para> + 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 + <filename>uninative</filename> shared state (sstate) + package is built. + See the + <link linkend='ref-classes-uninative'><filename>uninative</filename></link> + class for additional information. + </para></listitem> + <listitem><para> + All native and nativesdk recipes now use a separate + <filename>DISTRO_FEATURES</filename> value instead of + sharing the value used by recipes for the target, in order + to avoid unnecessary rebuilds.</para> + + <para>The <filename>DISTRO_FEATURES</filename> for + <filename>native</filename> recipes is + <link linkend='var-DISTRO_FEATURES_NATIVE'><filename>DISTRO_FEATURES_NATIVE</filename></link> + added to an intersection of + <filename>DISTRO_FEATURES</filename> and + <link linkend='var-DISTRO_FEATURES_FILTER_NATIVE'><filename>DISTRO_FEATURES_FILTER_NATIVE</filename></link>. + </para> + + <para>For nativesdk recipes, the + corresponding variables are + <link linkend='var-DISTRO_FEATURES_NATIVESDK'><filename>DISTRO_FEATURES_NATIVESDK</filename></link> + and + <link linkend='var-DISTRO_FEATURES_FILTER_NATIVESDK'><filename>DISTRO_FEATURES_FILTER_NATIVESDK</filename></link>. + </para></listitem> + <listitem><para> + The <filename>FILESDIR</filename> + variable, which was previously deprecated and rarely used, + has now been removed. + You should change any recipes that set + <filename>FILESDIR</filename> to set + <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link> + instead. + </para></listitem> + <listitem><para> + The <filename>MULTIMACH_HOST_SYS</filename> + variable has been removed as it is no longer needed + with recipe-specific sysroots. + </para></listitem> + </itemizedlist> + </para> + </section> +</section> + +<section id='moving-to-the-yocto-project-2.4-release'> + <title>Moving to the Yocto Project 2.4 Release</title> + + <para> + This section provides migration information for moving to the + Yocto Project 2.4 Release from the prior release. + </para> + + <section id='migration-2.4-memory-resident-mode'> + <title>Memory Resident Mode</title> + + <para> + A persistent mode is now available in BitBake's default operation, + replacing its previous "memory resident mode" (i.e. + <filename>oe-init-build-env-memres</filename>). + Now you only need to set + <link linkend='var-BB_SERVER_TIMEOUT'><filename>BB_SERVER_TIMEOUT</filename></link> + to a timeout (in seconds) and BitBake's server stays resident for + that amount of time between invocations. + The <filename>oe-init-build-env-memres</filename> script has been + removed since a separate environment setup script is no longer + needed. + </para> + </section> + + <section id='migration-2.4-packaging-changes'> + <title>Packaging Changes</title> + + <para> + This section provides information about packaging changes that have + ocurred: + <itemizedlist> + <listitem><para> + <emphasis><filename>python3</filename> Changes:</emphasis> + <itemizedlist> + <listitem><para> + 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 + <filename>python-core</filename> plus one or more of + the individual packages that are still produced. + </para></listitem> + <listitem><para> + <emphasis><filename>python3</filename>:</emphasis> + The <filename>bz2.py</filename>, + <filename>lzma.py</filename>, and + <filename>_compression.py</filename> scripts have + been moved from the + <filename>python3-misc</filename> package to + the <filename>python3-compression</filename> package. + </para></listitem> + </itemizedlist> + </para></listitem> + <listitem><para> + <emphasis><filename>binutils</filename>:</emphasis> + The <filename>libbfd</filename> library is now packaged in + a separate "libbfd" package. + This packaging saves space when certain tools + (e.g. <filename>perf</filename>) are installed. + In such cases, the tools only need + <filename>libbfd</filename> rather than all the packages in + <filename>binutils</filename>. + </para></listitem> + <listitem><para> + <emphasis><filename>util-linux</filename> Changes:</emphasis> + <itemizedlist> + <listitem><para> + The <filename>su</filename> program is now packaged + in a separate "util-linux-su" package, which is only + built when "pam" is listed in the + <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link> + variable. + <filename>util-linux</filename> should not be + installed unless it is needed because + <filename>su</filename> is normally provided through + the shadow file format. + The main <filename>util-linux</filename> package has + runtime dependencies (i.e. + <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>) + on the <filename>util-linux-su</filename> package + when "pam" is in + <filename>DISTRO_FEATURES</filename>. + </para></listitem> + <listitem><para> + The <filename>switch_root</filename> program is now + packaged in a separate "util-linux-switch-root" + package for small initramfs images that do not need + the whole <filename>util-linux</filename> package or + the busybox binary, which are both much larger than + <filename>switch_root</filename>. + The main <filename>util-linux</filename> package has + a recommended runtime dependency (i.e. + <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>) + on the <filename>util-linux-switch-root</filename> package. + </para></listitem> + <listitem><para> + The <filename>ionice</filename> program is now + packaged in a separate "util-linux-ionice" package. + The main <filename>util-linux</filename> package has + a recommended runtime dependency (i.e. + <filename>RRECOMMENDS</filename>) + on the <filename>util-linux-ionice</filename> package. + </para></listitem> + </itemizedlist> + </para></listitem> + <listitem><para> + <emphasis><filename>initscripts</filename>:</emphasis> + The <filename>sushell</filename> program is now packaged in + a separate "initscripts-sushell" package. + This packaging change allows systems to pull + <filename>sushell</filename> in when + <filename>selinux</filename> is enabled. + The change also eliminates needing to pull in the entire + <filename>initscripts</filename> package. + The main <filename>initscripts</filename> package has a + runtime dependency (i.e. <filename>RDEPENDS</filename>) + on the <filename>sushell</filename> package when + "selinux" is in <filename>DISTRO_FEATURES</filename>. + </para></listitem> + <listitem><para> + <emphasis><filename>glib-2.0</filename>:</emphasis> + The <filename>glib-2.0</filename> package now has a + recommended runtime dependency (i.e. + <filename>RRECOMMENDS</filename>) on the + <filename>shared-mime-info</filename> package, since large + portions of GIO are not useful without the MIME database. + You can remove the dependency by using the + <link linkend='var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></link> + variable if <filename>shared-mime-info</filename> is too + large and is not required. + </para></listitem> + <listitem><para> + <emphasis>Go Standard Runtime:</emphasis> + The Go standard runtime has been split out from the main + <filename>go</filename> recipe into a separate + <filename>go-runtime</filename> recipe. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-2.4-removed-recipes'> + <title>Removed Recipes</title> + + <para> + The following recipes have been removed: + <itemizedlist> + <listitem><para> + <emphasis><filename>acpitests</filename>:</emphasis> + This recipe is not maintained. + </para></listitem> + <listitem><para> + <emphasis><filename>autogen-native</filename>:</emphasis> + No longer required by Grub, oe-core, or meta-oe. + </para></listitem> + <listitem><para> + <emphasis><filename>bdwgc</filename>:</emphasis> + Nothing in OpenEmbedded-Core requires this recipe. + It has moved to meta-oe. + </para></listitem> + <listitem><para> + <emphasis><filename>byacc</filename>:</emphasis> + This recipe was only needed by rpm 5.x and has moved to + meta-oe. + </para></listitem> + <listitem><para> + <emphasis><filename>gcc (5.4)</filename>:</emphasis> + The 5.4 series dropped the recipe in favor of 6.3 / 7.2. + </para></listitem> + <listitem><para> + <emphasis><filename>gnome-common</filename>:</emphasis> + Deprecated upstream and no longer needed. + </para></listitem> + <listitem><para> + <emphasis><filename>go-bootstrap-native</filename>:</emphasis> + Go 1.9 does its own bootstrapping so this recipe has been + removed. + </para></listitem> + <listitem><para> + <emphasis><filename>guile</filename>:</emphasis> + This recipe was only needed by + <filename>autogen-native</filename> and + <filename>remake</filename>. + The recipe is no longer needed by either of these programs. + </para></listitem> + <listitem><para> + <emphasis><filename>libclass-isa-perl</filename>:</emphasis> + This recipe was previously needed for LSB 4, no longer + needed. + </para></listitem> + <listitem><para> + <emphasis><filename>libdumpvalue-perl</filename>:</emphasis> + This recipe was previously needed for LSB 4, no longer + needed. + </para></listitem> + <listitem><para> + <emphasis><filename>libenv-perl</filename>:</emphasis> + This recipe was previously needed for LSB 4, no longer + needed. + </para></listitem> + <listitem><para> + <emphasis><filename>libfile-checktree-perl</filename>:</emphasis> + This recipe was previously needed for LSB 4, no longer + needed. + </para></listitem> + <listitem><para> + <emphasis><filename>libi18n-collate-perl</filename>:</emphasis> + This recipe was previously needed for LSB 4, no longer + needed. + </para></listitem> + <listitem><para> + <emphasis><filename>libiconv</filename>:</emphasis> + This recipe was only needed for <filename>uclibc</filename>, + which was removed in the previous release. + <filename>glibc</filename> and <filename>musl</filename> + have their own implementations. + <filename>meta-mingw</filename> still needs + <filename>libiconv</filename>, so it has + been moved to <filename>meta-mingw</filename>. + </para></listitem> + <listitem><para> + <emphasis><filename>libpng12</filename>:</emphasis> + This recipe was previously needed for LSB. The current + <filename>libpng</filename> is 1.6.x. + </para></listitem> + <listitem><para> + <emphasis><filename>libpod-plainer-perl</filename>:</emphasis> + This recipe was previously needed for LSB 4, no longer + needed. + </para></listitem> + <listitem><para> + <emphasis><filename>linux-yocto (4.1)</filename>:</emphasis> + This recipe was removed in favor of 4.4, 4.9, 4.10 and 4.12. + </para></listitem> + <listitem><para> + <emphasis><filename>mailx</filename>:</emphasis> + This recipe was previously only needed for LSB + compatibility, and upstream is defunct. + </para></listitem> + <listitem><para> + <emphasis><filename>mesa (git version only)</filename>:</emphasis> + The git version recipe was stale with respect to the release + version. + </para></listitem> + <listitem><para> + <emphasis><filename>ofono (git version only)</filename>:</emphasis> + The git version recipe was stale with respect to the release + version. + </para></listitem> + <listitem><para> + <emphasis><filename>portmap</filename>:</emphasis> + This recipe is obsolete and is superseded by + <filename>rpcbind</filename>. + </para></listitem> + <listitem><para> + <emphasis><filename>python3-pygpgme</filename>:</emphasis> + This recipe is old and unmaintained. It was previously + required by <filename>dnf</filename>, which has switched + to official <filename>gpgme</filename> Python bindings. + </para></listitem> + <listitem><para> + <emphasis><filename>python-async</filename>:</emphasis> + This recipe has been removed in favor of the Python 3 + version. + </para></listitem> + <listitem><para> + <emphasis><filename>python-gitdb</filename>:</emphasis> + This recipe has been removed in favor of the Python 3 + version. + </para></listitem> + <listitem><para> + <emphasis><filename>python-git</filename>:</emphasis> + This recipe was removed in favor of the Python 3 + version. + </para></listitem> + <listitem><para> + <emphasis><filename>python-mako</filename>:</emphasis> + This recipe was removed in favor of the Python 3 + version. + </para></listitem> + <listitem><para> + <emphasis><filename>python-pexpect</filename>:</emphasis> + This recipe was removed in favor of the Python 3 version. + </para></listitem> + <listitem><para> + <emphasis><filename>python-ptyprocess</filename>:</emphasis> + This recipe was removed in favor of Python the 3 version. + </para></listitem> + <listitem><para> + <emphasis><filename>python-pycurl</filename>:</emphasis> + Nothing is using this recipe in OpenEmbedded-Core + (i.e. <filename>meta-oe</filename>). + </para></listitem> + <listitem><para> + <emphasis><filename>python-six</filename>:</emphasis> + This recipe was removed in favor of the Python 3 version. + </para></listitem> + <listitem><para> + <emphasis><filename>python-smmap</filename>:</emphasis> + This recipe was removed in favor of the Python 3 version. + </para></listitem> + <listitem><para> + <emphasis><filename>remake</filename>:</emphasis> + Using <filename>remake</filename> as the provider of + <filename>virtual/make</filename> is broken. + Consequently, this recipe is not needed in OpenEmbedded-Core. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-2.4-kernel-device-tree-move'> + <title>Kernel Device Tree Move</title> + + <para> + Kernel Device Tree support is now easier to enable in a kernel + recipe. + The Device Tree code has moved to a + <link linkend='ref-classes-kernel-devicetree'><filename>kernel-devicetree</filename></link> + class. + Functionality is automatically enabled for any recipe that inherits + the + <link linkend='ref-classes-kernel'><filename>kernel</filename></link> + class and sets the + <link linkend='var-KERNEL_DEVICETREE'><filename>KERNEL_DEVICETREE</filename></link> + variable. + The previous mechanism for doing this, + <filename>meta/recipes-kernel/linux/linux-dtb.inc</filename>, + is still available to avoid breakage, but triggers a + deprecation warning. + Future releases of the Yocto Project will remove + <filename>meta/recipes-kernel/linux/linux-dtb.inc</filename>. + It is advisable to remove any <filename>require</filename> + statements that request + <filename>meta/recipes-kernel/linux/linux-dtb.inc</filename> + from any custom kernel recipes you might have. + This will avoid breakage in post 2.4 releases. + </para> + </section> + + <section id='migration-2.4-package-qa-changes'> + <title>Package QA Changes</title> + + <para> + The following package QA changes took place: + <itemizedlist> + <listitem><para> + The "unsafe-references-in-scripts" QA check has been + removed. + </para></listitem> + <listitem><para> + If you refer to <filename>${COREBASE}/LICENSE</filename> + within + <link linkend='var-LIC_FILES_CHKSUM'><filename>LIC_FILES_CHKSUM</filename></link> + you receive a warning because this file is a description of + the license for OE-Core. + Use <filename>${COMMON_LICENSE_DIR}/MIT</filename> + if your recipe is MIT-licensed and you cannot use the + preferred method of referring to a file within the source + tree. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-2.4-readme-changes'> + <title><filename>README</filename> File Changes</title> + + <para> + The following are changes to <filename>README</filename> files: + <itemizedlist> + <listitem><para> + The main Poky <filename>README</filename> file has been + moved to the <filename>meta-poky</filename> layer and + has been renamed <filename>README.poky</filename>. + A symlink has been created so that references to the old + location work. + </para></listitem> + <listitem><para> + The <filename>README.hardware</filename> file has been moved + to <filename>meta-yocto-bsp</filename>. + A symlink has been created so that references to the old + location work. + </para></listitem> + <listitem><para> + A <filename>README.qemu</filename> file has been created + with coverage of the <filename>qemu*</filename> machines. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-2.4-miscellaneous-changes'> + <title>Miscellaneous Changes</title> + + <para> + The following are additional changes: + <itemizedlist> + <listitem><para> + The <filename>ROOTFS_PKGMANAGE_BOOTSTRAP</filename> + variable and any references to it have been removed. + You should remove this variable from any custom recipes. + </para></listitem> + <listitem><para> + The <filename>meta-yocto</filename> directory has been + removed. + <note> + In the Yocto Project 2.1 release + <filename>meta-yocto</filename> was renamed to + <filename>meta-poky</filename> and the + <filename>meta-yocto</filename> subdirectory remained + to avoid breaking existing configurations. + </note> + </para></listitem> + <listitem><para> + The <filename>maintainers.inc</filename> file, which tracks + maintainers by listing a primary person responsible for each + recipe in OE-Core, has been moved from + <filename>meta-poky</filename> to OE-Core (i.e. from + <filename>meta-poky/conf/distro/include</filename> to + <filename>meta/conf/distro/include</filename>). + </para></listitem> + <listitem><para> + The + <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link> + 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 + <link linkend='var-BUILDHISTORY_COMMIT'><filename>BUILDHISTORY_COMMIT</filename></link> + = "1", which is typical. + Previously, the <filename>buildhistory</filename> 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 <filename>git show</filename> + or <filename>git diff</filename> commands. + </para></listitem> + <listitem><para> + The <filename>x86-base.inc</filename> file, which is + included by all x86-based machine configurations, now sets + <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link> + using <filename>?=</filename> to "live" rather than + appending with <filename>+=</filename>. + This change makes the default easier to override. + </para></listitem> + <listitem><para> + BitBake fires multiple "BuildStarted" events when + multiconfig is enabled (one per configuration). + For more information, see the + "<ulink url='&YOCTO_DOCS_BB_URL;#events'>Events</ulink>" + section in the BitBake User Manual. + </para></listitem> + <listitem><para> + By default, the <filename>security_flags.inc</filename> file + sets a + <link linkend='var-GCCPIE'><filename>GCCPIE</filename></link> + variable with an option to enable Position Independent + Executables (PIE) within <filename>gcc</filename>. + Enabling PIE in the GNU C Compiler (GCC), makes Return + Oriented Programming (ROP) attacks much more difficult to + execute. + </para></listitem> + <listitem><para> + OE-Core now provides a + <filename>bitbake-layers</filename> plugin that implements + a "create-layer" subcommand. + The implementation of this subcommand has resulted in the + <filename>yocto-layer</filename> script being deprecated and + will likely be removed in the next Yocto Project release. + </para></listitem> + <listitem><para> + The <filename>vmdk</filename>, <filename>vdi</filename>, + and <filename>qcow2</filename> image file types are now + used in conjunction with the "wic" image type through + <filename>CONVERSION_CMD</filename>. + Consequently, the equivalent image types are now + <filename>wic.vmdk</filename>, <filename>wic.vdi</filename>, + and <filename>wic.qcow2</filename>, respectively. + </para></listitem> + <listitem><para> + <filename>do_image_<type>[depends]</filename> has + replaced <filename>IMAGE_DEPENDS_<type></filename>. + If you have your own classes that implement custom image + types, then you need to update them. + </para></listitem> + <listitem><para> + OpenSSL 1.1 has been introduced. + However, the default is still 1.0.x through the + <link linkend='var-PREFERRED_VERSION'><filename>PREFERRED_VERSION</filename></link> + variable. + This preference is set is due to the remaining compatibility + issues with other software. + The + <link linkend='var-PROVIDES'><filename>PROVIDES</filename></link> + variable in the openssl 1.0 recipe now includes "openssl10" + as a marker that can be used in + <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link> + within recipes that build software that still depend on + OpenSSL 1.0. + </para></listitem> + <listitem><para> + 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. + </para></listitem> + </itemizedlist> + </para> + </section> +</section> + +<section id='moving-to-the-yocto-project-2.5-release'> + <title>Moving to the Yocto Project 2.5 Release</title> + + <para> + This section provides migration information for moving to the + Yocto Project 2.5 Release from the prior release. + </para> + + <section id='migration-2.5-packaging-changes'> + <title>Packaging Changes</title> + + <para> + This section provides information about packaging changes that have + occurred: + <itemizedlist> + <listitem><para> + <emphasis><filename>bind-libs</filename>:</emphasis> + The libraries packaged by the bind recipe are in a + separate <filename>bind-libs</filename> package. + </para></listitem> + <listitem><para> + <emphasis><filename>libfm-gtk</filename>:</emphasis> + The <filename>libfm</filename> GTK+ bindings are split into + a separate <filename>libfm-gtk</filename> package. + </para></listitem> + <listitem><para> + <emphasis><filename>flex-libfl</filename>:</emphasis> + The flex recipe splits out libfl into a separate + <filename>flex-libfl</filename> package to avoid too many + dependencies being pulled in where only the library is + needed. + </para></listitem> + <listitem><para> + <emphasis><filename>grub-efi</filename>:</emphasis> + The <filename>grub-efi</filename> configuration is split + into a separate <filename>grub-bootconf</filename> + recipe. + However, the dependency relationship from + <filename>grub-efi</filename> 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 + <filename>grub-efi</filename> recipe. + </para></listitem> + <listitem><para> + <emphasis>armv7a Legacy Package Feed Support:</emphasis> + Legacy support is removed for transitioning from + <filename>armv7a</filename> to + <filename>armv7a-vfp-neon</filename> in package feeds, + which was previously enabled by setting + <filename>PKGARCHCOMPAT_ARMV7A</filename>. + This transition occurred in 2011 and active package feeds + should by now be updated to the new naming. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-2.5-removed-recipes'> + <title>Removed Recipes</title> + + <para> + The following recipes have been removed: + <itemizedlist> + <listitem><para> + <emphasis><filename>gcc</filename>:</emphasis> + The version 6.4 recipes are replaced by 7.x. + </para></listitem> + <listitem><para> + <emphasis><filename>gst-player</filename>:</emphasis> + Renamed to <filename>gst-examples</filename> as per + upstream. + </para></listitem> + <listitem><para> + <emphasis><filename>hostap-utils</filename>:</emphasis> + This software package is obsolete. + </para></listitem> + <listitem><para> + <emphasis><filename>latencytop</filename>:</emphasis> + This recipe is no longer maintained upstream. + The last release was in 2009. + </para></listitem> + <listitem><para> + <emphasis><filename>libpfm4</filename>:</emphasis> + The only file that requires this recipe is + <filename>oprofile</filename>, which has been removed. + </para></listitem> + <listitem><para> + <emphasis><filename>linux-yocto</filename>:</emphasis> + The version 4.4, 4.9, and 4.10 recipes have been removed. + Versions 4.12, 4.14, and 4.15 remain. + </para></listitem> + <listitem><para> + <emphasis><filename>man</filename>:</emphasis> + This recipe has been replaced by modern + <filename>man-db</filename> + </para></listitem> + <listitem><para> + <emphasis><filename>mkelfimage</filename>:</emphasis> + This tool has been removed in the upstream coreboot project, + and is no longer needed with the removal of the ELF image + type. + </para></listitem> + <listitem><para> + <emphasis><filename>nativesdk-postinst-intercept</filename>:</emphasis> + This recipe is not maintained. + </para></listitem> + <listitem><para> + <emphasis><filename>neon</filename>:</emphasis> + This software package is no longer maintained upstream and + is no longer needed by anything in OpenEmbedded-Core. + </para></listitem> + <listitem><para> + <emphasis><filename>oprofile</filename>:</emphasis> + The functionality of this recipe is replaced by + <filename>perf</filename> and keeping compatibility on + an ongoing basis with <filename>musl</filename> is + difficult. + </para></listitem> + <listitem><para> + <emphasis><filename>pax</filename>:</emphasis> + This software package is obsolete. + </para></listitem> + <listitem><para> + <emphasis><filename>stat</filename>:</emphasis> + This software package is not maintained upstream. + <filename>coreutils</filename> provides a modern stat binary. + </para></listitem> + <listitem><para> + <emphasis><filename>zisofs-tools-native</filename>:</emphasis> + This recipe is no longer needed because the compressed + ISO image feature has been removed. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-2.5-scripts-and-tools-changes'> + <title>Scripts and Tools Changes</title> + + <para> + The following are changes to scripts and tools: + <itemizedlist> + <listitem><para> + <emphasis><filename>yocto-bsp</filename>, + <filename>yocto-kernel</filename>, and + <filename>yocto-layer</filename></emphasis>: + The <filename>yocto-bsp</filename>, + <filename>yocto-kernel</filename>, and + <filename>yocto-layer</filename> 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 <filename>bitbake-layers create-layer</filename> command + is a direct replacement for <filename>yocto-layer</filename>. + See the documentation to create a BSP or kernel recipe in + the + "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-kernel-recipe-example'>BSP Kernel Recipe Example</ulink>" + section. + </para></listitem> + <listitem><para> + <emphasis><filename>devtool finish</filename>:</emphasis> + <filename>devtool finish</filename> 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. + </para></listitem> + <listitem><para> + <emphasis><filename>scripts/oe-setup-rpmrepo</filename> script:</emphasis> + The functionality of + <filename>scripts/oe-setup-rpmrepo</filename> is replaced by + <filename>bitbake package-index</filename>. + </para></listitem> + <listitem><para> + <emphasis><filename>scripts/test-dependencies.sh</filename> script:</emphasis> + The script is largely made obsolete by the + recipe-specific sysroots functionality introduced in the + previous release. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-2.5-bitbake-changes'> + <title>BitBake Changes</title> + + <para> + The following are BitBake changes: + <itemizedlist> + <listitem><para> + The <filename>--runall</filename> option has changed. + There are two different behaviors people might want: + <itemizedlist> + <listitem><para> + <emphasis>Behavior A:</emphasis> + 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. + </para></listitem> + <listitem><para> + <emphasis>Behavior B:</emphasis> + 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. + </para></listitem> + </itemizedlist> + The <filename>--runall</filename> option now performs + "Behavior B". + Previously <filename>--runall</filename> behaved like + "Behavior A". + A <filename>--runonly</filename> option has been added to + retain the ability to perform "Behavior A". + </para></listitem> + <listitem><para> + Several explicit "run this task for all recipes in the + dependency tree" tasks have been removed (e.g. + <filename>fetchall</filename>, + <filename>checkuriall</filename>, and the + <filename>*all</filename> tasks provided by the + <filename>distrodata</filename> and + <filename>archiver</filename> classes). + There is a BitBake option to complete this for any arbitrary + task. For example: + <literallayout class='monospaced'> + bitbake <target> -c fetchall + </literallayout> + should now be replaced with: + <literallayout class='monospaced'> + bitbake <target> --runall=fetch + </literallayout> + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-2.5-python-and-python3-changes'> + <title>Python and Python 3 Changes</title> + + <para> + The following are auto-packaging changes to Python and Python 3: + </para> + <para> + The script-managed <filename>python-*-manifest.inc</filename> 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. + </para> + <para> + One particular change to note is that the Python recipes no longer + have build-time provides for their packages. + This assumes <filename>python-foo</filename> is one of the packages + provided by the Python recipe. + You can no longer run <filename>bitbake python-foo</filename> or + have a <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink> on + <filename>python-foo</filename>, but doing either of the following + causes the package to work as expected: + <literallayout class='monospaced'> + IMAGE_INSTALL_append = " python-foo" + </literallayout> + or + <literallayout class='monospaced'> + RDEPENDS_${PN} = "python-foo" + </literallayout> + 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 + <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/poky/commit/?id=8d94b9db221d1def42f091b991903faa2d1651ce'>this commit</ulink>. + </para> + </section> + + <section id='migration-2.5-miscellaneous-changes'> + <title>Miscellaneous Changes</title> + + <para> + The following are additional changes: + <itemizedlist> + <listitem><para> + The <filename>kernel</filename> class supports building + packages for multiple kernels. + If your kernel recipe or <filename>.bbappend</filename> file + mentions packaging at all, you should replace references to + the kernel in package names with + <filename>${KERNEL_PACKAGE_NAME}</filename>. + For example, if you disable automatic installation of the + kernel image using + <filename>RDEPENDS_kernel-base = ""</filename> you can avoid + warnings using + <filename>RDEPENDS_${KERNEL_PACKAGE_NAME}-base = ""</filename> + instead. + </para></listitem> + <listitem><para> + The <filename>buildhistory</filename> class commits changes + to the repository by default so you no longer need to set + <filename>BUILDHISTORY_COMMIT = "1"</filename>. + If you want to disable commits you need to set + <filename>BUILDHISTORY_COMMIT = "0"</filename> in your + configuration. + </para></listitem> + <listitem><para> + The <filename>beaglebone</filename> reference machine has + been renamed to <filename>beaglebone-yocto</filename>. + The <filename>beaglebone-yocto</filename> BSP is a reference + implementation using only mainline components available in + OpenEmbedded-Core and <filename>meta-yocto-bsp</filename>, + whereas Texas Instruments maintains a full-featured BSP in + the <filename>meta-ti</filename> layer. + This rename avoids the previous name clash that existed + between the two BSPs. + </para></listitem> + <listitem><para> + The <filename>update-alternatives</filename> class no longer + works with SysV <filename>init</filename> scripts because + this usage has been problematic. + Also, the <filename>sysklogd</filename> recipe no longer + uses <filename>update-alternatives</filename> because it is + incompatible with other implementations. + </para></listitem> + <listitem><para> + By default, the <filename>cmake</filename> class uses + <filename>ninja</filename> instead of + <filename>make</filename> for building. + This improves build performance. + If a recipe is broken with <filename>ninja</filename>, then + the recipe can set + <filename>OECMAKE_GENERATOR = "Unix Makefiles"</filename> + to change back to <filename>make</filename>. + </para></listitem> + <listitem><para> + The previously deprecated <filename>base_*</filename> + functions have been removed in favor of their replacements + in <filename>meta/lib/oe</filename> and + <filename>bitbake/lib/bb</filename>. + 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: + + <literallayout class='monospaced'> + <emphasis>Removed</emphasis> <emphasis>Replacement</emphasis> + ============================ ============================ + 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). + </literallayout> + </para></listitem> + <listitem><para> + Using <filename>exit 1</filename> 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 <filename>rootfs</filename> + creation time, use + <filename>pkg_postinst_ontarget()</filename> + or call + <filename>postinst-intercepts defer_to_first_boot</filename> + from <filename>pkg_postinst()</filename>. + Any failure of a <filename>pkg_postinst()</filename> + script (including <filename>exit 1</filename>) + will trigger a warning during + <filename>do_rootfs</filename>. + </para></listitem> + <listitem><para> + The <filename>elf</filename> image type has been removed. + This image type was removed because the + <filename>mkelfimage</filename> tool + that was required to create it is no longer provided by + coreboot upstream and required updating every time + <filename>binutils</filename> updated. + </para></listitem> + <listitem><para> + Support for .iso image compression (previously enabled + through <filename>COMPRESSISO = "1"</filename>) has been + removed. + The userspace tools (<filename>zisofs-tools</filename>) are + unmaintained and <filename>squashfs</filename> provides + better performance and compression. + In order to build a live image with squashfs+lz4 compression + enabled you should now set + <filename>LIVE_ROOTFS_TYPE = "squashfs-lz4"</filename> + and ensure that <filename>live</filename> + is in <filename>IMAGE_FSTYPES</filename>. + </para></listitem> + <listitem><para> + Recipes with an unconditional dependency on + <filename>libpam</filename> are only buildable with + <filename>pam</filename> in + <filename>DISTRO_FEATURES</filename>. + If the dependency is truly optional then it is recommended + that the dependency be conditional upon + <filename>pam</filename> being in + <filename>DISTRO_FEATURES</filename>. + </para></listitem> + <listitem><para> + For EFI-based machines, the bootloader + (<filename>grub-efi</filename> 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. + </para></listitem> + <listitem><para> + 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 + <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/poky/commit/?id=cc97bc08125b63821ce3f616771830f77c456f57'>this commit</ulink>. + </para></listitem> + <listitem><para> + Layers are expected to set + <filename>LAYERSERIES_COMPAT_layername</filename> + 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 + <filename>LAYERSERIES_COMPAT_layername</filename>, 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. + </para></listitem> + <listitem><para> + The <filename>TZ</filename> environment variable is set to + "UTC" within the build environment in order to fix + reproducibility problems in some recipes. + </para></listitem> + </itemizedlist> + </para> + </section> +</section> +</chapter> +<!-- +vim: expandtab tw=80 ts=4 +--> |
