sphinx: ref-manual/migration: Split each release into its own file

This avoids the duplicate heading warnings at the slight expense
of more directory clutter.

(From yocto-docs rev: ef896d71836aa3bd6c926b36976a9c45d5f2ca15)

Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

1 files changed, 237 insertions, 0 deletions

diff --git a/documentation/ref-manual/migration-1.4.rst b/documentation/ref-manual/migration-1.4.rst
new file mode 100644
index 0000000000..a658bdff68
--- /dev/null
+++ b/documentation/ref-manual/migration-1.4.rst
@@ -0,0 +1,237 @@
+Moving to the Yocto Project 1.4 Release
+=======================================
+
+This section provides migration information for moving to the Yocto
+Project 1.4 Release from the prior release.
+
+.. _migration-1.4-bitbake:
+
+BitBake
+-------
+
+Differences include the following:
+
+-  *Comment Continuation:* If a comment ends with a line continuation
+   (\) character, then the next line must also be a comment. Any
+   instance where this is not the case, now triggers a warning. You must
+   either remove the continuation character, or be sure the next line is
+   a comment.
+
+-  *Package Name Overrides:* The runtime package specific variables
+   :term:`RDEPENDS`,
+   :term:`RRECOMMENDS`,
+   :term:`RSUGGESTS`,
+   :term:`RPROVIDES`,
+   :term:`RCONFLICTS`,
+   :term:`RREPLACES`, :term:`FILES`,
+   :term:`ALLOW_EMPTY`, and the pre, post, install,
+   and uninstall script functions ``pkg_preinst``, ``pkg_postinst``,
+   ``pkg_prerm``, and ``pkg_postrm`` should always have a package name
+   override. For example, use ``RDEPENDS_${PN}`` for the main package
+   instead of ``RDEPENDS``. BitBake uses more strict checks when it
+   parses recipes.
+
+.. _migration-1.4-build-behavior:
+
+Build Behavior
+--------------
+
+Differences include the following:
+
+-  *Shared State Code:* The shared state code has been optimized to
+   avoid running unnecessary tasks. For example, the following no longer
+   populates the target sysroot since that is not necessary:
+   ::
+
+      $ bitbake -c rootfs some-image
+
+   Instead, the system just needs to extract the
+   output package contents, re-create the packages, and construct the
+   root filesystem. This change is unlikely to cause any problems unless
+   you have missing declared dependencies.
+
+-  *Scanning Directory Names:* When scanning for files in
+   :term:`SRC_URI`, the build system now uses
+   :term:`FILESOVERRIDES` instead of
+   :term:`OVERRIDES` for the directory names. In
+   general, the values previously in ``OVERRIDES`` are now in
+   ``FILESOVERRIDES`` as well. However, if you relied upon an additional
+   value you previously added to ``OVERRIDES``, you might now need to
+   add it to ``FILESOVERRIDES`` unless you are already adding it through
+   the :term:`MACHINEOVERRIDES` or
+   :term:`DISTROOVERRIDES` variables, as
+   appropriate. For more related changes, see the
+   "`Variables <#migration-1.4-variables>`__" section.
+
+.. _migration-1.4-proxies-and-fetching-source:
+
+Proxies and Fetching Source
+---------------------------
+
+A new ``oe-git-proxy`` script has been added to replace previous methods
+of handling proxies and fetching source from Git. See the
+``meta-yocto/conf/site.conf.sample`` file for information on how to use
+this script.
+
+.. _migration-1.4-custom-interfaces-file-netbase-change:
+
+Custom Interfaces File (netbase change)
+---------------------------------------
+
+If you have created your own custom ``etc/network/interfaces`` file by
+creating an append file for the ``netbase`` recipe, you now need to
+create an append file for the ``init-ifupdown`` recipe instead, which
+you can find in the :term:`Source Directory` at
+``meta/recipes-core/init-ifupdown``. For information on how to use
+append files, see the
+":ref:`dev-manual/dev-manual-common-tasks:using .bbappend files in your layer`"
+section in the Yocto Project Development Tasks Manual.
+
+.. _migration-1.4-remote-debugging:
+
+Remote Debugging
+----------------
+
+Support for remote debugging with the Eclipse IDE is now separated into
+an image feature (``eclipse-debug``) that corresponds to the
+``packagegroup-core-eclipse-debug`` package group. Previously, the
+debugging feature was included through the ``tools-debug`` image
+feature, which corresponds to the ``packagegroup-core-tools-debug``
+package group.
+
+.. _migration-1.4-variables:
+
+Variables
+---------
+
+The following variables have changed:
+
+-  ``SANITY_TESTED_DISTROS``: This variable now uses a distribution
+   ID, which is composed of the host distributor ID followed by the
+   release. Previously,
+   :term:`SANITY_TESTED_DISTROS` was
+   composed of the description field. For example, "Ubuntu 12.10"
+   becomes "Ubuntu-12.10". You do not need to worry about this change if
+   you are not specifically setting this variable, or if you are
+   specifically setting it to "".
+
+-  ``SRC_URI``: The ``${``\ :term:`PN`\ ``}``,
+   ``${``\ :term:`PF`\ ``}``,
+   ``${``\ :term:`P`\ ``}``, and ``FILE_DIRNAME`` directories
+   have been dropped from the default value of the
+   :term:`FILESPATH` variable, which is used as the
+   search path for finding files referred to in
+   :term:`SRC_URI`. If you have a recipe that relied upon
+   these directories, which would be unusual, then you will need to add
+   the appropriate paths within the recipe or, alternatively, rearrange
+   the files. The most common locations are still covered by ``${BP}``,
+   ``${BPN}``, and "files", which all remain in the default value of
+   :term:`FILESPATH`.
+
+.. _migration-target-package-management-with-rpm:
+
+Target Package Management with RPM
+----------------------------------
+
+If runtime package management is enabled and the RPM backend is
+selected, Smart is now installed for package download, dependency
+resolution, and upgrades instead of Zypper. For more information on how
+to use Smart, run the following command on the target:
+::
+
+   smart --help
+
+.. _migration-1.4-recipes-moved:
+
+Recipes Moved
+-------------
+
+The following recipes were moved from their previous locations because
+they are no longer used by anything in the OpenEmbedded-Core:
+
+-  ``clutter-box2d``: Now resides in the ``meta-oe`` layer.
+
+-  ``evolution-data-server``: Now resides in the ``meta-gnome`` layer.
+
+-  ``gthumb``: Now resides in the ``meta-gnome`` layer.
+
+-  ``gtkhtml2``: Now resides in the ``meta-oe`` layer.
+
+-  ``gupnp``: Now resides in the ``meta-multimedia`` layer.
+
+-  ``gypsy``: Now resides in the ``meta-oe`` layer.
+
+-  ``libcanberra``: Now resides in the ``meta-gnome`` layer.
+
+-  ``libgdata``: Now resides in the ``meta-gnome`` layer.
+
+-  ``libmusicbrainz``: Now resides in the ``meta-multimedia`` layer.
+
+-  ``metacity``: Now resides in the ``meta-gnome`` layer.
+
+-  ``polkit``: Now resides in the ``meta-oe`` layer.
+
+-  ``zeroconf``: Now resides in the ``meta-networking`` layer.
+
+.. _migration-1.4-removals-and-renames:
+
+Removals and Renames
+--------------------
+
+The following list shows what has been removed or renamed:
+
+-  ``evieext``: Removed because it has been removed from ``xserver``
+   since 2008.
+
+-  *Gtk+ DirectFB:* Removed support because upstream Gtk+ no longer
+   supports it as of version 2.18.
+
+-  ``libxfontcache / xfontcacheproto``: Removed because they were
+   removed from the Xorg server in 2008.
+
+-  ``libxp / libxprintapputil / libxprintutil / printproto``: Removed
+   because the XPrint server was removed from Xorg in 2008.
+
+-  ``libxtrap / xtrapproto``: Removed because their functionality was
+   broken upstream.
+
+-  *linux-yocto 3.0 kernel:* Removed with linux-yocto 3.8 kernel being
+   added. The linux-yocto 3.2 and linux-yocto 3.4 kernels remain as part
+   of the release.
+
+-  ``lsbsetup``: Removed with functionality now provided by
+   ``lsbtest``.
+
+-  ``matchbox-stroke``: Removed because it was never more than a
+   proof-of-concept.
+
+-  ``matchbox-wm-2 / matchbox-theme-sato-2``: Removed because they are
+   not maintained. However, ``matchbox-wm`` and ``matchbox-theme-sato``
+   are still provided.
+
+-  ``mesa-dri``: Renamed to ``mesa``.
+
+-  ``mesa-xlib``: Removed because it was no longer useful.
+
+-  ``mutter``: Removed because nothing ever uses it and the recipe is
+   very old.
+
+-  ``orinoco-conf``: Removed because it has become obsolete.
+
+-  ``update-modules``: Removed because it is no longer used. The
+   kernel module ``postinstall`` and ``postrm`` scripts can now do the
+   same task without the use of this script.
+
+-  ``web``: Removed because it is not maintained. Superseded by
+   ``web-webkit``.
+
+-  ``xf86bigfontproto``: Removed because upstream it has been disabled
+   by default since 2007. Nothing uses ``xf86bigfontproto``.
+
+-  ``xf86rushproto``: Removed because its dependency in ``xserver``
+   was spurious and it was removed in 2005.
+
+-  ``zypper / libzypp / sat-solver``: Removed and been functionally
+   replaced with Smart (``python-smartpm``) when RPM packaging is used
+   and package management is enabled on the target.
+