From b1dc0ee121e575f1978cdea409a16bba4040e5b2 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Fri, 28 Apr 2017 16:23:48 -0700 Subject: ref-manual, dev-manual: Completed first draft of 2.3 migration section. (From yocto-docs rev: 42ab9e34da640b46d39741c9c83648dc65518ec1) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- documentation/ref-manual/migration.xml | 538 ++++++++++++++++++++++++++++++--- 1 file changed, 504 insertions(+), 34 deletions(-) (limited to 'documentation/ref-manual/migration.xml') diff --git a/documentation/ref-manual/migration.xml b/documentation/ref-manual/migration.xml index ddd6644240..f46d230577 100644 --- a/documentation/ref-manual/migration.xml +++ b/documentation/ref-manual/migration.xml @@ -3689,7 +3689,7 @@ $ runqemu qemux86-64 tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64. by BB_SETSCENE_VERIFY_FUNCTION needed to change signature. Consequently, a new variable named - BB_SETSCENE_VERIFY_FUNCTION2 + BB_SETSCENE_VERIFY_FUNCTION2 has been added allowing multiple versions of BitBake to work with suitably written metadata, which includes OpenEmbedded-Core and Poky. @@ -3974,20 +3974,100 @@ $ runqemu qemux86-64 tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64. 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 a previous release. + to be present in the shared sysroot in previous releases. - 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. - + Consider the following: + + + Declare Build-Time Dependencies: + 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. + + + Specify Pre-Installation and Post-Installtion + Native Tool Dependencies: + You must specifically specify any special native tool + dependencies of pkg_preinst and + pkg_postinst scripts by using the + PACKAGE_WRITE_DEPS + variable. + Specifying these dependencies ensures that these tools + are available if these scripts need to be run on the + build host during the + do_rootfs + task. + + As an example, see the dbus + recipe. + You will see that this recipe has a + pkg_postinst that calls + systemctl if "systemd" is in + DISTRO_FEATURES. + In the example, + systemd-systemctl-native is added to + PACKAGE_WRITE_DEPS, which is also + conditional on "systemd" being in + DISTRO_FEATURES. + + + Examine Recipes that Use + SSTATEPOSTINSTFUNCS: + You need to examine any recipe that uses + SSTATEPOSTINSTFUNCS and determine + steps to take. + + Functions added to + SSTATEPOSTINSTFUNCS 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 SSTATEPOSTINSTFUNCS are + doing relocation, then you will need to change these + to use a post-installation script that is installed by a + function added to + SYSROOT_PREPROCESS_FUNCS. + - - You can find information on how this works in the - staging - class. + For an example, see the + pixbufcache class in + meta/classes/ in the Yocto Project + Source Repositories. + + The SSTATEPOSTINSTFUNCS variable + itself is now deprecated in favor of the + do_populate_sysroot[postfuncs] + 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 + SSTATEPOSTINSTFUNCS is + removed in a future Yocto Project release. + + + + Specify Which + STAGING_DIR_NATIVE is Used: + Because the shared sysroot is now gone, the scripts + oe-find-native-sysroot and + oe-run-native have been changed such + that you need to specify which recipe's + STAGING_DIR_NATIVE + is used. + + + + You can find more information on how recipe-specific sysroots + work in the + "staging.bbclass" + section. + @@ -3997,16 +4077,21 @@ $ runqemu qemux86-64 tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64. Within the environment used to run build tasks, the environment variable PATH is now sanitized such that - symbolic links linking only the binaries from the host mentioned - in the + the normal native binary paths + (/bin, /sbin, + /usr/bin and so forth) are + removed and a directory containing symbolic links linking only + to the binaries from the host mentioned in the HOSTTOOLS and HOSTTOOLS_NONFATAL - variables into - their own directory are added to PATH. - Consequently, any native binaries that you need to call should - either be in one of these two variables at the configuration - level. + variables is added to PATH. + + + + 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. @@ -4024,6 +4109,60 @@ $ runqemu qemux86-64 tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64. +
+ Changes to Scripts + + + The following changes to scripts took place: + + + oe-find-native-sysroot: + The usage for the + oe-find-native-sysroot script has + changed to the following: + + $ . oe-find-native-sysroot recipe + + You must now supply a recipe for + recipe as part of the command. + Prior to the Yocto Project &DISTRO; release, it was not + necessary to provide the script with the command. + + + oe-run-native: + The usage for the + oe-run-native script has changed + to the following: + + $ oe-run-native native_recipe tool + + 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. + + + cleanup-workdir: + The cleanup-workdir 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 + TMPDIR + and getting it wrong, it is recommended that you + delete TMPDIR and have it restored + from shared state (sstate) on subsequent builds. + + + wipe-sysroot: + The wipe-sysroot script has been + removed as it is no longer needed with recipe-specific + sysroots. + + + +
+
Changes to Functions @@ -4055,7 +4194,7 @@ $ runqemu qemux86-64 tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64. provides a graphical way of exploring the task-depends.dot file. The data presented by Task Explorer is much more - accurate than the data that is presented by + accurate than the data that was presented by depexp. Being able to visualize the data is an often requested feature as standard *.dot file @@ -4063,7 +4202,7 @@ $ runqemu qemux86-64 tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64. the task-depends.dot file. - Dependency Tree Information Removals: + BitBake "-g" Output Changes: The package-depends.dot and pn-depends.dot files as previously generated using the bitbake -g command @@ -4080,6 +4219,48 @@ $ runqemu qemux86-64 tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64. into account task-level dependencies between recipes, which could be misleading. + + Mirror Variable Splitting Changes: + Mirror variables including + MIRRORS, + PREMIRRORS, + and + SSTATE_MIRRORS + 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. + + + The Subversion (SVN) Fetcher Uses an "ssh" Parameter and Not an "rsh" Parameter: + 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 + ssh program used by SVN. + The SVN fetcher passes the new parameter through the + SVN_SSH environment variable during + the + do_fetch + task. + + See the + "Subversion (SVN) Fetcher (svn://)" + section in the Yocto Project BitBake User Manual for + additional information. + + + BB_SETSCENE_VERIFY_FUNCTION + and BB_SETSCENE_VERIFY_FUNCTION2 + Removed: + Because the mechanism they were part of is no longer + necessary with recipe-specific sysroots, the + BB_SETSCENE_VERIFY_FUNCTION and + BB_SETSCENE_VERIFY_FUNCTION2 + variables have been removed. +
@@ -4117,8 +4298,8 @@ $ runqemu qemux86-64 tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64. INCOMPATIBLE_LICENSE to exclude GPLv3 or set PREFERRED_VERSION - to select recipes that use GPLv3, then you must add the - meta-gplv2 layer to your configuration. + to substitute a GPLv2 version of a GPLv3 recipe, then you must add + the meta-gplv2 layer to your configuration. You can find meta-gplv2 layer in the OpenEmbedded layer index at @@ -4127,7 +4308,7 @@ $ runqemu qemux86-64 tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64. - These relocated GPLv3 recipes do not receive the same level of + 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. @@ -4153,11 +4334,11 @@ $ runqemu qemux86-64 tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64. The following package management changes took place: - Smart package manager is replaced by Dnf package manager. + 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. + DNF is the only feasible candidate. 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 @@ -4165,14 +4346,14 @@ $ runqemu qemux86-64 tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64. If you have scripts that call the tool directly, or use its API, they need to be fixed. For more information, see the - Dnf Documentation. + DNF Documentation. Rpm 5.x is replaced with Rpm 4.x. This is done for two major reasons: - Dnf is API-incompatible with Rpm 5.x and porting + DNF is API-incompatible with Rpm 5.x and porting it and maintaining the port is non-trivial. @@ -4193,8 +4374,6 @@ $ runqemu qemux86-64 tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64. As a result, most mainstream open source projects that require DB are still developed and tested with DB 5.x. - By extension,all the open source projects are still - developed and tested with DB 5.x In OE-core, the only thing that was requiring @@ -4220,7 +4399,7 @@ $ runqemu qemux86-64 tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64. Architecture-independent RPM packages are "noarch" instead of "all". This change was made because too many places in - dnf/rpm4 stack already make that assumption. + 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 @@ -4233,16 +4412,307 @@ $ runqemu qemux86-64 tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64. is not currently supported. This issue will be fully addressed in a future Yocto Project release. + See defect 11209 + for more information on a solution to package feed + signing with RPM in the Yocto Project 2.3 release. + + + 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. - See the defect - 11209 - for more information on a solution to package feed - signing with RPM in the Yocto Project 2.3 release. + For further details on this change, see the + commit message. + +
+ Removed Recipes + + + The following recipes have been removed: + + + linux-yocto 4.8: + Version 4.8 has been removed. + Versions 4.1 (LTSI), 4.4 (LTS), 4.9 (LTS/LTSI) and 4.10 + are now present. + + + python-smartpm: + Functionally replaced by dnf. + + + createrepo: + Replaced by the createrepo-c recipe. + + + rpmresolve: + No longer needed with the move to RPM 4 as RPM itself is + used instead. + + + gstreamer: + Removed the GStreamer Git version recipes as they have + been stale. + 1.10.x + recipes are still present. + + + alsa-conf-base: + Merged into alsa-conf since + libasound depended on both. + Essentially, no way existed to install only one of these. + + + tremor: + Moved to meta-multimedia. + 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 + tremor recipe in OE-Core. + + + gummiboot: + Replaced by systemd-boot. + + + +
+ +
+ Wic Changes + + + The following changes have been made to Wic: + + For more information on Wic, see the + "Creating Partitioned Images" + section in the Yocto Project Development Manual. + + + + Default Output Directory Changed: + Wic's default output directory is now the current directory + by default instead of the unusual + /var/tmp/wic. + + 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. + + + fsimage Plug-in Removed: + The Wic fsimage plug-in has been removed as it duplicates + functionality of the rawcopy plug-in. + + + +
+ +
+ QA Changes + + + The following QA checks have changed: + + + unsafe-references-in-binaries: + The unsafe-references-in-binaries + QA check, which was disabled by default, has now been + removed. + This check was intended to detect binaries in + /bin that link to libraries in + /usr/lib and have the case where + the user has /usr on a separate + filesystem to /. + + The removed QA check was buggy. + Additionally, /usr residing on a + separate partition from / is now + a rare configuration. + Consequently, + unsafe-references-in-binaries was + removed. + + + file-rdeps: + The file-rdeps 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. + + For additional information, see the + insane + class and the + "Errors and Warnings" + section. + + + +
+ +
+ Miscellaneous Changes + + + The following miscellaneous changes have occurred: + + + In this release, a number of recipes have been changed to + ignore the largefile + DISTRO_FEATURES + item, enabling large file support unconditionally. + This feature has always been enabled by default. + Disabling the feature has not been widely tested. + + Future releases of the Yocto Project will remove + entirely the ability to disable the + largefile feature, + which would make it unconditionally enabled everywhere. + + + + If the + DISTRO_VERSION + value contains the value of the + DATE + variable, which is the default between Poky releases, + the DATE value is explicitly excluded + from /etc/issue and + /etc/issue.net, which is displayed at + the login prompt, in order to avoid conflicts with + Multilib enabled. + Regardless, the DATE value is + inaccurate if the base-files + recipe is restored from shared state (sstate) rather + than rebuilt. + + If you need the build date recorded in + /etc/issue* 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 + ROOTFS_POSTPROCESS_COMMAND. + Doing so ensures the value is always up-to-date with the + created image. + + + Dropbear's init 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. + + + The + buildhistory + class now correctly uses tabs as separators between all + columns in installed-package-sizes.txt + in order to aid import into other tools. + + + The USE_LDCONFIG variable has been + replaced with the "ldconfig" + DISTRO_FEATURES + feature. + Distributions that previously set: + + USE_LDCONFIG = "0" + + should now instead use the following: + + DISTRO_FEATURES_BACKFILL_CONSIDERED_append = " ldconfig" + + + + The default value of + COPYLEFT_LICENSE_INCLUDE + now includes all versions of AGPL licenses in addition + to GPL and LGPL. + + 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. + + + + 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: + + KERNEL_MODULE_PACKAGE_SUFFIX to "" + + + + Removal of libtool + *.la files is now enabled by default. + The *.la files are not actually + needed on Linux and relocating them is an unnecessary + burden. + + If you need to preserve these + .la files (e.g. in a custom + distribution), you must change + INHERIT_DISTRO + such that "remove-libtool" is not included in the value. + + + 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 + uninative shared state (sstate) + package is built. + See the + uninative + class for additional information. + + + All native and nativesdk recipes now use a separate + DISTRO_FEATURES + value instead of sharing the value used by recipes for the + target, in order to avoid unnecessary rebuilds. + + The DISTRO_FEATURES for + native recipes is + DISTRO_FEATURES_NATIVE added to an + intersection of DISTRO_FEATURES and + DISTRO_FEATURES_FILTER_NATIVE. + + For nativesdk recipes, the + corresponding variables are + DISTRO_FEATURES_NATIVESDK and + DISTRO_FEATURES_FILTER_NATIVESDK. + + + The FILESDIR + variable, which was previously deprecated and rarely used, + has now been removed. + You should change any recipes that set + FILESDIR to set + FILESPATH + instead. + + + The MULTIMACH_HOST_SYS + variable has been removed as it is no longer needed + with recipe-specific sysroots. + + + +