generic-poky/documentation/ref-manual/migration.xml

587 lines
30 KiB
XML

<!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='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 rising
from too many files in the same directory.
Also, native sstate-cache packages 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://someserver.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 or Hob 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 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'>Package Groups - packagegroup.bbclass</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
<ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>.
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_DEV_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,
<filename>bitbake -c rootfs some-image</filename> from
shared state no longer populates the target sysroot
since that is not necessary.
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
<ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
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>"
in the Yocto Project Development 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>
</chapter>
<!--
vim: expandtab tw=80 ts=4
-->