diff options
Diffstat (limited to 'external/poky/documentation/ref-manual/migration.xml')
| -rw-r--r-- | external/poky/documentation/ref-manual/migration.xml | 1011 |
1 files changed, 990 insertions, 21 deletions
diff --git a/external/poky/documentation/ref-manual/migration.xml b/external/poky/documentation/ref-manual/migration.xml index c648d8d4..affc8b90 100644 --- a/external/poky/documentation/ref-manual/migration.xml +++ b/external/poky/documentation/ref-manual/migration.xml @@ -680,7 +680,7 @@ <para> For more information on this requirement, see the - "<link linkend='required-git-tar-and-python-versions'>Required Git, tar, and Python Versions</link>" + "<link linkend='required-git-tar-python-and-gcc-versions'>Required Git, tar, Python and gcc Versions</link>" section. </para> </section> @@ -875,8 +875,7 @@ not work. This change is intended to catch those kinds of situations. Valid <filename>IMAGE_FEATURES</filename> are drawn from - <link linkend='var-PACKAGE_GROUP'><filename>PACKAGE_GROUP</filename></link> - definitions, + <filename>PACKAGE_GROUP</filename> definitions, <link linkend='var-COMPLEMENTARY_GLOB'><filename>COMPLEMENTARY_GLOB</filename></link> and a new "validitems" varflag on <filename>IMAGE_FEATURES</filename>. @@ -1404,8 +1403,7 @@ <para> The - <link linkend='var-PACKAGE_GROUP'><filename>PACKAGE_GROUP</filename></link> - variable has been renamed to + <filename>PACKAGE_GROUP</filename> variable has been renamed to <link linkend='var-FEATURE_PACKAGES'><filename>FEATURE_PACKAGES</filename></link> to more accurately reflect its purpose. You can still use <filename>PACKAGE_GROUP</filename> but @@ -1754,7 +1752,7 @@ Git that meets this requirement, you can use the <filename>buildtools-tarball</filename> that does. See the - "<link linkend='required-git-tar-and-python-versions'>Required Git, tar, and Python Versions</link>" + "<link linkend='required-git-tar-python-and-gcc-versions'>Required Git, tar, Python and gcc Versions</link>" section for more information. </para> </section> @@ -2103,15 +2101,14 @@ </para> <para> - Additionally, a - <link linkend='ref-classes-bluetooth'><filename>bluetooth</filename></link> - class has been added to make selection of the appropriate bluetooth - support within a recipe a little easier. + Additionally, a <filename>bluetooth</filename> class has been added + to make selection of the appropriate bluetooth support within a + recipe a little easier. If you wish to make use of this class in a recipe, add something such as the following: <literallayout class='monospaced'> inherit bluetooth - PACKAGECONFIG ??= "${@bb.utils.contains('DISTRO_FEATURES', 'bluetooth', '${BLUEZ}', '', d)} + PACKAGECONFIG ??= "${@bb.utils.contains('DISTRO_FEATURES', 'bluetooth', '${BLUEZ}', '', d)}" PACKAGECONFIG[bluez4] = "--enable-bluetooth,--disable-bluetooth,bluez4" PACKAGECONFIG[bluez5] = "--enable-bluez5,--disable-bluez5,bluez5" </literallayout> @@ -2566,9 +2563,7 @@ <link linkend='oe-core'>OE-Core</link>. The change includes <filename>package_regex.inc</filename> and <filename>distro_alias.inc</filename>, which are typically enabled - when using the - <link linkend='ref-classes-distrodata'><filename>distrodata</filename></link> - class. + when using the <filename>distrodata</filename> class. Additionally, the contents of <filename>upstream_tracking.inc</filename> has now been split out to the relevant recipes. @@ -3218,7 +3213,7 @@ recent version, you can install the buildtools, which will provide it. See the - "<link linkend='required-git-tar-and-python-versions'>Required Git, tar, and Python Versions</link>" + "<link linkend='required-git-tar-python-and-gcc-versions'>Required Git, tar, Python and gcc Versions</link>" section for more information on the buildtools tarball. </para></listitem> <listitem><para> @@ -3627,7 +3622,7 @@ $ runqemu qemux86-64 tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64. image types, this part of the kernel image base name as been removed leaving only the following: <literallayout class='monospaced'> - KERNEL_IMAGE_BASE_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}-${DATETIME} + KERNEL_IMAGE_BASE_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}-${DATETIME}" </literallayout> If you have recipes or classes that use <filename>KERNEL_IMAGE_BASE_NAME</filename> directly, you might @@ -4506,8 +4501,8 @@ id=f4d4f99cfbc2396e49c1613a7d237b9e57f06f81'>commit message</ulink>. </para></listitem> <listitem><para> <emphasis>fsimage Plug-in Removed:</emphasis> - The Wic fsimage plug-in has been removed as it duplicates - functionality of the rawcopy plug-in. + The Wic fsimage plugin has been removed as it duplicates + functionality of the rawcopy plugin. </para></listitem> </itemizedlist> </para> @@ -4742,7 +4737,7 @@ id=f4d4f99cfbc2396e49c1613a7d237b9e57f06f81'>commit message</ulink>. <para> This section provides information about packaging changes that have - ocurred: + occurred: <itemizedlist> <listitem><para> <emphasis><filename>python3</filename> Changes:</emphasis> @@ -5604,7 +5599,7 @@ id=f4d4f99cfbc2396e49c1613a7d237b9e57f06f81'>commit message</ulink>. creation time, use <filename>pkg_postinst_ontarget()</filename> or call - <filename>postinst-intercepts defer_to_first_boot</filename> + <filename>postinst_intercept delay_to_first_boot</filename> from <filename>pkg_postinst()</filename>. Any failure of a <filename>pkg_postinst()</filename> script (including <filename>exit 1</filename>) @@ -6195,7 +6190,7 @@ id=f4d4f99cfbc2396e49c1613a7d237b9e57f06f81'>commit message</ulink>. If you want to explicitly defer a postinstall to first boot on the target rather than at rootfs creation time, use <filename>pkg_postinst_ontarget()</filename> or call - <filename>postinst-intercepts defer_to_first_boot</filename> from + <filename>postinst_intercept delay_to_first_boot</filename> from <filename>pkg_postinst()</filename>. Any failure of a <filename>pkg_postinst()</filename> script (including exit 1) triggers an error during the @@ -6325,6 +6320,980 @@ id=f4d4f99cfbc2396e49c1613a7d237b9e57f06f81'>commit message</ulink>. </para> </section> </section> + +<section id='moving-to-the-yocto-project-2.7-release'> + <title>Moving to the Yocto Project 2.7 Release</title> + + <para> + This section provides migration information for moving to the + Yocto Project 2.7 Release from the prior release. + </para> + + <section id='migration-2.7-bitbake-changes'> + <title>BitBake Changes</title> + + <para> + The following changes have been made to BitBake: + <itemizedlist> + <listitem><para> + BitBake now checks anonymous Python functions and pure + Python functions (e.g. <filename>def funcname:</filename>) + in the metadata for tab indentation. + If found, BitBake produces a warning. + </para></listitem> + <listitem><para> + Bitbake now checks + <link linkend='var-BBFILE_COLLECTIONS'><filename>BBFILE_COLLECTIONS</filename></link> + for duplicate entries and triggers an error if any are + found. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-2.7-eclipse-support-dropped'> + <title><trademark class='trade'>Eclipse</trademark> Support Removed</title> + + <para> + Support for the Eclipse IDE has been removed. + Support continues for those releases prior to 2.7 that did include + support. + The 2.7 release does not include the Eclipse Yocto plugin. + </para> + </section> + + <section id='migration-2.7-qemu-native-splits-system-and-user-mode-parts'> + <title><filename>qemu-native</filename> Splits the System and User-Mode Parts</title> + + <para> + The system and user-mode parts of <filename>qemu-native</filename> + are now split. + <filename>qemu-native</filename> provides the user-mode components + and <filename>qemu-system-native</filename> provides the system + components. + If you have recipes that depend on QEMU's system emulation + functionality at build time, they should now depend upon + <filename>qemu-system-native</filename> instead of + <filename>qemu-native</filename>. + </para> + </section> + + <section id='migration-2.7-upstream-tracking.inc-removed'> + <title>The <filename>upstream-tracking.inc</filename> File Has Been Removed</title> + + <para> + The previously deprecated <filename>upstream-tracking.inc</filename> + file is now removed. + Any <filename>UPSTREAM_TRACKING*</filename> variables are now set + in the corresponding recipes instead. + </para> + + <para> + Remove any references you have to the + <filename>upstream-tracking.inc</filename> file in your + configuration. + </para> + </section> + + <section id='migration-2.7-distro-features-libc-removed'> + <title>The <filename>DISTRO_FEATURES_LIBC</filename> Variable Has Been Removed</title> + + <para> + The <filename>DISTRO_FEATURES_LIBC</filename> variable is no + longer used. + The ability to configure glibc using kconfig has been removed + for quite some time making the <filename>libc-*</filename> features + set no longer effective. + </para> + + <para> + Remove any references you have to + <filename>DISTRO_FEATURES_LIBC</filename> in your own layers. + </para> + </section> + + <section id='migration-2.7-license-values'> + <title>License Value Corrections</title> + + <para> + The following corrections have been made to the + <link linkend='var-LICENSE'><filename>LICENSE</filename></link> + values set by recipes: + <literallayout class='monospaced'> + <emphasis>socat</emphasis>: Corrected <filename>LICENSE</filename> to be "GPLv2" rather than + "GPLv2+". + + <emphasis>libgfortran</emphasis>: Set license to "GPL-3.0-with-GCC-exception". + + <emphasis>elfutils</emphasis>: Removed "Elfutils-Exception" and set to "GPLv2" for shared + libraries + </literallayout> + </para> + </section> + + <section id='migration-2.7-packaging-changes'> + <title>Packaging Changes</title> + + <para> + This section provides information about packaging changes. + <itemizedlist> + <listitem><para> + <filename>bind</filename>: The + <filename>nsupdate</filename> binary has been moved to + the <filename>bind-utils</filename> package. + </para></listitem> + <listitem><para> + Debug split: The default debug split has been changed to + create separate source packages (i.e. + <replaceable>package_name</replaceable><filename>-dbg</filename> + and + <replaceable>package_name</replaceable><filename>-src</filename>). + If you are currently using <filename>dbg-pkgs</filename> + in + <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link> + to bring in debug symbols and you still need the sources, + you must now also add <filename>src-pkgs</filename> to + <filename>IMAGE_FEATURES</filename>. + Source packages remain in the target portion of the SDK + by default, unless you have set your own value for + <link linkend='var-SDKIMAGE_FEATURES'><filename>SDKIMAGE_FEATURES</filename></link> + that does not include <filename>src-pkgs</filename>. + </para></listitem> + <listitem><para> + Mount all using <filename>util-linux</filename>: + <filename>/etc/default/mountall</filename> has + moved into the -mount sub-package. + </para></listitem> + <listitem><para> + Splitting binaries using <filename>util-linux</filename>: + <filename>util-linux</filename> now splits each binary into + its own package for fine-grained control. + The main <filename>util-linux</filename> package pulls in + the individual binary packages using the + <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link> + and + <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link> + variables. + As a result, existing images should not see any changes + assuming + <link linkend='var-NO_RECOMMENDATIONS'><filename>NO_RECOMMENDATIONS</filename></link> + is not set. + </para></listitem> + <listitem><para> + <filename>netbase/base-files</filename>: + <filename>/etc/hosts</filename> has moved from + <filename>netbase</filename> to + <filename>base-files</filename>. + </para></listitem> + <listitem><para> + <filename>tzdata</filename>: The main package has been + converted to an empty meta package that pulls in all + <filename>tzdata</filename> packages by default. + </para></listitem> + <listitem><para> + <filename>lrzsz</filename>: This package has been removed + from <filename>packagegroup-self-hosted</filename> and + <filename>packagegroup-core-tools-testapps</filename>. + The X/Y/ZModem support is less likely to be needed on + modern systems. + If you are relying on these packagegroups to include the + <filename>lrzsz</filename> package in your image, you + now need to explicitly add the package. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-2.7-removed-recipes'> + <title>Removed Recipes</title> + + <para> + The following recipes have been removed: + <literallayout class='monospaced'> + <emphasis>gcc</emphasis>: Drop version 7.3 recipes. Version 8.3 now remains. + + <emphasis>linux-yocto</emphasis>: Drop versions 4.14 and 4.18 recipes. Versions 4.19 and 5.0 remain. + + <emphasis>go</emphasis>: Drop version 1.9 recipes. Versions 1.11 and 1.12 remain. + + <emphasis>xvideo-tests</emphasis>: Became obsolete. + + <emphasis>libart-lgpl</emphasis>: Became obsolete. + + <emphasis>gtk-icon-utils-native</emphasis>: These tools are now provided by gtk+3-native + + <emphasis>gcc-cross-initial</emphasis>: No longer needed. gcc-cross/gcc-crosssdk is now used instead. + + <emphasis>gcc-crosssdk-initial</emphasis>: No longer needed. gcc-cross/gcc-crosssdk is now used instead. + + <emphasis>glibc-initial</emphasis>: Removed because the benefits of having it for site_config are + currently outweighed by the cost of building the recipe. + </literallayout> + </para> + </section> + + <section id='migration-2.7-removed-classes'> + <title>Removed Classes</title> + + <para> + The following classes have been removed: + <literallayout class='monospaced'> + <emphasis>distutils-tools</emphasis>: This class was never used. + + <emphasis>bugzilla.bbclass</emphasis>: Became obsolete. + + <emphasis>distrodata</emphasis>: This functionally has been replaced by a more modern + tinfoil-based implementation. + </literallayout> + </para> + </section> + + <section id='migration-2.7-miscellaneous-changes'> + <title>Miscellaneous Changes</title> + + <para> + The following miscellaneous changes occurred: + <itemizedlist> + <listitem><para> + The <filename>distro</filename> subdirectory of the Poky + repository has been removed from the top-level + <filename>scripts</filename> directory. + </para></listitem> + <listitem><para> + Perl now builds for the target using + <ulink url='http://arsv.github.io/perl-cross/'><filename>perl-cross</filename></ulink> + for better maintainability and improved build performance. + This change should not present any problems unless you have + heavily customized your Perl recipe. + </para></listitem> + <listitem><para> + <filename>arm-tunes</filename>: Removed the "-march" + option if mcpu is already added. + </para></listitem> + <listitem><para> + <filename>update-alternatives</filename>: Convert file + renames to + <link linkend='var-PACKAGE_PREPROCESS_FUNCS'><filename>PACKAGE_PREPROCESS_FUNCS</filename></link> + </para></listitem> + <listitem><para> + <filename>base/pixbufcache</filename>: Obsolete + <filename>sstatecompletions</filename> code has been + removed. + </para></listitem> + <listitem><para> + <link linkend='ref-classes-native'><filename>native</filename></link> + class: + <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link> + handling has been enabled. + </para></listitem> + <listitem><para> + <filename>inetutils</filename>: This recipe has rsh + disabled. + </para></listitem> + </itemizedlist> + </para> + </section> +</section> + +<section id='moving-to-the-yocto-project-3.0-release'> + <title>Moving to the Yocto Project 3.0 Release</title> + + <para> + This section provides migration information for moving to the + Yocto Project 3.0 Release from the prior release. + </para> + + <section id='migration-3.0-init-system-selection'> + <title>Init System Selection</title> + + <para> + Changing the init system manager previously required setting a + number of different variables. + You can now change the manager by setting the + <filename>INIT_MANAGER</filename> variable and the corresponding + include files + (i.e. <filename>conf/distro/include/init-manager-*.conf</filename>). + Include files are provided for four values: "none", "sysvinit", + "systemd", and "mdev-busybox". + The default value, "none", for <filename>INIT_MANAGER</filename> + should allow your current settings to continue working. + However, it is advisable to explicitly set + <filename>INIT_MANAGER</filename>. + </para> + </section> + + <section id='migration-3.0-lsb-support-removed'> + <title>LSB Support Removed</title> + + <para> + Linux Standard Base (LSB) as a standard is not current, and + is not well suited for embedded applications. + Support can be continued in a separate layer if needed. + However, presently LSB support has been removed from the core. + </para> + + <para> + As a result of this change, the <filename>poky-lsb</filename> + derivative distribution configuration that was also used for + testing alternative configurations has been replaced with a + <filename>poky-altcfg</filename> distribution that has LSB + parts removed. + </para> + </section> + + <section id='migration-3.0-removed-recipes'> + <title>Removed Recipes</title> + + <para> + The following recipes have been removed. + <itemizedlist> + <listitem><para> + <filename>core-image-lsb-dev</filename>: Part of removed + LSB support. + </para></listitem> + <listitem><para> + <filename>core-image-lsb</filename>: Part of removed + LSB support. + </para></listitem> + <listitem><para> + <filename>core-image-lsb-sdk</filename>: Part of removed + LSB support. + </para></listitem> + <listitem><para> + <filename>cve-check-tool</filename>: Functionally replaced + by the <filename>cve-update-db</filename> recipe and + <filename>cve-check</filename> class. + </para></listitem> + <listitem><para> + <filename>eglinfo</filename>: No longer maintained. + <filename>eglinfo</filename> from + <filename>mesa-demos</filename> is an adequate and + maintained alternative. + </para></listitem> + <listitem><para> + <filename>gcc-8.3</filename>: Version 8.3 removed. + Replaced by 9.2. + </para></listitem> + <listitem><para> + <filename>gnome-themes-standard</filename>: Only needed + by gtk+ 2.x, which has been removed. + </para></listitem> + <listitem><para> + <filename>gtk+</filename>: GTK+ 2 is obsolete and has been + replaced by gtk+3. + </para></listitem> + <listitem><para> + <filename>irda-utils</filename>: Has become obsolete. + IrDA support has been removed from the Linux kernel in + version 4.17 and later. + </para></listitem> + <listitem><para> + <filename>libnewt-python</filename>: + <filename>libnewt</filename> Python support merged into + main <filename>libnewt</filename> recipe. + </para></listitem> + <listitem><para> + <filename>libsdl</filename>: Replaced by newer + <filename>libsdl2</filename>. + </para></listitem> + <listitem><para> + <filename>libx11-diet</filename>: Became obsolete. + </para></listitem> + <listitem><para> + <filename>libxx86dga</filename>: Removed obsolete client + library. + </para></listitem> + <listitem><para> + <filename>libxx86misc</filename>: Removed. Library is + redundant. + </para></listitem> + <listitem><para> + <filename>linux-yocto</filename>: Version 5.0 removed, + which is now redundant (5.2 / 4.19 present). + </para></listitem> + <listitem><para> + <filename>lsbinitscripts</filename>: Part of removed LSB + support. + </para></listitem> + <listitem><para> + <filename>lsb</filename>: Part of removed LSB support. + </para></listitem> + <listitem><para> + <filename>lsbtest</filename>: Part of removed LSB support. + </para></listitem> + <listitem><para> + <filename>openssl10</filename>: Replaced by newer + <filename>openssl</filename> version 1.1. + </para></listitem> + <listitem><para> + <filename>packagegroup-core-lsb</filename>: Part of removed + LSB support. + </para></listitem> + <listitem><para> + <filename>python-nose</filename>: Removed the Python 2.x + version of the recipe. + </para></listitem> + <listitem><para> + <filename>python-numpy</filename>: Removed the Python 2.x + version of the recipe. + </para></listitem> + <listitem><para> + <filename>python-scons</filename>: Removed the Python 2.x + version of the recipe. + </para></listitem> + <listitem><para> + <filename>source-highlight</filename>: No longer needed. + </para></listitem> + <listitem><para> + <filename>stress</filename>: Replaced by + <filename>stress-ng</filename>. + </para></listitem> + <listitem><para> + <filename>vulkan</filename>: Split into + <filename>vulkan-loader</filename>, + <filename>vulkan-headers</filename>, and + <filename>vulkan-tools</filename>. + </para></listitem> + <listitem><para> + <filename>weston-conf</filename>: Functionality moved to + <filename>weston-init</filename>. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-3.0-packaging-changes'> + <title>Packaging Changes</title> + + <para> + The following packaging changes have occurred. + <itemizedlist> + <listitem><para> + The + <ulink url='https://en.wikipedia.org/wiki/GNOME_Web'>Epiphany</ulink> + browser has been dropped from + <filename>packagegroup-self-hosted</filename> as it has + not been needed inside + <filename>build-appliance-image</filename> for + quite some time and was causing resource problems. + </para></listitem> + <listitem><para> + <filename>libcap-ng</filename> Python support has been + moved to a separate <filename>libcap-ng-python</filename> + recipe to streamline the build process when the Python + bindings are not needed. + </para></listitem> + <listitem><para> + <filename>libdrm</filename> now packages the file + <filename>amdgpu.ids</filename> into a separate + <filename>libdrm-amdgpu</filename> package. + </para></listitem> + <listitem><para> + <filename>python3</filename>: The + <filename>runpy</filename> module is now in the + <filename>python3-core</filename> package as it is + required to support the common "python3 -m" command usage. + </para></listitem> + <listitem><para> + <filename>distcc</filename> now provides separate + <filename>distcc-client</filename> and + <filename>distcc-server</filename> packages as typically + one or the other are needed, rather than both. + </para></listitem> + <listitem><para> + <filename>python*-setuptools</filename> recipes now + separately package the <filename>pkg_resources</filename> + module in a <filename>python-pkg-resources</filename> / + <filename>python3-pkg-resources</filename> package as + the module is useful independent of the rest of the + setuptools package. + The main <filename>python-setuptools</filename> / + <filename>python3-setuptools</filename> package depends + on this new package so you should only need to update + dependencies unless you want to take advantage of the + increased granularity. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-3.0-cve-checking'> + <title>CVE Checking</title> + + <para> + <filename>cve-check-tool</filename> has been functionally replaced + by a new <filename>cve-update-db</filename> recipe and + functionality built into the <filename>cve-check</filename> class. + The result uses NVD JSON data feeds rather than the deprecated + XML feeds that <filename>cve-check-tool</filename> was using, + supports CVSSv3 scoring, and makes other improvements. + </para> + + <para> + Additionally, the <filename>CVE_CHECK_CVE_WHITELIST</filename> + variable has been replaced by + <filename>CVE_CHECK_WHITELIST</filename>. + </para> + </section> + + <section id='migration-3.0-bitbake-changes'> + <title>Bitbake Changes</title> + + <para> + The following BitBake changes have occurred. + <itemizedlist> + <listitem><para> + <filename>addtask</filename> statements now properly + validate dependent tasks. + Previously, an invalid task was silently ignored. + With this change, the invalid task generates a warning. + </para></listitem> + <listitem><para> + Other invalid <filename>addtask</filename> and + <filename>deltask</filename> usages now trigger these + warnings: "multiple target tasks arguments with + addtask / deltask", and "multiple before/after clauses". + </para></listitem> + <listitem><para> + The "multiconfig" prefix is now shortened to "mc". + "multiconfig" will continue to work, however it may be + removed in a future release. + </para></listitem> + <listitem><para> + The <filename>bitbake -g</filename> command no longer + generates a <filename>recipe-depends.dot</filename> file + as the contents (i.e. a reprocessed version of + <filename>task-depends.dot</filename>) were confusing. + </para></listitem> + <listitem><para> + The <filename>bb.build.FuncFailed</filename> exception, + previously raised by + <filename>bb.build.exec_func()</filename> when certain + other exceptions have occurred, has been removed. + The real underlying exceptions will be raised instead. + If you have calls to + <filename>bb.build.exec_func()</filename> in custom classes + or <filename>tinfoil-using</filename> scripts, any + references to <filename>bb.build.FuncFailed</filename> + should be cleaned up. + </para></listitem> + <listitem><para> + Additionally, the + <filename>bb.build.exec_func()</filename> no longer accepts + the "pythonexception" parameter. + The function now always raises exceptions. + Remove this argument in any calls to + <filename>bb.build.exec_func()</filename> in custom classes + or scripts. + </para></listitem> + <listitem><para> + The + <ulink url='&YOCTO_DOCS_BB_URL;#var-bb-BB_SETSCENE_VERIFY_FUNCTION2'><filename>BB_SETSCENE_VERIFY_FUNCTION2</filename></ulink> + is no longer used. + In the unlikely event that you have any references to it, + they should be removed. + </para></listitem> + <listitem><para> + The <filename>RunQueueExecuteScenequeue</filename> and + <filename>RunQueueExecuteTasks</filename> events have been + removed since setscene tasks are now executed as part of + the normal runqueue. + Any event handling code in custom classes or scripts that + handles these two events need to be updated. + </para></listitem> + <listitem><para> + The arguments passed to functions used with + <ulink url='&YOCTO_DOCS_BB_URL;#var-bb-BB_HASHCHECK_FUNCTION'><filename>BB_HASHCHECK_FUNCTION</filename></ulink> + have changed. + If you are using your own custom hash check function, see + <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/poky/commit/?id=40a5e193c4ba45c928fccd899415ea56b5417725'></ulink> + for details. + </para></listitem> + <listitem><para> + Task specifications in <filename>BB_TASKDEPDATA</filename> + and class implementations used in signature generator + classes now use "<fn>:<task>" everywhere rather than + the "." delimiter that was being used in some places. + This change makes it consistent with all areas in the code. + Custom signature generator classes and code that reads + <filename>BB_TASKDEPDATA</filename> need to be updated to + use ':' as a separator rather than '.'. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-3.0-sanity-checks'> + <title>Sanity Checks</title> + + <para> + The following sanity check changes occurred. + <itemizedlist> + <listitem><para> + <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link> + is now checked for usage of two problematic items: + <itemizedlist> + <listitem><para> + "${PN}" prefix/suffix use - Warnings always appear + if ${PN} is used. + You must fix the issue regardless of whether + multiconfig or anything else that would cause + prefixing/suffixing to happen. + </para></listitem> + <listitem><para> + Github archive tarballs - these are not guaranteed + to be stable. + Consequently, it is likely that the tarballs will + be refreshed and thus the SRC_URI checksums + will fail to apply. + It is recommended that you fetch either an official + release tarball or a specific revision from the + actual Git repository instead. + </para></listitem> + </itemizedlist> + Either one of these items now trigger a warning by default. + If you wish to disable this check, remove + <filename>src-uri-bad</filename> from + <link linkend='var-WARN_QA'><filename>WARN_QA</filename></link>. + </para></listitem> + <listitem><para> + The <filename>file-rdeps</filename> runtime dependency + check no longer expands + <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link> + recursively as there is no mechanism to ensure they can be + fully computed, and thus races sometimes result in errors + either showing up or not. + Thus, you might now see errors for missing runtime + dependencies that were previously satisfied recursively. + Here is an example: package A contains a shell script + starting with <filename>#!/bin/bash</filename> but has no + dependency on bash. + However, package A depends on package B, which does depend + on bash. + You need to add the missing dependency or dependencies to + resolve the warning. + </para></listitem> + <listitem><para> + Setting <filename>DEPENDS_${PN}</filename> anywhere + (i.e. typically in a recipe) now triggers an error. + The error is triggered because + <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link> + is not a package-specific variable unlike RDEPENDS. + You should set <filename>DEPENDS</filename> instead. + </para></listitem> + <listitem><para> + systemd currently does not work well with the musl C + library because only upstream officially supports linking + the library with glibc. + Thus, a warning is shown when building systemd in + conjunction with musl. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-3.0-miscellaneous-changes'> + <title>Miscellaneous Changes</title> + + <para> + The following miscellaneous changes have occurred. + <itemizedlist> + <listitem><para> + The <filename>gnome</filename> + class has been removed because it now does very little. + You should update recipes that previously inherited this + class to do the following: + <literallayout class='monospaced'> + inherit gnomebase gtk-icon-cache gconf mime + </literallayout> + </para></listitem> + <listitem><para> + The + <filename>meta/recipes-kernel/linux/linux-dtb.inc</filename> + file has been removed. + This file was previously deprecated in favor of setting + <link linkend='var-KERNEL_DEVICETREE'><filename>KERNEL_DEVICETREE</filename></link> + in any kernel recipe and only produced a warning. + Remove any <filename>include</filename> or + <filename>require</filename> statements pointing to this + file. + </para></listitem> + <listitem><para> + <link linkend='var-TARGET_CFLAGS'><filename>TARGET_CFLAGS</filename></link>, + <link linkend='var-TARGET_CPPFLAGS'><filename>TARGET_CPPFLAGS</filename></link>, + <link linkend='var-TARGET_CXXFLAGS'><filename>TARGET_CXXFLAGS</filename></link>, + and + <link linkend='var-TARGET_LDFLAGS'><filename>TARGET_LDFLAGS</filename></link> + are no longer exported to the external environment. + This change did not require any changes to core recipes, + which is a good indicator that no changes will be + required. + However, if for some reason the software being built by one + of your recipes is expecting these variables to be set, + then building the recipe will fail. + In such cases, you must either export the variable or + variables in the recipe or change the scripts so that + exporting is not necessary. + </para></listitem> + <listitem><para> + You must change the host distro identifier used in + <link linkend='var-NATIVELSBSTRING'><filename>NATIVELSBSTRING</filename></link> + to use all lowercase characters even if it does not contain + a version number. + This change is necessary only if you are not using + <filename>uninative</filename> and + <link linkend='var-SANITY_TESTED_DISTROS'><filename>SANITY_TESTED_DISTROS</filename></link>. + </para></listitem> + <listitem><para> + In the <filename>base-files</filename> recipe, writing the + hostname into <filename>/etc/hosts</filename> and + <filename>/etc/hostname</filename> is now done within the + main + <link linkend='ref-tasks-install'><filename>do_install</filename></link> + function rather than in the + <filename>do_install_basefilesissue</filename> function. + The reason for the change is because + <filename>do_install_basefilesissue</filename> is more + easily overridden without having to duplicate the hostname + functionality. + If you have done the latter (e.g. in a + <filename>base-files</filename> bbappend), then you should + remove it from your customized + <filename>do_install_basefilesissue</filename> function. + </para></listitem> + <listitem><para> + The <filename>wic --expand</filename> command now uses + commas to separate "key:value" pairs rather than hyphens. + <note> + The wic command-line help is not updated. + </note> + You must update any scripts or commands where you use + <filename>wic --expand</filename> with multiple + "key:value" pairs. + </para></listitem> + <listitem><para> + UEFI image variable settings have been moved from various + places to a central + <filename>conf/image-uefi.conf</filename>. + This change should not influence any existing configuration + as the <filename>meta/conf/image-uefi.conf</filename> + in the core metadata sets defaults that can be overridden + in the same manner as before. + </para></listitem> + <listitem><para> + <filename>conf/distro/include/world-broken.inc</filename> + has been removed. + For cases where certain recipes need to be disabled when + using the musl C library, these recipes now have + <filename>COMPATIBLE_HOST_libc-musl</filename> set with a + comment that explains why. + </para></listitem> + </itemizedlist> + </para> + </section> +</section> + + +<section id='moving-to-the-yocto-project-3.1-release'> + <title>Moving to the Yocto Project 3.1 Release</title> + + <para> + This section provides migration information for moving to the + Yocto Project 3.1 Release from the prior release. + </para> + + <section id='migration-3.1-minimum-system-requirements'> + <title>Minimum system requirements</title> + + <para> + The following versions / requirements of build host components have been updated: + <itemizedlist> + <listitem><para>gcc 5.0</para></listitem> + <listitem><para>python 3.5</para></listitem> + <listitem><para>tar 1.28</para></listitem> + <listitem><para><filename>rpcgen</filename> is now required on the host (part of the <filename>libc-dev-bin</filename> package on Ubuntu, Debian and related distributions, and the <filename>glibc</filename> package on RPM-based distributions).</para></listitem> + </itemizedlist> + + Additionally, the <filename>makeinfo</filename> and <filename>pod2man</filename> + tools are <emphasis>no longer</emphasis> required on the host. + </para> + </section> + + <section id='migration-3.1-mpc8315e-rdb-removed'> + <title>mpc8315e-rdb machine removed</title> + + <para> + The MPC8315E-RDB machine is old/obsolete and unobtainable, thus given the maintenance burden + the <filename>mpc8315e-rdb</filename> machine configuration that supported it has been removed + in this release. The removal does leave a gap in official PowerPC reference hardware + support; this may change in future if a suitable machine with accompanying support resources + is found. + </para> + </section> + + <section id='migration-3.1-python-2-removed'> + <title>Python 2 removed</title> + + <para> + Due to the expiration of upstream support in January 2020, support for Python 2 has now been removed; it is recommended that you use Python 3 instead. If absolutely needed there is a meta-python2 community layer containing Python 2, related classes and various Python 2-based modules, however it should not be considered as supported. + </para> + </section> + + <section id='migration-3.1-reproducible-builds'> + <title>Reproducible builds now enabled by default</title> + + <para> + In order to avoid unnecessary differences in output files (aiding binary reproducibility), the Poky distribution configuration (<filename><link linkend='var-DISTRO'>DISTRO</link> = "poky"</filename>) now inherits the <filename>reproducible_build</filename> class by default. + </para> + </section> + + <section id='migration-3.1-ptest-feature-impact'> + <title>Impact of ptest feature is now more significant</title> + + <para> + The Poky distribution configuration (<filename><link linkend='var-DISTRO'>DISTRO</link> = "poky"</filename>) enables ptests by default to enable runtime testing of various components. In this release, a dependency needed to be added that has resulted in a significant increase in the number of components that will be built just when building a simple image such as core-image-minimal. If you do not need runtime tests enabled for core components, then it is recommended that you remove "ptest" from <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link> to save a significant amount of build time e.g. by adding the following in your configuration: + + <literallayout class='monospaced'> + DISTRO_FEATURES_remove = "ptest" + </literallayout> + </para> + </section> + + <section id='migration-3.1-removed-recipes'> + <title>Removed recipes</title> + + <para> + The following recipes have been removed: + + <itemizedlist> + <listitem><para><filename>chkconfig</filename>: obsolete</para></listitem> + <listitem><para><filename>console-tools</filename>: obsolete</para></listitem> + <listitem><para><filename>enchant</filename>: replaced by <filename>enchant2</filename></para></listitem> + <listitem><para><filename>foomatic-filters</filename>: obsolete</para></listitem> + <listitem><para><filename>libidn</filename>: no longer needed, moved to meta-oe</para></listitem> + <listitem><para><filename>libmodulemd</filename>: replaced by <filename>libmodulemd-v1</filename></para></listitem> + <listitem><para><filename>linux-yocto</filename>: drop 4.19, 5.2 version recipes (5.4 now provided)</para></listitem> + <listitem><para><filename>nspr</filename>: no longer needed, moved to meta-oe</para></listitem> + <listitem><para><filename>nss</filename>: no longer needed, moved to meta-oe</para></listitem> + <listitem><para><filename>python</filename>: Python 2 removed (Python 3 preferred)</para></listitem> + <listitem><para><filename>python-setuptools</filename>: Python 2 version removed (python3-setuptools preferred)</para></listitem> + <listitem><para><filename>sysprof</filename>: no longer needed, moved to meta-oe</para></listitem> + <listitem><para><filename>texi2html</filename>: obsolete</para></listitem> + <listitem><para><filename>u-boot-fw-utils</filename>: functionally replaced by <filename>libubootenv</filename></para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-3.1-features-check'> + <title>features_check class replaces distro_features_check</title> + + <para> + The <filename>distro_features_check</filename> class has had its functionality expanded, now supporting <filename>ANY_OF_MACHINE_FEATURES</filename>, <filename>REQUIRED_MACHINE_FEATURES</filename>, <filename>CONFLICT_MACHINE_FEATURES</filename>, <filename>ANY_OF_COMBINED_FEATURES</filename>, <filename>REQUIRED_COMBINED_FEATURES</filename>, <filename>CONFLICT_COMBINED_FEATURES</filename>. As a result the class has now been renamed to <filename>features_check</filename>; the <filename>distro_features_check</filename> class still exists but generates a warning and redirects to the new class. In preparation for a future removal of the old class it is recommended that you update recipes currently inheriting <filename>distro_features_check</filename> to inherit <filename>features_check</filename> instead. + </para> + </section> + + <section id='migration-3.1-removed-classes'> + <title>Removed classes</title> + + <para> + The following classes have been removed: + + <itemizedlist> + <listitem><para><filename>distutils-base</filename>: moved to meta-python2</para></listitem> + <listitem><para><filename>distutils</filename>: moved to meta-python2</para></listitem> + <listitem><para><filename>libc-common</filename>: merged into the glibc recipe as nothing else used it.</para></listitem> + <listitem><para><filename>python-dir</filename>: moved to meta-python2</para></listitem> + <listitem><para><filename>pythonnative</filename>: moved to meta-python2</para></listitem> + <listitem><para><filename>setuptools</filename>: moved to meta-python2</para></listitem> + <listitem><para><filename>tinderclient</filename>: dropped as it was obsolete.</para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-3.1-src-uri-checksums'> + <title>SRC_URI checksum behaviour</title> + + <para> + Previously, recipes by tradition included both SHA256 and MD5 checksums for remotely fetched files in <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>, even though only one is actually mandated. However, the MD5 checksum does not add much given its inherent weakness; thus when a checksum fails only the SHA256 sum will now be printed. The md5sum will still be verified if it is specified. + </para> + </section> + + + <section id='migration-3.1-npm'> + <title>npm fetcher changes</title> + + <para> + The npm fetcher has been completely reworked in this release. The npm fetcher now only fetches the package source itself and no longer the dependencies; there is now also an npmsw fetcher which explicitly fetches the shrinkwrap file and the dependencies. This removes the slightly awkward <filename>NPM_LOCKDOWN</filename> and <filename>NPM_SHRINKWRAP</filename> variables which pointed to local files; the lockdown file is no longer needed at all. Additionally, the package name in <filename>npm://</filename> entries in <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link> is now specified using a <filename>package</filename> parameter instead of the earlier <filename>name</filename> which overlapped with the generic <filename>name</filename> parameter. All recipes using the npm fetcher will need to be changed as a result. + </para> + <para> + An example of the new scheme: + <literallayout class='monospaced'> +SRC_URI = "npm://registry.npmjs.org;package=array-flatten;version=1.1.1 \ + npmsw://${THISDIR}/npm-shrinkwrap.json" + </literallayout> + Another example where the sources are fetched from git rather than an npm repository: + <literallayout class='monospaced'> +SRC_URI = "git://github.com/foo/bar.git;protocol=https \ + npmsw://${THISDIR}/npm-shrinkwrap.json" + </literallayout> + </para> + <para> + devtool and recipetool have also been updated to match with the npm fetcher changes. Other than producing working and more complete recipes for npm sources, there is also a minor change to the command line for devtool: the <filename>--fetch-dev</filename> option has been renamed to <filename>--npm-dev</filename> as it is npm-specific. + </para> + </section> + + + <section id='migration-3.1-packaging-changes'> + <title>Packaging changes</title> + + <para> + <itemizedlist> + <listitem><para><filename>intltool</filename> has been removed from <filename>packagegroup-core-sdk</filename> as it is rarely needed to build modern software - gettext can do most of the things it used to be needed for. <filename>intltool</filename> has also been removed from <filename>packagegroup-core-self-hosted</filename> as it is not needed to for standard builds.</para></listitem> + <listitem><para>git: <filename>git-am</filename>, <filename>git-difftool</filename>, <filename>git-submodule</filename>, and <filename>git-request-pull</filename> are no longer perl-based, so are now installed with the main <filename>git</filename> package instead of within <filename>git-perltools</filename>.</para></listitem> + <listitem><para>The <filename>ldconfig</filename> binary built as part of glibc has now been moved to its own <filename>ldconfig</filename> package (note no <filename>glibc-</filename> prefix). This package is in the <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link> of the main <filename>glibc</filename> package if <filename>ldconfig</filename> is present in <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>.</para></listitem> + <listitem><para><filename>libevent</filename> now splits each shared library into its own package (as Debian does). Since these are shared libraries and will be pulled in through the normal shared library dependency handling, there should be no impact to existing configurations other than less unnecessary libraries being installed in some cases.</para></listitem> + <listitem><para>linux-firmware now has a new package for <filename>bcm4366c</filename> and includes available NVRAM config files into the <filename>bcm43340</filename>, <filename>bcm43362</filename>, <filename>bcm43430</filename> and <filename>bcm4356-pcie</filename> packages.</para></listitem> + <listitem><para><filename>harfbuzz</filename> now splits the new <filename>libharfbuzz-subset.so</filename> library into its own package to reduce the main package size in cases where <filename>libharfbuzz-subset.so</filename> is not needed.</para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-3.1-package-qa-warnings'> + <title>Additional warnings</title> + + <para> + Warnings will now be shown at <filename>do_package_qa</filename> time in the following circumstances: + + <itemizedlist> + <listitem><para>A recipe installs <filename>.desktop</filename> files containing <filename>MimeType</filename> keys but does not inherit the new <filename>mime-xdg</filename> class</para></listitem> + <listitem><para>A recipe installs <filename>.xml</filename> files into <filename>${datadir}/mime/packages</filename> but does not inherit the <filename>mime</filename> class</para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-3.1-x86-live-wic'> + <title><filename>wic</filename> image type now used instead of <filename>live</filename> by default for x86</title> + + <para> + <filename>conf/machine/include/x86-base.inc</filename> (inherited by most x86 machine configurations) now specifies <filename>wic</filename> instead of <filename>live</filename> by default in <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>. The <filename>live</filename> image type will likely be removed in a future release so it is recommended that you use <filename>wic</filename> instead. + </para> + </section> + + <section id='migration-3.1-misc'> + <title>Miscellaneous changes</title> + + <para> + <itemizedlist> + <listitem><para>The undocumented <filename>SRC_DISTRIBUTE_LICENSES</filename> variable has now been removed in favour of a new <filename>AVAILABLE_LICENSES</filename> variable which is dynamically set based upon license files found in <filename>${COMMON_LICENSE_DIR}</filename> and <filename>${LICENSE_PATH}</filename>.</para></listitem> + <listitem><para>The tune definition for big-endian microblaze machines is now <filename>microblaze</filename> instead of <filename>microblazeeb</filename>.</para></listitem> + <listitem><para><filename>newlib</filename> no longer has built-in syscalls. <filename>libgloss</filename> should then provide the syscalls, <filename>crt0.o</filename> and other functions that are no longer part of <filename>newlib</filename> itself. If you are using <filename>TCLIBC = "newlib"</filename> this now means that you must link applications with both <filename>newlib</filename> and <filename>libgloss</filename>, whereas before <filename>newlib</filename> would run in many configurations by itself.</para></listitem> + </itemizedlist> + </para> + </section> + +</section> + + </chapter> <!-- vim: expandtab tw=80 ts=4 |