From e00a62c905045b57dc6e472d4a08f46cc17aaf04 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Wed, 13 Apr 2016 17:08:48 -0700 Subject: ref-manual: Added the migration section for 2.1 (From yocto-docs rev: ed1eec9139d8a9caf32f0cc896f651cafecece4f) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- documentation/ref-manual/migration.xml | 552 ++++++++++++++++++++++++++++++++- 1 file changed, 540 insertions(+), 12 deletions(-) diff --git a/documentation/ref-manual/migration.xml b/documentation/ref-manual/migration.xml index 670e1c1f7d..e6c0aa36b8 100644 --- a/documentation/ref-manual/migration.xml +++ b/documentation/ref-manual/migration.xml @@ -2447,9 +2447,10 @@ - d.delVar('VARNAME') and - d.setVar('VARNAME', None) result - in the variable and all of its overrides being cleared out. + d.delVar('varname') and + d.setVar('varname', None) + result in the variable and all of its overrides being + cleared out. Before the change, only the non-overridden values were cleared. @@ -2734,23 +2735,550 @@ Yocto Project 2.1 Release from the prior release. -
- Stuff to Remember When Creating this Section +
+ Variable Expansion in Python Functions - This is a note from Alexander Kanavin regarding qt4 stuff. + Variable expressions, such as + ${varname} + no longer expand automatically within Python functions. + Suppressing expansion was done to allow Python functions to + construct shell scripts or other code for situations in which you + do not want such expressions expanded. + For any existing code that relies on these expansions, you need to + change the expansions to either expand the value of individual + variables through d.getVar(). + To alternatively expand more complex expressions, + use d.expand(). + +
+ +
+ Overrides Must Now be Lower-Case + + + The convention for overrides has always been for them to be + lower-case characters. + This practice is now a requirement as BitBake's datastore now + assumes lower-case characters in order to give a slight performance + boost during parsing. + In practical terms, this requirement means that anything that ends + up in + OVERRIDES + must now appear in lower-case characters (e.g. values for + MACHINE, TARGET_ARCH, + DISTRO, and also recipe names if + _pn-recipename + overrides are to be effective). + +
+ +
+ Expand Parameter to <filename>getVar()</filename> and + <filename>getVarFlag()</filename> is Now Mandatory + + + The expand parameter to getVar() and + getVarFlag() previously defaulted to + False if not specified. + Now, however, no default exists so one must be specified. + You must change any getVar() calls that + do not specify the final expand parameter to calls that do specify + the parameter. + You can run the following sed command at the + base of a layer to make this change: + + sed -e 's:\(\.getVar([^,()]*\)):\1, False):g' -i `grep -ril getVar *` + sed -e 's:\(\.getVarFlag([^,()]*, [^,()]*\)):\1, False):g' -i `grep -ril getVarFlag *` + - Qt4 recipes and classes have been removed in YP 2.1 because - Qt4.x has reached end of life upstream. For legacy applications - and LSB compliancy purposes Qt4 can be found in meta-qt4 - repository, and for any new development Qt5 is available at - meta-qt5 repository(provide links to both). + 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.
-
+
+ Makefile Environment Changes + + + EXTRA_OEMAKE + now defaults to "" instead of "-e MAKEFLAGS=". + Setting EXTRA_OEMAKE to "-e MAKEFLAGS=" by + default was a historical accident that has required many classes + (e.g. autotools, module) + and recipes to override this default in order to work with + sensible build systems. + When upgrading to the release, you must edit any recipe that + relies upon this old default by either setting + EXTRA_OEMAKE back to "-e MAKEFLAGS=" or by + explicitly setting any required variable value overrides using + EXTRA_OEMAKE, which is typically only needed + when a Makefile sets a default value for a variable that is + inappropriate for cross-compilation using the "=" operator rather + than the "?=" operator. + +
+ +
+ <filename>libexecdir</filename> Reverted to <filename>${prefix}/libexec</filename> + + + The use of ${libdir}/${BPN} as + libexecdir is different as compared to all + other mainstream distributions, which either uses + ${prefix}/libexec or + ${libdir}. + The use is also contrary to the GNU Coding Standards + (i.e. ) + that suggest ${prefix}/libexec and also + notes that any package-specific nesting should be done by the + package itself. + Finally, having libexecdir change between + recipes makes it very difficult for different recipes to invoke + binaries that have been installed into + libexecdir. + The Filesystem Hierarchy Standard + (i.e. ) + now recognizes the use of ${prefix}/libexec/, + giving distributions the choice between + ${prefix}/lib or + ${prefix}/libexec without breaking FHS. + +
+ +
+ <filename>ac_cv_sizeof_off_t</filename> is No Longer Cached in Site Files + + + For recipes inheriting the + autotools + class, ac_cv_sizeof_off_t is no longer cached + in the site files for autoconf. + The reason for this change is because the + ac_cv_sizeof_off_t value is not necessarily + static per architecture as was previously assumed. + Rather, the value changes based on whether large file support is + enabled. + For most software that uses autoconf, this + change should not be a problem. + However, if you have a recipe that bypasses the standard + do_configure + task from the autotools class and the software + the recipe is building uses a very old version of + autoconf, the recipe might be incapable of + determining the correct size of off_t during + do_configure. + + + + The best course of action is to patch the software as necessary + to allow the default implementation from the + autotools class to work such that + autoreconf succeeds and produces a working + configure script), and to remove the + overridden do_configure task such that the + default implementation does get used. + +
+ +
+ Image Generation is Now Split Out from Filesystem Generation + + + Previously, for image recipes the + do_rootfs + task assembled the filesystem and then from that filesystem + generated images. + With this Yocto Project release, image generation is split into + separate + do_image_* + tasks for clarity both in operation and in the code. + + + + For most cases, this change does not present any problems. + However, if you have made customizations that directly modify the + do_rootfs task or that mention + do_rootfs, you might need to update those + changes. + In particular, if you had added any tasks after + do_rootfs, you should make edits so that + those tasks are after the + do_image_complete + task rather than before the task so that the your added tasks + run at the correct time. + + + + A minor part of this restructuring is that the post-processing + definitions and functions have been moved from the + image + class to the + rootfs-postcommands + class. + Functionally, however, they remain unchanged. + +
+ +
+ Removed Recipes + + + The following recipes have been removed in the 2.1 release: + + gcc version 4.8: + Versions 4.9 and 5.3 remain. + + qt4: + All support for Qt 4.x has been moved out to a separate + meta-qt4 layer because Qt 4 is no + longer supported upstream. + + x11vnc: + Moved to the meta-oe layer. + + linux-yocto-3.14: + No longer supported. + + linux-yocto-3.19: + No longer supported. + + libjpeg: + Replaced by the libjpeg-turbo recipe. + + pth: + Became obsolete. + + liboil: + Recipe is no longer needed and has been moved to the + meta-multimedia layer. + + gtk-theme-torturer: + Recipe is no longer needed and has been moved to the + meta-gnome layer. + + gnome-mime-data: + Recipe is no longer needed and has been moved to the + meta-gnome layer. + + udev: + Replaced by the eudev recipe for + compatibility when using sysvinit + with newer kernels. + + python-pygtk: + Recipe became obsolete. + + adt-installer: + Recipe became obsolete. + See the + "ADT Removed" + section for more information. + + + +
+ +
+ Class Changes + + The following classes have changed: + + autotools_stage: + Removed because the + autotools + class now provides its functionality. + Recipes that inherited from + autotools_stage should now inherit + from autotools instead. + + boot-directdisk: + Merged into the + image-vm + class. + The boot-directdisk class was rarely + directly used. + Consequently, this change should not cause any issues. + + bootimg: + Merged into the + image-live + class. + The bootimg class was rarely + directly used. + Consequently, this change should not cause any issues. + + packageinfo: + Removed due to its limited use by the Hob UI, which has + itself been removed. + + + +
+ +
+ Build System User Interface Changes + + + The following changes have been made to the build system user + interface: + + Hob GTK+-based UI: + Removed because it is unmaintained and based on the + outdated GTK+ 2 library. + The Toaster web-based UI is much more capable and is + actively maintained. + See the + "Using the Toaster Web Interface" + section in the Yocto Project Toaster User Manual for more + information on this interface. + + "puccho" BitBake UI: + Removed because is unmaintained and no longer useful. + + + +
+ +
+ ADT Removed + + + The Application Development Toolkit (ADT) has been removed + because its functionality almost completely overlapped with the + standard SDK + and the + extensible SDK. + For information on these SDKs and how to build and use them, see the + Yocto Project Software Development Kit (SDK) Developer's Guide. + +
+ +
+ Poky Reference Distribution Changes + + + The following changes have been made for the Poky distribution: + + + The meta-yocto layer has been renamed + to meta-poky to better match its + purpose, which is to provide the Poky reference + distribution. + The meta-yocto-bsp layer retains its + original name since it provides reference machines for + the Yocto Project and it is otherwise unrelated to Poky. + References to meta-yocto in your + conf/bblayers.conf should + automatically be updated, so you should not need to change + anything unless you are relying on this naming elsewhere. + + + The + uninative + class is now enabled by default in Poky. + This class attempts to isolate the build system from the + host distribution's C library and makes re-use of native + shared state artifacts across different host distributions + practical. + With this class enabled, a tarball containing a pre-built + C library is downloaded at the start of the build. + + The uninative class is enabled + through the + meta/conf/distro/include/yocto-uninative.inc + file, which for those not using the Poky distribution, can + include to easily enable the same functionality. + + Alternatively, if you wish to build your own + uninative tarball, you can do so by + building the uninative-tarball recipe, + making it available to your build machines + (e.g. over HTTP/HTTPS) and setting a similar configuration + as the one set by yocto-uninative.inc. + + + Static library generation, for most cases, is now disabled + by default in the Poky distribution. + Disabling this generation saves some build time as well + as the size used for build output artifacts. + + Disabling this library generation is accomplished + through a + meta/conf/distro/include/no-static-libs.inc, + which for those not using the Poky distribution can + easily include to enable the same functionality. + + Any recipe that needs to opt-out of having the + "--disable-static" option specified on the configure + command line either because it is not a supported option + for the configure script or because static libraries are + needed should set the following variable: + + DISABLE_STATIC = "" + + + + The separate poky-tiny distribution + now uses the musl C library instead of a heavily pared + down glibc. + Using glibc results in a smaller + distribution and facilitates much greater maintainability + because musl is designed to have a small footprint. + + If you have used poky-tiny and + have customized the glibc + configuration you will need to redo those customizations + with musl when upgrading to the new release. + + + +
+ +
+ Packaging Changes + + + The following changes have been made to packaging: + + + The runuser and + mountpoint binaries, which were + previously in the main util-linux + package, have been split out into the + util-linux-runuser and + util-linux-mountpoint packages, + respectively. + + + The python-elementtree package has + been merged into the python-xml + package. + + + +
+ +
+ Tuning File Changes + + + The following changes have been made to the tuning files: + + + The "no-thumb-interwork" tuning feature has been dropped + from the ARM tune include files. + Because interworking is required for ARM EABI, attempting + to disable it through a tuning feature no longer makes + sense. + + Support for ARM OABI was deprecated in gcc 4.7. + + + + The tune-cortexm*.inc and + tune-cortexr4.inc files have been + removed because they are poorly tested. + Until the OpenEmbedded build system officially gains + support for CPUs without an MMU, these tuning files would + probably be better maintained in a separate layer + if needed. + + + +
+ +
+ Miscellaneous Changes + + + These additional changes exist: + + + The minimum Git version has been increased to 1.8.3.1. + If your host distribution does not provide a sufficiently + recent version, you can install the buildtools, which + will provide it. + + + 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. + + + The + devtool modify + 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" option when running + devtool modify. + + + If the formfactor for a machine is either not supplied + or does not specify whether a keyboard is attached, then + the default is to assume a keyboard is attached rather + than assume no keyboard. + + This change primarily affects the Sato UI. + + + + The .debug directory packaging is + now automatic. + If your recipe builds software that installs binaries into + directories other than the standard ones, you no longer + need to take care of setting + FILES_${PN}-dbg to pick up the + resulting .debug directories as these + directories are automatically found and added. + + + Inaccurate disk and CPU percentage data has been dropped + from buildstats output. + This data has been replaced with + getrusage() data and corrected IO + statistics. + You will probably need to update code that reads the + buildstats data. + + + The + meta/conf/distro/include/package_regex.inc + is now deprecated. + The contents of this file have been moved to individual + recipes. + Tip + Because this file will likely be removed in a future + Yocto Project release, it is suggested that you remove + any references to the file that might be in your + configuration. + + + + The v86d/uvesafb has been removed from + the genericx86 and + genericx86-64 reference machines, + which are provided by the + meta-yocto-bsp layer. + Most modern x86 boards do not rely on this file and it only + adds kernel error messages during startup. + If you do still need the file, you can simply add + v86d to your image. + + + +
+