blob: a714bd6bcaab5386278b36762fd51ec853c62dbd [file] [log] [blame]
Andrew Geissler09036742021-06-25 14:25:14 -05001Release 3.2 (gatesgarth)
2========================
Andrew Geissler6ce62a22020-11-30 19:58:47 -06003
4This section provides migration information for moving to the Yocto
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05005Project 3.2 Release (codename "gatesgarth") from the prior release.
Andrew Geissler6ce62a22020-11-30 19:58:47 -06006
7.. _migration-3.2-minimum-system-requirements:
8
9Minimum system requirements
10---------------------------
11
12``gcc`` version 6.0 is now required at minimum on the build host. For older
13host distributions where this is not available, you can use the
14``buildtools-extended-tarball`` (easily installable using
15``scripts/install-buildtools``).
16
17
18.. _migration-3.2-removed-recipes:
19
20Removed recipes
21---------------
22
23The following recipes have been removed:
24
25- ``bjam-native``: replaced by ``boost-build-native``
Andrew Geissler615f2f12022-07-15 14:00:58 -050026- ``avahi-ui``: folded into the main ``avahi`` recipe --- the GTK UI can be disabled using :term:`PACKAGECONFIG` for ``avahi``.
Andrew Geissler6ce62a22020-11-30 19:58:47 -060027- ``build-compare``: no longer needed with the removal of the ``packagefeed-stability`` class
28- ``dhcp``: obsolete, functionally replaced by ``dhcpcd`` and ``kea``
29- ``libmodulemd-v1``: replaced by ``libmodulemd``
30- ``packagegroup-core-device-devel``: obsolete
31
32
33.. _migration-3.2-removed-classes:
34
35Removed classes
36---------------
37
38The following classes (.bbclass files) have been removed:
39
Andrew Geissler615f2f12022-07-15 14:00:58 -050040- ``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.
Andrew Geissler6ce62a22020-11-30 19:58:47 -060041
42- ``packagefeed-stability``: this class had become obsolete with the advent of hash equivalence and reproducible builds.
43
44
45pseudo path filtering and mismatch behaviour
46--------------------------------------------
47
48pseudo now operates on a filtered subset of files. This is a significant change
Andrew Geissler615f2f12022-07-15 14:00:58 -050049to the way pseudo operates within OpenEmbedded --- by default, pseudo monitors and
Andrew Geissler6ce62a22020-11-30 19:58:47 -060050logs (adds to its database) any file created or modified whilst in a ``fakeroot``
51environment. However, there are large numbers of files that we simply don't care
52about the permissions of whilst in that ``fakeroot`` context, for example ${:term:`S`}, ${:term:`B`}, ${:term:`T`},
53${:term:`SSTATE_DIR`}, the central sstate control directories, and others.
54
55As of this release, new functionality in pseudo is enabled to ignore these
56directory trees (controlled using a new :term:`PSEUDO_IGNORE_PATHS` variable)
57resulting in a cleaner database with less chance of "stray" mismatches if files
58are modified outside pseudo context. It also should reduce some overhead from
59pseudo as the interprocess round trip to the server is avoided.
60
61There is a possible complication where some existing recipe may break, for
62example, a recipe was found to be writing to ``${B}/install`` for
Patrick Williams2194f502022-10-16 14:26:09 -050063``make install`` in :ref:`ref-tasks-install` and since ``${B}`` is listed as not to be tracked,
Andrew Geissler6ce62a22020-11-30 19:58:47 -060064there were errors trying to ``chown root`` for files in this location. Another
Andrew Geissler09036742021-06-25 14:25:14 -050065example was the ``tcl`` recipe where the source directory :term:`S` is set to a
Andrew Geissler6ce62a22020-11-30 19:58:47 -060066subdirectory of the source tree but files were written out to the directory
67structure above that subdirectory. For these types of cases in your own recipes,
Andrew Geissler09036742021-06-25 14:25:14 -050068extend :term:`PSEUDO_IGNORE_PATHS` to cover additional paths that pseudo should not
Andrew Geissler6ce62a22020-11-30 19:58:47 -060069be monitoring.
70
Andrew Geissler615f2f12022-07-15 14:00:58 -050071In addition, pseudo's behaviour on mismatches has now been changed --- rather
Andrew Geissler6ce62a22020-11-30 19:58:47 -060072than doing what turns out to be a rather dangerous "fixup" if it sees a file
73with a different path but the same inode as another file it has previously seen,
Andrew Geissler09209ee2020-12-13 08:44:15 -060074pseudo will throw an ``abort()`` and direct you to a :yocto_wiki:`wiki page </Pseudo_Abort>`
Andrew Geissler6ce62a22020-11-30 19:58:47 -060075that explains how to deal with this.
76
77
78.. _migration-3.2-multilib-mlprefix:
79
80``MLPREFIX`` now required for multilib when runtime dependencies conditionally added
81------------------------------------------------------------------------------------
82
83In order to solve some previously intractable problems with runtime
84dependencies and multilib, a change was made that now requires the :term:`MLPREFIX`
85value to be explicitly prepended to package names being added as
86dependencies (e.g. in :term:`RDEPENDS` and :term:`RRECOMMENDS` values)
87where the dependency is conditionally added.
88
Andrew Geisslerd5838332022-05-27 11:33:10 -050089If you have anonymous Python or in-line Python conditionally adding
Andrew Geissler6ce62a22020-11-30 19:58:47 -060090dependencies in your custom recipes, and you intend for those recipes to
91work with multilib, then you will need to ensure that ``${MLPREFIX}``
92is prefixed on the package names in the dependencies, for example
Andrew Geisslerc926e172021-05-07 16:11:35 -050093(from the ``glibc`` recipe)::
Andrew Geissler6ce62a22020-11-30 19:58:47 -060094
95 RRECOMMENDS_${PN} = "${@bb.utils.contains('DISTRO_FEATURES', 'ldconfig', '${MLPREFIX}ldconfig', '', d)}"
96
97This also applies when conditionally adding packages to :term:`PACKAGES` where
Andrew Geisslerc926e172021-05-07 16:11:35 -050098those packages have dependencies, for example (from the ``alsa-plugins`` recipe)::
Andrew Geissler6ce62a22020-11-30 19:58:47 -060099
100 PACKAGES += "${@bb.utils.contains('PACKAGECONFIG', 'pulseaudio', 'alsa-plugins-pulseaudio-conf', '', d)}"
101 ...
102 RDEPENDS_${PN}-pulseaudio-conf += "\
103 ${MLPREFIX}libasound-module-conf-pulse \
104 ${MLPREFIX}libasound-module-ctl-pulse \
105 ${MLPREFIX}libasound-module-pcm-pulse \
106 "
107
108
109.. _migration-3.2-packagegroup-core-device-devel:
110
111packagegroup-core-device-devel no longer included in images built for qemu* machines
112------------------------------------------------------------------------------------
113
114``packagegroup-core-device-devel`` was previously added automatically to
115images built for ``qemu*`` machines, however the purpose of the group and what
116it should contain is no longer clear, and in general, adding userspace
117development items to images is best done at the image/class level; thus this
118packagegroup was removed.
119
120This packagegroup previously pulled in the following:
121
122- ``distcc-config``
123- ``nfs-export-root``
124- ``bash``
125- ``binutils-symlinks``
126
127If you still need any of these in your image built for a ``qemu*`` machine
128then you will add them explicitly to :term:`IMAGE_INSTALL` or another
129appropriate place in the dependency chain for your image (if you have not
130already done so).
131
132
133.. _migration-3.2-dhcp:
134
135DHCP server/client replaced
136---------------------------
137
138The ``dhcp`` software package has become unmaintained and thus has been
139functionally replaced by ``dhcpcd`` (client) and ``kea`` (server). You will
Andrew Geissler615f2f12022-07-15 14:00:58 -0500140need to replace references to the recipe/package names as appropriate --- most
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600141commonly, at the package level ``dhcp-client`` should be replaced by
142``dhcpcd`` and ``dhcp-server`` should be replaced by ``kea``. If you have any
Andrew Geissler615f2f12022-07-15 14:00:58 -0500143custom configuration files for these they will need to be adapted --- refer to
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600144the upstream documentation for ``dhcpcd`` and ``kea`` for further details.
145
146
147.. _migration-3.2-packaging-changes:
148
149Packaging changes
150-----------------
151
Andrew Geisslerd5838332022-05-27 11:33:10 -0500152- ``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.
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600153
154- ``iptables``: ``iptables-apply`` and ``ip6tables-apply`` have been split out to their own package to avoid a bash dependency in the main ``iptables`` package
155
156
157.. _migration-3.2-package-qa-checks:
158
159Package QA check changes
160------------------------
161
162Previously, the following package QA checks triggered warnings, however they can
163be indicators of genuine underlying problems and are therefore now treated as
164errors:
165
166- :ref:`already-stripped <qa-check-already-stripped>`
167- :ref:`compile-host-path <qa-check-compile-host-path>`
168- :ref:`installed-vs-shipped <qa-check-installed-vs-shipped>`
169- :ref:`ldflags <qa-check-ldflags>`
170- :ref:`pn-overrides <qa-check-pn-overrides>`
171- :ref:`rpaths <qa-check-rpaths>`
172- :ref:`staticdev <qa-check-staticdev>`
173- :ref:`unknown-configure-option <qa-check-unknown-configure-option>`
174- :ref:`useless-rpaths <qa-check-useless-rpaths>`
175
176In addition, the following new checks were added and default to triggering an error:
177
178- :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.
179
180- :ref:`unhandled-features-check <qa-check-unhandled-features-check>`: Check if any of the variables supported by the :ref:`features_check <ref-classes-features_check>` class is set while not inheriting the class itself.
181
182- :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:`update-alternatives <ref-classes-update-alternatives>` class.
183
Andrew Geissler615f2f12022-07-15 14:00:58 -0500184- 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.
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600185
186
187.. _migration-3.2-src-uri-file-globbing:
188
189Globbing no longer supported in ``file://`` entries in ``SRC_URI``
190------------------------------------------------------------------
191
192Globbing (``*`` and ``?`` wildcards) in ``file://`` URLs within :term:`SRC_URI`
193did not properly support file checksums, thus changes to the source files
Patrick Williams2194f502022-10-16 14:26:09 -0500194would not always change the :ref:`ref-tasks-fetch` task checksum, and consequently would
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600195not ensure that the changed files would be incorporated in subsequent builds.
196
197Unfortunately it is not practical to make globbing work generically here, so
198the decision was taken to remove support for globs in ``file://`` URLs.
199If you have any usage of these in your recipes, then you will now need to
200either add each of the files that you expect to match explicitly, or
201alternatively if you still need files to be pulled in dynamically, put the
202files into a subdirectory and reference that instead.
203
204
205.. _migration-3.2-deploydir-clean:
206
207deploy class now cleans ``DEPLOYDIR`` before ``do_deploy``
208----------------------------------------------------------
209
Patrick Williams2194f502022-10-16 14:26:09 -0500210:ref:`ref-tasks-deploy` as implemented in the :ref:`deploy <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.
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600211
Patrick Williams2194f502022-10-16 14:26:09 -0500212Most recipes and classes that inherit the :ref:`deploy <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.
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600213
214
215.. _migration-3.2-nativesdk-sdk-provides-dummy:
216
217Custom SDK / SDK-style recipes need to include ``nativesdk-sdk-provides-dummy``
218-------------------------------------------------------------------------------
219
220All ``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`.
221
222
223``ld.so.conf`` now moved back to main ``glibc`` package
224-------------------------------------------------------
225
226There are cases where one doesn't want ``ldconfig`` on target (e.g. for
227read-only root filesystems, it's rather pointless), yet one still
228needs ``/etc/ld.so.conf`` to be present at image build time:
229
230When some recipe installs libraries to a non-standard location, and
231therefore installs in a file in ``/etc/ld.so.conf.d/foo.conf``, we
Andrew Geisslerc926e172021-05-07 16:11:35 -0500232need ``/etc/ld.so.conf`` containing::
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600233
234 include /etc/ld.so.conf.d/*.conf
235
236in order to get those other locations picked up.
237
238Thus ``/etc/ld.so.conf`` is now in the main ``glibc`` package so that
239there's always an ``ld.so.conf`` present when the build-time ``ldconfig``
240runs towards the end of image construction.
241
242The ``ld.so.conf`` and ``ld.so.conf.d/*.conf`` files do not take up
243significant space (at least not compared to the ~700kB ``ldconfig`` binary), and they
244might be needed in case ``ldconfig`` is installable, so they are left
245in place after the image is built. Technically it would be possible to
246remove them if desired, though it would not be trivial if you still
247wanted the build-time ldconfig to function (:term:`ROOTFS_POSTPROCESS_COMMAND`
248will not work as ``ldconfig`` is run after the functions referred to
249by that variable).
250
251
252.. _migration-3.2-virgl:
253
254Host DRI drivers now used for GL support within ``runqemu``
255-----------------------------------------------------------
256
257``runqemu`` now uses the mesa-native libraries everywhere virgl is used
258(i.e. when ``gl``, ``gl-es`` or ``egl-headless`` options are specified),
259but instructs them to load DRI drivers from the host. Unfortunately this
260may not work well with proprietary graphics drivers such as those from
261Nvidia; if you are using such drivers then you may need to switch to an
262alternative (such as Nouveau in the case of Nvidia hardware) or avoid
263using the GL options.
264
265
266.. _migration-3.2-initramfs-suffix:
267
Patrick Williams2194f502022-10-16 14:26:09 -0500268Initramfs images now use a blank suffix
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600269---------------------------------------
270
Patrick Williams2194f502022-10-16 14:26:09 -0500271The reference :term:`Initramfs` images (``core-image-minimal-initramfs``,
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600272``core-image-tiny-initramfs`` and ``core-image-testmaster-initramfs``) now
273set an empty string for :term:`IMAGE_NAME_SUFFIX`, which otherwise defaults
274to ``".rootfs"``. These images aren't root filesystems and thus the rootfs
275label didn't make sense. If you are looking for the output files generated
276by these image recipes directly then you will need to adapt to the new
277naming without the ``.rootfs`` part.
278
279
280.. _migration-3.2-image-artifact-names:
281
282Image artifact name variables now centralised in image-artifact-names class
283---------------------------------------------------------------------------
284
285The defaults for the following image artifact name variables have been moved
Andrew Geisslerd5838332022-05-27 11:33:10 -0500286from ``bitbake.conf`` to a new ``image-artifact-names`` class:
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600287
288- :term:`IMAGE_BASENAME`
289- :term:`IMAGE_LINK_NAME`
290- :term:`IMAGE_NAME`
291- :term:`IMAGE_NAME_SUFFIX`
292- :term:`IMAGE_VERSION_SUFFIX`
293
294Image-related classes now inherit this class, and typically these variables
295are only referenced within image recipes so those will be unaffected by this
296change. However if you have references to these variables in either a recipe
297that is not an image or a class that is enabled globally, then those will
298now need to be changed to ``inherit image-artifact-names``.
299
300
301.. _migration-3.2-misc:
302
303Miscellaneous changes
304---------------------
305
Andrew Geissler615f2f12022-07-15 14:00:58 -0500306- Support for the long-deprecated ``PACKAGE_GROUP`` variable has now been removed --- replace any remaining instances with :term:`FEATURE_PACKAGES`.
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600307- The ``FILESPATHPKG`` variable, having been previously deprecated, has now been removed. Replace any remaining references with appropriate use of :term:`FILESEXTRAPATHS`.
308- Erroneous use of ``inherit +=`` (instead of ``INHERIT +=``) in a configuration file now triggers an error instead of silently being ignored.
309- 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.
310- ``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.
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500311- 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.
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600312- 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.
313- The ``tune-supersparc.inc`` tune file has been removed as it does not appear to be widely used and no longer works.