blob: d1c6c0c5f58e26cfa4ba361ddea6c9ad0eca4e80 [file] [log] [blame]
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05001Moving to the Yocto Project 2.6 Release (thud)
2==============================================
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003
4This section provides migration information for moving to the Yocto
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05005Project 2.6 Release (codename "thud") from the prior release.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006
7.. _migration-2.6-gcc-changes:
8
9GCC 8.2 is Now Used by Default
10------------------------------
11
12The GNU Compiler Collection version 8.2 is now used by default for
13compilation. For more information on what has changed in the GCC 8.x
14release, see https://gcc.gnu.org/gcc-8/changes.html.
15
16If you still need to compile with version 7.x, GCC 7.3 is also provided.
17You can select this version by setting the and can be selected by
18setting the :term:`GCCVERSION` variable to "7.%" in
19your configuration.
20
21.. _migration-2.6-removed-recipes:
22
23Removed Recipes
24---------------
25
26The following recipes have been removed:
27
28- *beecrypt*: No longer needed since moving to RPM 4.
29- *bigreqsproto*: Replaced by ``xorgproto``.
30- *calibrateproto*: Removed in favor of ``xinput``.
31- *compositeproto*: Replaced by ``xorgproto``.
32- *damageproto*: Replaced by ``xorgproto``.
33- *dmxproto*: Replaced by ``xorgproto``.
34- *dri2proto*: Replaced by ``xorgproto``.
35- *dri3proto*: Replaced by ``xorgproto``.
36- *eee-acpi-scripts*: Became obsolete.
37- *fixesproto*: Replaced by ``xorgproto``.
38- *fontsproto*: Replaced by ``xorgproto``.
39- *fstests*: Became obsolete.
40- *gccmakedep*: No longer used.
41- *glproto*: Replaced by ``xorgproto``.
42- *gnome-desktop3*: No longer needed. This recipe has moved to ``meta-oe``.
43- *icon-naming-utils*: No longer used since the Sato theme was removed in 2016.
44- *inputproto*: Replaced by ``xorgproto``.
45- *kbproto*: Replaced by ``xorgproto``.
46- *libusb-compat*: Became obsolete.
47- *libuser*: Became obsolete.
48- *libnfsidmap*: No longer an external requirement since ``nfs-utils`` 2.2.1. ``libnfsidmap`` is now integrated.
49- *libxcalibrate*: No longer needed with ``xinput``
50- *mktemp*: Became obsolete. The ``mktemp`` command is provided by both ``busybox`` and ``coreutils``.
51- *ossp-uuid*: Is not being maintained and has mostly been replaced by ``uuid.h`` in ``util-linux``.
52- *pax-utils*: No longer needed. Previous QA tests that did use this recipe are now done at build time.
53- *pcmciautils*: Became obsolete.
54- *pixz*: No longer needed. ``xz`` now supports multi-threaded compression.
55- *presentproto*: Replaced by ``xorgproto``.
56- *randrproto*: Replaced by ``xorgproto``.
57- *recordproto*: Replaced by ``xorgproto``.
58- *renderproto*: Replaced by ``xorgproto``.
59- *resourceproto*: Replaced by ``xorgproto``.
60- *scrnsaverproto*: Replaced by ``xorgproto``.
61- *trace-cmd*: Became obsolete. ``perf`` replaced this recipe's functionally.
62- *videoproto*: Replaced by ``xorgproto``.
63- *wireless-tools*: Became obsolete. Superseded by ``iw``.
64- *xcmiscproto*: Replaced by ``xorgproto``.
65- *xextproto*: Replaced by ``xorgproto``.
66- *xf86dgaproto*: Replaced by ``xorgproto``.
67- *xf86driproto*: Replaced by ``xorgproto``.
68- *xf86miscproto*: Replaced by ``xorgproto``.
69- *xf86-video-omapfb*: Became obsolete. Use kernel modesetting driver instead.
70- *xf86-video-omap*: Became obsolete. Use kernel modesetting driver instead.
71- *xf86vidmodeproto*: Replaced by ``xorgproto``.
72- *xineramaproto*: Replaced by ``xorgproto``.
73- *xproto*: Replaced by ``xorgproto``.
74- *yasm*: No longer needed since previous usages are now satisfied by ``nasm``.
75
76.. _migration-2.6-packaging-changes:
77
78Packaging Changes
79-----------------
80
81The following packaging changes have been made:
82
83- *cmake*: ``cmake.m4`` and ``toolchain`` files have been moved to
84 the main package.
85
86- *iptables*: The ``iptables`` modules have been split into
87 separate packages.
88
89- *alsa-lib*: ``libasound`` is now in the main ``alsa-lib`` package
90 instead of ``libasound``.
91
92- *glibc*: ``libnss-db`` is now in its own package along with a
93 ``/var/db/makedbs.sh`` script to update databases.
94
95- *python and python3*: The main package has been removed from
96 the recipe. You must install specific packages or ``python-modules``
97 / ``python3-modules`` for everything.
98
99- *systemtap*: Moved ``systemtap-exporter`` into its own package.
100
101.. _migration-2.6-xorg-protocol-dependencies:
102
103XOrg Protocol dependencies
104--------------------------
105
106The ``*proto`` upstream repositories have been combined into one
107"xorgproto" repository. Thus, the corresponding recipes have also been
108combined into a single ``xorgproto`` recipe. Any recipes that depend
109upon the older ``*proto`` recipes need to be changed to depend on the
110newer ``xorgproto`` recipe instead.
111
112For names of recipes removed because of this repository change, see the
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500113:ref:`ref-manual/migration-2.6:removed recipes` section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500114
115.. _migration-2.6-distutils-distutils3-fetching-dependencies:
116
117``distutils`` and ``distutils3`` Now Prevent Fetching Dependencies During the ``do_configure`` Task
118---------------------------------------------------------------------------------------------------
119
120Previously, it was possible for Python recipes that inherited the
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500121``distutils`` and
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500122:ref:`distutils3 <ref-classes-distutils3>` classes to fetch code
123during the :ref:`ref-tasks-configure` task to satisfy
124dependencies mentioned in ``setup.py`` if those dependencies were not
125provided in the sysroot (i.e. recipes providing the dependencies were
126missing from :term:`DEPENDS`).
127
128.. note::
129
130 This change affects classes beyond just the two mentioned (i.e.
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500131 ``distutils`` and ``distutils3``). Any recipe that inherits ``distutils*``
132 classes are affected. For example, the ``setuptools`` and ``setuptools3``
133 recipes are affected since they inherit the ``distutils*`` classes.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500134
135Fetching these types of dependencies that are not provided in the
136sysroot negatively affects the ability to reproduce builds. This type of
137fetching is now explicitly disabled. Consequently, any missing
138dependencies in Python recipes that use these classes now result in an
139error during the ``do_configure`` task.
140
141.. _migration-2.6-linux-yocto-configuration-audit-issues-now-correctly-reported:
142
143``linux-yocto`` Configuration Audit Issues Now Correctly Reported
144-----------------------------------------------------------------
145
146Due to a bug, the kernel configuration audit functionality was not
147writing out any resulting warnings during the build. This issue is now
148corrected. You might notice these warnings now if you have a custom
149kernel configuration with a ``linux-yocto`` style kernel recipe.
150
151.. _migration-2.6-image-kernel-artifact-naming-changes:
152
153Image/Kernel Artifact Naming Changes
154------------------------------------
155
156The following changes have been made:
157
158- Name variables (e.g. :term:`IMAGE_NAME`) use a new
159 ``IMAGE_VERSION_SUFFIX`` variable instead of
160 :term:`DATETIME`. Using ``IMAGE_VERSION_SUFFIX``
161 allows easier and more direct changes.
162
163 The ``IMAGE_VERSION_SUFFIX`` variable is set in the ``bitbake.conf``
Andrew Geisslerc926e172021-05-07 16:11:35 -0500164 configuration file as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500165
166 IMAGE_VERSION_SUFFIX = "-${DATETIME}"
167
Andrew Geisslerc926e172021-05-07 16:11:35 -0500168- Several variables have changed names for consistency::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500169
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500170 Old Variable Name New Variable Name
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500171 ========================================================
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500172 KERNEL_IMAGE_BASE_NAME KERNEL_IMAGE_NAME
173 KERNEL_IMAGE_SYMLINK_NAME KERNEL_IMAGE_LINK_NAME
174 MODULE_TARBALL_BASE_NAME MODULE_TARBALL_NAME
175 MODULE_TARBALL_SYMLINK_NAME MODULE_TARBALL_LINK_NAME
176 INITRAMFS_BASE_NAME INITRAMFS_NAME
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500177
178- The ``MODULE_IMAGE_BASE_NAME`` variable has been removed. The module
179 tarball name is now controlled directly with the
180 :term:`MODULE_TARBALL_NAME` variable.
181
182- The :term:`KERNEL_DTB_NAME` and
183 :term:`KERNEL_DTB_LINK_NAME` variables
184 have been introduced to control kernel Device Tree Binary (DTB)
185 artifact names instead of mangling ``KERNEL_IMAGE_*`` variables.
186
187- The :term:`KERNEL_FIT_NAME` and
188 :term:`KERNEL_FIT_LINK_NAME` variables
189 have been introduced to specify the name of flattened image tree
190 (FIT) kernel images similar to other deployed artifacts.
191
192- The :term:`MODULE_TARBALL_NAME` and
193 :term:`MODULE_TARBALL_LINK_NAME`
194 variable values no longer include the "module-" prefix or ".tgz"
195 suffix. These parts are now hardcoded so that the values are
196 consistent with other artifact naming variables.
197
198- Added the :term:`INITRAMFS_LINK_NAME`
199 variable so that the symlink can be controlled similarly to other
200 artifact types.
201
202- :term:`INITRAMFS_NAME` now uses
203 "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}" instead
204 of "${PV}-${PR}-${MACHINE}-${DATETIME}", which makes it consistent
205 with other variables.
206
207.. _migration-2.6-serial-console-deprecated:
208
209``SERIAL_CONSOLE`` Deprecated
210-----------------------------
211
212The :term:`SERIAL_CONSOLE` variable has been
213functionally replaced by the
214:term:`SERIAL_CONSOLES` variable for some time.
215With the Yocto Project 2.6 release, ``SERIAL_CONSOLE`` has been
216officially deprecated.
217
218``SERIAL_CONSOLE`` will continue to work as before for the 2.6 release.
219However, for the sake of future compatibility, it is recommended that
220you replace all instances of ``SERIAL_CONSOLE`` with
221``SERIAL_CONSOLES``.
222
223.. note::
224
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500225 The only difference in usage is that ``SERIAL_CONSOLES``
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500226 expects entries to be separated using semicolons as compared to
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500227 ``SERIAL_CONSOLE``, which expects spaces.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500228
229.. _migration-2.6-poky-sets-unknown-configure-option-to-qa-error:
230
231Configure Script Reports Unknown Options as Errors
232--------------------------------------------------
233
234If the configure script reports an unknown option, this now triggers a
235QA error instead of a warning. Any recipes that previously got away with
236specifying such unknown options now need to be fixed.
237
238.. _migration-2.6-override-changes:
239
240Override Changes
241----------------
242
243The following changes have occurred:
244
245- The ``virtclass-native`` and ``virtclass-nativesdk`` Overrides Have
246 Been Removed: The ``virtclass-native`` and ``virtclass-nativesdk``
247 overrides have been deprecated since 2012 in favor of
248 ``class-native`` and ``class-nativesdk``, respectively. Both
249 ``virtclass-native`` and ``virtclass-nativesdk`` are now dropped.
250
251 .. note::
252
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500253 The ``virtclass-multilib-`` overrides for multilib are still valid.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500254
255- The ``forcevariable`` Override Now Has a Higher Priority Than
256 ``libc`` Overrides: The ``forcevariable`` override is documented to
257 be the highest priority override. However, due to a long-standing
258 quirk of how :term:`OVERRIDES` is set, the ``libc``
259 overrides (e.g. ``libc-glibc``, ``libc-musl``, and so forth)
260 erroneously had a higher priority. This issue is now corrected.
261
262 It is likely this change will not cause any problems. However, it is
263 possible with some unusual configurations that you might see a change
264 in behavior if you were relying on the previous behavior. Be sure to
265 check how you use ``forcevariable`` and ``libc-*`` overrides in your
266 custom layers and configuration files to ensure they make sense.
267
268- The ``build-${BUILD_OS}`` Override Has Been Removed: The
269 ``build-${BUILD_OS}``, which is typically ``build-linux``, override
270 has been removed because building on a host operating system other
271 than a recent version of Linux is neither supported nor recommended.
272 Dropping the override avoids giving the impression that other host
273 operating systems might be supported.
274
275- The "_remove" operator now preserves whitespace. Consequently, when
276 specifying list items to remove, be aware that leading and trailing
277 whitespace resulting from the removal is retained.
278
Andrew Geissler09209ee2020-12-13 08:44:15 -0600279 See the ":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata:removal (override style syntax)`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500280 section in the BitBake User Manual for a detailed example.
281
282.. _migration-2.6-systemd-configuration-now-split-out-to-system-conf:
283
284``systemd`` Configuration is Now Split Into ``systemd-conf``
285------------------------------------------------------------
286
287The configuration for the ``systemd`` recipe has been moved into a
288``system-conf`` recipe. Moving this configuration to a separate recipe
289avoids the ``systemd`` recipe from becoming machine-specific for cases
290where machine-specific configurations need to be applied (e.g. for
291``qemu*`` machines).
292
Andrew Geisslerc926e172021-05-07 16:11:35 -0500293Currently, the new recipe packages the following files::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500294
295 ${sysconfdir}/machine-id
296 ${sysconfdir}/systemd/coredump.conf
297 ${sysconfdir}/systemd/journald.conf
298 ${sysconfdir}/systemd/logind.conf
299 ${sysconfdir}/systemd/system.conf
300 ${sysconfdir}/systemd/user.conf
301
302If you previously used bbappend files to append the ``systemd`` recipe to
303change any of the listed files, you must do so for the ``systemd-conf``
304recipe instead.
305
306.. _migration-2.6-automatic-testing-changes:
307
308Automatic Testing Changes
309-------------------------
310
311This section provides information about automatic testing changes:
312
313- ``TEST_IMAGE`` Variable Removed: Prior to this release, you set the
314 ``TEST_IMAGE`` variable to "1" to enable automatic testing for
315 successfully built images. The ``TEST_IMAGE`` variable no longer
316 exists and has been replaced by the
317 :term:`TESTIMAGE_AUTO` variable.
318
319- Inheriting the ``testimage`` and ``testsdk`` Classes: Best
320 practices now dictate that you use the
321 :term:`IMAGE_CLASSES` variable rather than the
322 :term:`INHERIT` variable when you inherit the
323 :ref:`testimage <ref-classes-testimage*>` and
324 :ref:`testsdk <ref-classes-testsdk>` classes used for automatic
325 testing.
326
327.. _migration-2.6-openssl-changes:
328
329OpenSSL Changes
330---------------
331
332`OpenSSL <https://www.openssl.org/>`__ has been upgraded from 1.0 to
3331.1. By default, this upgrade could cause problems for recipes that have
334both versions in their dependency chains. The problem is that both
335versions cannot be installed together at build time.
336
337.. note::
338
339 It is possible to have both versions of the library at runtime.
340
341.. _migration-2.6-bitbake-changes:
342
343BitBake Changes
344---------------
345
346The server logfile ``bitbake-cookerdaemon.log`` is now always placed in
347the :term:`Build Directory` instead of the current
348directory.
349
350.. _migration-2.6-security-changes:
351
352Security Changes
353----------------
354
355The Poky distribution now uses security compiler flags by default.
356Inclusion of these flags could cause new failures due to stricter
357checking for various potential security issues in code.
358
359.. _migration-2.6-post-installation-changes:
360
361Post Installation Changes
362-------------------------
363
364You must explicitly mark post installs to defer to the target. If you
365want to explicitly defer a postinstall to first boot on the target
366rather than at rootfs creation time, use ``pkg_postinst_ontarget()`` or
367call ``postinst_intercept delay_to_first_boot`` from ``pkg_postinst()``.
368Any failure of a ``pkg_postinst()`` script (including exit 1) triggers
369an error during the :ref:`ref-tasks-rootfs` task.
370
371For more information on post-installation behavior, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600372":ref:`dev-manual/common-tasks:post-installation scripts`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500373section in the Yocto Project Development Tasks Manual.
374
375.. _migration-2.6-python-3-profile-guided-optimizations:
376
377Python 3 Profile-Guided Optimization
378------------------------------------
379
380The ``python3`` recipe now enables profile-guided optimization. Using
381this optimization requires a little extra build time in exchange for
382improved performance on the target at runtime. Additionally, the
383optimization is only enabled if the current
384:term:`MACHINE` has support for user-mode emulation in
385QEMU (i.e. "qemu-usermode" is in
386:term:`MACHINE_FEATURES`, which it is by
387default).
388
389If you wish to disable Python profile-guided optimization regardless of
390the value of ``MACHINE_FEATURES``, then ensure that
391:term:`PACKAGECONFIG` for the ``python3`` recipe
392does not contain "pgo". You could accomplish the latter using the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500393following at the configuration level::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500394
395 PACKAGECONFIG_remove_pn-python3 = "pgo"
396
397Alternatively, you can set ``PACKAGECONFIG`` using an append file
398for the ``python3`` recipe.
399
400.. _migration-2.6-miscellaneous-changes:
401
402Miscellaneous Changes
403---------------------
404
405The following miscellaneous changes occurred:
406
407- Default to using the Thumb-2 instruction set for armv7a and above. If
408 you have any custom recipes that build software that needs to be
409 built with the ARM instruction set, change the recipe to set the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500410 instruction set as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500411
412 ARM_INSTRUCTION_SET = "arm"
413
414- ``run-postinsts`` no longer uses ``/etc/*-postinsts`` for
415 ``dpkg/opkg`` in favor of built-in postinst support. RPM behavior
416 remains unchanged.
417
418- The ``NOISO`` and ``NOHDD`` variables are no longer used. You now
419 control building ``*.iso`` and ``*.hddimg`` image types directly by
420 using the :term:`IMAGE_FSTYPES` variable.
421
422- The ``scripts/contrib/mkefidisk.sh`` has been removed in favor of
423 Wic.
424
425- ``kernel-modules`` has been removed from
426 :term:`RRECOMMENDS` for ``qemumips`` and
427 ``qemumips64`` machines. Removal also impacts the ``x86-base.inc``
428 file.
429
430 .. note::
431
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500432 ``genericx86`` and ``genericx86-64`` retain ``kernel-modules`` as part of
433 the ``RRECOMMENDS`` variable setting.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500434
435- The ``LGPLv2_WHITELIST_GPL-3.0`` variable has been removed. If you
436 are setting this variable in your configuration, set or append it to
437 the ``WHITELIST_GPL-3.0`` variable instead.
438
439- ``${ASNEEDED}`` is now included in the
440 :term:`TARGET_LDFLAGS` variable directly. The
441 remaining definitions from ``meta/conf/distro/include/as-needed.inc``
442 have been moved to corresponding recipes.
443
444- Support for DSA host keys has been dropped from the OpenSSH recipes.
445 If you are still using DSA keys, you must switch over to a more
446 secure algorithm as recommended by OpenSSH upstream.
447
448- The ``dhcp`` recipe now uses the ``dhcpd6.conf`` configuration file
449 in ``dhcpd6.service`` for IPv6 DHCP rather than re-using
450 ``dhcpd.conf``, which is now reserved for IPv4.
451
452