diff options
Diffstat (limited to 'documentation/migration-guides/migration-3.2.rst')
| -rw-r--r-- | documentation/migration-guides/migration-3.2.rst | 340 |
1 files changed, 340 insertions, 0 deletions
diff --git a/documentation/migration-guides/migration-3.2.rst b/documentation/migration-guides/migration-3.2.rst new file mode 100644 index 0000000000..c538df04d2 --- /dev/null +++ b/documentation/migration-guides/migration-3.2.rst @@ -0,0 +1,340 @@ +.. SPDX-License-Identifier: CC-BY-SA-2.0-UK + +Release 3.2 (gatesgarth) +======================== + +This section provides migration information for moving to the Yocto +Project 3.2 Release (codename "gatesgarth") from the prior release. + +.. _migration-3.2-minimum-system-requirements: + +Minimum system requirements +--------------------------- + +``gcc`` version 6.0 is now required at minimum on the build host. For older +host distributions where this is not available, you can use the +:term:`buildtools-extended` tarball (easily installable using +``scripts/install-buildtools``). + + +.. _migration-3.2-removed-recipes: + +Removed recipes +--------------- + +The following recipes have been removed: + +- ``bjam-native``: replaced by ``boost-build-native`` +- ``avahi-ui``: folded into the main ``avahi`` recipe --- the GTK UI can be disabled using :term:`PACKAGECONFIG` for ``avahi``. +- ``build-compare``: no longer needed with the removal of the ``packagefeed-stability`` class +- ``dhcp``: obsolete, functionally replaced by ``dhcpcd`` and ``kea`` +- ``libmodulemd-v1``: replaced by ``libmodulemd`` +- ``packagegroup-core-device-devel``: obsolete + + +.. _migration-3.2-removed-classes: + +Removed classes +--------------- + +The following classes (.bbclass files) have been removed: + +- ``spdx``: obsolete --- the Yocto Project is a strong supporter of SPDX, but this class was old code using a dated approach and had the potential to be misleading. The ``meta-sdpxscanner`` layer is a much more modern and active approach to handling this and is recommended as a replacement. + +- ``packagefeed-stability``: this class had become obsolete with the advent of hash equivalence and reproducible builds. + + +pseudo path filtering and mismatch behaviour +-------------------------------------------- + +pseudo now operates on a filtered subset of files. This is a significant change +to the way pseudo operates within OpenEmbedded --- by default, pseudo monitors and +logs (adds to its database) any file created or modified whilst in a ``fakeroot`` +environment. However, there are large numbers of files that we simply don't care +about the permissions of whilst in that ``fakeroot`` context, for example ${:term:`S`}, ${:term:`B`}, ${:term:`T`}, +${:term:`SSTATE_DIR`}, the central sstate control directories, and others. + +As of this release, new functionality in pseudo is enabled to ignore these +directory trees (controlled using a new :term:`PSEUDO_IGNORE_PATHS` variable) +resulting in a cleaner database with less chance of "stray" mismatches if files +are modified outside pseudo context. It also should reduce some overhead from +pseudo as the interprocess round trip to the server is avoided. + +There is a possible complication where some existing recipe may break, for +example, a recipe was found to be writing to ``${B}/install`` for +``make install`` in :ref:`ref-tasks-install` and since ``${B}`` is listed as not to be tracked, +there were errors trying to ``chown root`` for files in this location. Another +example was the ``tcl`` recipe where the source directory :term:`S` is set to a +subdirectory of the source tree but files were written out to the directory +structure above that subdirectory. For these types of cases in your own recipes, +extend :term:`PSEUDO_IGNORE_PATHS` to cover additional paths that pseudo should not +be monitoring. + +In addition, pseudo's behaviour on mismatches has now been changed --- rather +than doing what turns out to be a rather dangerous "fixup" if it sees a file +with a different path but the same inode as another file it has previously seen, +pseudo will throw an ``abort()`` and direct you to a :yocto_wiki:`wiki page </Pseudo_Abort>` +that explains how to deal with this. + + +.. _migration-3.2-multilib-mlprefix: + +``MLPREFIX`` now required for multilib when runtime dependencies conditionally added +------------------------------------------------------------------------------------ + +In order to solve some previously intractable problems with runtime +dependencies and multilib, a change was made that now requires the :term:`MLPREFIX` +value to be explicitly prepended to package names being added as +dependencies (e.g. in :term:`RDEPENDS` and :term:`RRECOMMENDS` values) +where the dependency is conditionally added. + +If you have anonymous Python or in-line Python conditionally adding +dependencies in your custom recipes, and you intend for those recipes to +work with multilib, then you will need to ensure that ``${MLPREFIX}`` +is prefixed on the package names in the dependencies, for example +(from the ``glibc`` recipe):: + + RRECOMMENDS_${PN} = "${@bb.utils.contains('DISTRO_FEATURES', 'ldconfig', '${MLPREFIX}ldconfig', '', d)}" + +This also applies when conditionally adding packages to :term:`PACKAGES` where +those packages have dependencies, for example (from the ``alsa-plugins`` recipe):: + + PACKAGES += "${@bb.utils.contains('PACKAGECONFIG', 'pulseaudio', 'alsa-plugins-pulseaudio-conf', '', d)}" + ... + RDEPENDS_${PN}-pulseaudio-conf += "\ + ${MLPREFIX}libasound-module-conf-pulse \ + ${MLPREFIX}libasound-module-ctl-pulse \ + ${MLPREFIX}libasound-module-pcm-pulse \ + " + + +.. _migration-3.2-packagegroup-core-device-devel: + +packagegroup-core-device-devel no longer included in images built for qemu* machines +------------------------------------------------------------------------------------ + +``packagegroup-core-device-devel`` was previously added automatically to +images built for ``qemu*`` machines, however the purpose of the group and what +it should contain is no longer clear, and in general, adding userspace +development items to images is best done at the image/class level; thus this +packagegroup was removed. + +This packagegroup previously pulled in the following: + +- ``distcc-config`` +- ``nfs-export-root`` +- ``bash`` +- ``binutils-symlinks`` + +If you still need any of these in your image built for a ``qemu*`` machine +then you will add them explicitly to :term:`IMAGE_INSTALL` or another +appropriate place in the dependency chain for your image (if you have not +already done so). + + +.. _migration-3.2-dhcp: + +DHCP server/client replaced +--------------------------- + +The ``dhcp`` software package has become unmaintained and thus has been +functionally replaced by ``dhcpcd`` (client) and ``kea`` (server). You will +need to replace references to the recipe/package names as appropriate --- most +commonly, at the package level ``dhcp-client`` should be replaced by +``dhcpcd`` and ``dhcp-server`` should be replaced by ``kea``. If you have any +custom configuration files for these they will need to be adapted --- refer to +the upstream documentation for ``dhcpcd`` and ``kea`` for further details. + + +.. _migration-3.2-packaging-changes: + +Packaging changes +----------------- + +- ``python3``: the ``urllib`` Python package has now moved into the core package, as it is used more commonly than just netclient (e.g. email, xml, mimetypes, pydoc). In addition, the ``pathlib`` module is now also part of the core package. + +- ``iptables``: ``iptables-apply`` and ``ip6tables-apply`` have been split out to their own package to avoid a bash dependency in the main ``iptables`` package + + +.. _migration-3.2-package-qa-checks: + +Package QA check changes +------------------------ + +Previously, the following package QA checks triggered warnings, however they can +be indicators of genuine underlying problems and are therefore now treated as +errors: + +- :ref:`already-stripped <qa-check-already-stripped>` +- :ref:`compile-host-path <qa-check-compile-host-path>` +- :ref:`installed-vs-shipped <qa-check-installed-vs-shipped>` +- :ref:`ldflags <qa-check-ldflags>` +- :ref:`pn-overrides <qa-check-pn-overrides>` +- :ref:`rpaths <qa-check-rpaths>` +- :ref:`staticdev <qa-check-staticdev>` +- :ref:`unknown-configure-option <qa-check-unknown-configure-option>` +- :ref:`useless-rpaths <qa-check-useless-rpaths>` + +In addition, the following new checks were added and default to triggering an error: + +- :ref:`shebang-size <qa-check-shebang-size>`: Check for shebang (#!) lines + longer than 128 characters, which can give an error at runtime depending on + the operating system. + +- :ref:`unhandled-features-check <qa-check-unhandled-features-check>`: Check + if any of the variables supported by the :ref:`ref-classes-features_check` + class is set while not inheriting the class itself. + +- :ref:`missing-update-alternatives <qa-check-missing-update-alternatives>`: + Check if the recipe sets the :term:`ALTERNATIVE` variable for any of its + packages, and does not inherit the :ref:`ref-classes-update-alternatives` + class. + +- A trailing slash or duplicated slashes in the value of :term:`S` or :term:`B` + will now trigger a warning so that they can be removed and path comparisons + can be more reliable --- remove any instances of these in your recipes if the + warning is displayed. + + +.. _migration-3.2-src-uri-file-globbing: + +Globbing no longer supported in ``file://`` entries in ``SRC_URI`` +------------------------------------------------------------------ + +Globbing (``*`` and ``?`` wildcards) in ``file://`` URLs within :term:`SRC_URI` +did not properly support file checksums, thus changes to the source files +would not always change the :ref:`ref-tasks-fetch` task checksum, and consequently would +not ensure that the changed files would be incorporated in subsequent builds. + +Unfortunately it is not practical to make globbing work generically here, so +the decision was taken to remove support for globs in ``file://`` URLs. +If you have any usage of these in your recipes, then you will now need to +either add each of the files that you expect to match explicitly, or +alternatively if you still need files to be pulled in dynamically, put the +files into a subdirectory and reference that instead. + + +.. _migration-3.2-deploydir-clean: + +deploy class now cleans ``DEPLOYDIR`` before ``do_deploy`` +---------------------------------------------------------- + +:ref:`ref-tasks-deploy` as implemented in the :ref:`ref-classes-deploy` class +now cleans up ${:term:`DEPLOYDIR`} before running, just as +:ref:`ref-tasks-install` cleans up ${:term:`D`} before running. This reduces +the risk of :term:`DEPLOYDIR` being accidentally contaminated by files from +previous runs, possibly even with different config, in case of incremental +builds. + +Most recipes and classes that inherit the :ref:`ref-classes-deploy` class or +interact with :ref:`ref-tasks-deploy` are unlikely to be affected by this +unless they add ``prefuncs`` to :ref:`ref-tasks-deploy` *which also* put files +into ``${DEPLOYDIR}`` --- these should be refactored to use +``do_deploy_prepend`` instead. + + +.. _migration-3.2-nativesdk-sdk-provides-dummy: + +Custom SDK / SDK-style recipes need to include ``nativesdk-sdk-provides-dummy`` +------------------------------------------------------------------------------- + +All :ref:`ref-classes-nativesdk` packages require ``/bin/sh`` due +to their postinstall scriptlets, thus this package has to be dummy-provided +within the SDK and ``nativesdk-sdk-provides-dummy`` now does this. If you have +a custom SDK recipe (or your own SDK-style recipe similar to e.g. +``buildtools-tarball``), you will need to ensure +``nativesdk-sdk-provides-dummy`` or an equivalent is included in +:term:`TOOLCHAIN_HOST_TASK`. + + +``ld.so.conf`` now moved back to main ``glibc`` package +------------------------------------------------------- + +There are cases where one doesn't want ``ldconfig`` on target (e.g. for +read-only root filesystems, it's rather pointless), yet one still +needs ``/etc/ld.so.conf`` to be present at image build time: + +When some recipe installs libraries to a non-standard location, and +therefore installs in a file in ``/etc/ld.so.conf.d/foo.conf``, we +need ``/etc/ld.so.conf`` containing:: + + include /etc/ld.so.conf.d/*.conf + +in order to get those other locations picked up. + +Thus ``/etc/ld.so.conf`` is now in the main ``glibc`` package so that +there's always an ``ld.so.conf`` present when the build-time ``ldconfig`` +runs towards the end of image construction. + +The ``ld.so.conf`` and ``ld.so.conf.d/*.conf`` files do not take up +significant space (at least not compared to the ~700kB ``ldconfig`` binary), and they +might be needed in case ``ldconfig`` is installable, so they are left +in place after the image is built. Technically it would be possible to +remove them if desired, though it would not be trivial if you still +wanted the build-time ldconfig to function (:term:`ROOTFS_POSTPROCESS_COMMAND` +will not work as ``ldconfig`` is run after the functions referred to +by that variable). + + +.. _migration-3.2-virgl: + +Host DRI drivers now used for GL support within ``runqemu`` +----------------------------------------------------------- + +``runqemu`` now uses the mesa-native libraries everywhere virgl is used +(i.e. when ``gl``, ``gl-es`` or ``egl-headless`` options are specified), +but instructs them to load DRI drivers from the host. Unfortunately this +may not work well with proprietary graphics drivers such as those from +Nvidia; if you are using such drivers then you may need to switch to an +alternative (such as Nouveau in the case of Nvidia hardware) or avoid +using the GL options. + + +.. _migration-3.2-initramfs-suffix: + +Initramfs images now use a blank suffix +--------------------------------------- + +The reference :term:`Initramfs` images (``core-image-minimal-initramfs``, +``core-image-tiny-initramfs`` and ``core-image-testmaster-initramfs``) now +set an empty string for :term:`IMAGE_NAME_SUFFIX`, which otherwise defaults +to ``".rootfs"``. These images aren't root filesystems and thus the rootfs +label didn't make sense. If you are looking for the output files generated +by these image recipes directly then you will need to adapt to the new +naming without the ``.rootfs`` part. + + +.. _migration-3.2-image-artifact-names: + +Image artifact name variables now centralised in image-artifact-names class +--------------------------------------------------------------------------- + +The defaults for the following image artifact name variables have been moved +from ``bitbake.conf`` to a new ``image-artifact-names`` class: + +- :term:`IMAGE_BASENAME` +- :term:`IMAGE_LINK_NAME` +- :term:`IMAGE_NAME` +- :term:`IMAGE_NAME_SUFFIX` +- :term:`IMAGE_VERSION_SUFFIX` + +Image-related classes now inherit this class, and typically these variables +are only referenced within image recipes so those will be unaffected by this +change. However if you have references to these variables in either a recipe +that is not an image or a class that is enabled globally, then those will +now need to be changed to ``inherit image-artifact-names``. + + +.. _migration-3.2-misc: + +Miscellaneous changes +--------------------- + +- Support for the long-deprecated ``PACKAGE_GROUP`` variable has now been removed --- replace any remaining instances with :term:`FEATURE_PACKAGES`. +- The ``FILESPATHPKG`` variable, having been previously deprecated, has now been removed. Replace any remaining references with appropriate use of :term:`FILESEXTRAPATHS`. +- Erroneous use of ``inherit +=`` (instead of ``INHERIT +=``) in a configuration file now triggers an error instead of silently being ignored. +- ptest support has been removed from the ``kbd`` recipe, as upstream has moved to autotest which is difficult to work with in a cross-compilation environment. +- ``oe.utils.is_machine_specific()`` and ``oe.utils.machine_paths()`` have been removed as their utility was questionable. In the unlikely event that you have references to these in your own code, then the code will need to be reworked. +- The ``i2ctransfer`` module is now disabled by default when building ``busybox`` in order to be consistent with disabling the other i2c tools there. If you do wish the i2ctransfer module to be built in BusyBox then add ``CONFIG_I2CTRANSFER=y`` to your custom BusyBox configuration. +- In the ``Upstream-Status`` header convention for patches, ``Accepted`` has been replaced with ``Backport`` as these almost always mean the same thing i.e. the patch is already upstream and may need to be removed in a future recipe upgrade. If you are adding these headers to your own patches then use ``Backport`` to indicate that the patch has been sent upstream. +- The ``tune-supersparc.inc`` tune file has been removed as it does not appear to be widely used and no longer works. |