ref-manual: move migration guides to separate document

This makes the reference manual much lighter by moving
the migration guides to a separate document.

The migration guides are also reordered from last to first,
and they appear directly in the left bar, making them easier
to find in the documentation.

(From yocto-docs rev: 5121b86ee97eb62a0c69c9ad1fc0e3fabbe3e934)

Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

1 files changed, 221 insertions, 0 deletions

diff --git a/documentation/migration-guides/migration-1.7.rst b/documentation/migration-guides/migration-1.7.rst
new file mode 100644
index 0000000000..999f11a12b
--- /dev/null
+++ b/documentation/migration-guides/migration-1.7.rst
@@ -0,0 +1,221 @@
+Release 1.7 (dizzy)
+===================
+
+This section provides migration information for moving to the Yocto
+Project 1.7 Release (codename "dizzy") from the prior release.
+
+.. _migration-1.7-changes-to-setting-qemu-packageconfig-options:
+
+Changes to Setting QEMU ``PACKAGECONFIG`` Options in ``local.conf``
+-------------------------------------------------------------------
+
+The QEMU recipe now uses a number of
+:term:`PACKAGECONFIG` options to enable various
+optional features. The method used to set defaults for these options
+means that existing ``local.conf`` files will need to be modified to
+append to ``PACKAGECONFIG`` for ``qemu-native`` and ``nativesdk-qemu``
+instead of setting it. In other words, to enable graphical output for
+QEMU, you should now have these lines in ``local.conf``::
+
+   PACKAGECONFIG_append_pn-qemu-native = " sdl"
+   PACKAGECONFIG_append_pn-nativesdk-qemu = " sdl"
+
+.. _migration-1.7-minimum-git-version:
+
+Minimum Git version
+-------------------
+
+The minimum :ref:`overview-manual/development-environment:git`
+version required on the
+build host is now 1.7.8 because the ``--list`` option is now required by
+BitBake's Git fetcher. As always, if your host distribution does not
+provide a version of Git that meets this requirement, you can use the
+``buildtools-tarball`` that does. See the
+":ref:`ref-manual/system-requirements:required git, tar, python and gcc versions`"
+section for more information.
+
+.. _migration-1.7-autotools-class-changes:
+
+Autotools Class Changes
+-----------------------
+
+The following :ref:`autotools <ref-classes-autotools>` class changes
+occurred:
+
+-  *A separate build directory is now used by default:* The
+   ``autotools`` class has been changed to use a directory for building
+   (:term:`B`), which is separate from the source directory
+   (:term:`S`). This is commonly referred to as ``B != S``, or
+   an out-of-tree build.
+
+   If the software being built is already capable of building in a
+   directory separate from the source, you do not need to do anything.
+   However, if the software is not capable of being built in this
+   manner, you will need to either patch the software so that it can
+   build separately, or you will need to change the recipe to inherit
+   the :ref:`autotools-brokensep <ref-classes-autotools>` class
+   instead of the ``autotools`` or ``autotools_stage`` classes.
+
+-  The ``--foreign`` option is no longer passed to ``automake`` when
+   running ``autoconf``: This option tells ``automake`` that a
+   particular software package does not follow the GNU standards and
+   therefore should not be expected to distribute certain files such as
+   ``ChangeLog``, ``AUTHORS``, and so forth. Because the majority of
+   upstream software packages already tell ``automake`` to enable
+   foreign mode themselves, the option is mostly superfluous. However,
+   some recipes will need patches for this change. You can easily make
+   the change by patching ``configure.ac`` so that it passes "foreign"
+   to ``AM_INIT_AUTOMAKE()``. See :oe_git:`this
+   commit </openembedded-core/commit/?id=01943188f85ce6411717fb5bf702d609f55813f2>`
+   for an example showing how to make the patch.
+
+.. _migration-1.7-binary-configuration-scripts-disabled:
+
+Binary Configuration Scripts Disabled
+-------------------------------------
+
+Some of the core recipes that package binary configuration scripts now
+disable the scripts due to the scripts previously requiring error-prone
+path substitution. Software that links against these libraries using
+these scripts should use the much more robust ``pkg-config`` instead.
+The list of recipes changed in this version (and their configuration
+scripts) is as follows::
+
+   directfb (directfb-config)
+   freetype (freetype-config)
+   gpgme (gpgme-config)
+   libassuan (libassuan-config)
+   libcroco (croco-6.0-config)
+   libgcrypt (libgcrypt-config)
+   libgpg-error (gpg-error-config)
+   libksba (ksba-config)
+   libpcap (pcap-config)
+   libpcre (pcre-config)
+   libpng (libpng-config, libpng16-config)
+   libsdl (sdl-config)
+   libusb-compat (libusb-config)
+   libxml2 (xml2-config)
+   libxslt (xslt-config)
+   ncurses (ncurses-config)
+   neon (neon-config)
+   npth (npth-config)
+   pth (pth-config)
+   taglib (taglib-config)
+
+Additionally, support for ``pkg-config`` has been added to some recipes in the
+previous list in the rare cases where the upstream software package does
+not already provide it.
+
+.. _migration-1.7-glibc-replaces-eglibc:
+
+``eglibc 2.19`` Replaced with ``glibc 2.20``
+--------------------------------------------
+
+Because ``eglibc`` and ``glibc`` were already fairly close, this
+replacement should not require any significant changes to other software
+that links to ``eglibc``. However, there were a number of minor changes
+in ``glibc 2.20`` upstream that could require patching some software
+(e.g. the removal of the ``_BSD_SOURCE`` feature test macro).
+
+``glibc 2.20`` requires version 2.6.32 or greater of the Linux kernel.
+Thus, older kernels will no longer be usable in conjunction with it.
+
+For full details on the changes in ``glibc 2.20``, see the upstream
+release notes
+`here <https://sourceware.org/ml/libc-alpha/2014-09/msg00088.html>`__.
+
+.. _migration-1.7-kernel-module-autoloading:
+
+Kernel Module Autoloading
+-------------------------
+
+The :term:`module_autoload_* <module_autoload>` variable is now
+deprecated and a new
+:term:`KERNEL_MODULE_AUTOLOAD` variable
+should be used instead. Also, :term:`module_conf_* <module_conf>`
+must now be used in conjunction with a new
+:term:`KERNEL_MODULE_PROBECONF` variable.
+The new variables no longer require you to specify the module name as
+part of the variable name. This change not only simplifies usage but
+also allows the values of these variables to be appropriately
+incorporated into task signatures and thus trigger the appropriate tasks
+to re-execute when changed. You should replace any references to
+``module_autoload_*`` with ``KERNEL_MODULE_AUTOLOAD``, and add any
+modules for which ``module_conf_*`` is specified to
+``KERNEL_MODULE_PROBECONF``.
+
+.. _migration-1.7-qa-check-changes:
+
+QA Check Changes
+----------------
+
+The following changes have occurred to the QA check process:
+
+-  Additional QA checks ``file-rdeps`` and ``build-deps`` have been
+   added in order to verify that file dependencies are satisfied (e.g.
+   package contains a script requiring ``/bin/bash``) and build-time
+   dependencies are declared, respectively. For more information, please
+   see the ":doc:`/ref-manual/qa-checks`" chapter.
+
+-  Package QA checks are now performed during a new
+   :ref:`ref-tasks-package_qa` task rather than being
+   part of the :ref:`ref-tasks-package` task. This allows
+   more parallel execution. This change is unlikely to be an issue
+   except for highly customized recipes that disable packaging tasks
+   themselves by marking them as ``noexec``. For those packages, you
+   will need to disable the ``do_package_qa`` task as well.
+
+-  Files being overwritten during the
+   :ref:`ref-tasks-populate_sysroot` task now
+   trigger an error instead of a warning. Recipes should not be
+   overwriting files written to the sysroot by other recipes. If you
+   have these types of recipes, you need to alter them so that they do
+   not overwrite these files.
+
+   You might now receive this error after changes in configuration or
+   metadata resulting in orphaned files being left in the sysroot. If
+   you do receive this error, the way to resolve the issue is to delete
+   your :term:`TMPDIR` or to move it out of the way and
+   then re-start the build. Anything that has been fully built up to
+   that point and does not need rebuilding will be restored from the
+   shared state cache and the rest of the build will be able to proceed
+   as normal.
+
+.. _migration-1.7-removed-recipes:
+
+Removed Recipes
+---------------
+
+The following recipes have been removed:
+
+-  ``x-load``: This recipe has been superseded by U-Boot SPL for all
+   Cortex-based TI SoCs. For legacy boards, the ``meta-ti`` layer, which
+   contains a maintained recipe, should be used instead.
+
+-  ``ubootchart``: This recipe is obsolete. A ``bootchart2`` recipe has
+   been added to functionally replace it.
+
+-  ``linux-yocto 3.4``: Support for the linux-yocto 3.4 kernel has been
+   dropped. Support for the 3.10 and 3.14 kernels remains, while support
+   for version 3.17 has been added.
+
+-  ``eglibc`` has been removed in favor of ``glibc``. See the
+   ":ref:`migration-1.7-glibc-replaces-eglibc`" section for more information.
+
+.. _migration-1.7-miscellaneous-changes:
+
+Miscellaneous Changes
+---------------------
+
+The following miscellaneous change occurred:
+
+-  The build history feature now writes ``build-id.txt`` instead of
+   ``build-id``. Additionally, ``build-id.txt`` now contains the full
+   build header as printed by BitBake upon starting the build. You
+   should manually remove old "build-id" files from your existing build
+   history repositories to avoid confusion. For information on the build
+   history feature, see the
+   ":ref:`dev-manual/common-tasks:maintaining build output quality`"
+   section in the Yocto Project Development Tasks Manual.
+
+