blob: 5d524f38173e6776c5f46c456e12c6ccd35304cd [file] [log] [blame]
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001Moving to the Yocto Project 2.6 Release
2=======================================
3
4This section provides migration information for moving to the Yocto
5Project 2.6 Release from the prior release.
6
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 Geissler4c19ea12020-10-27 13:52:24 -0500113`Removed Recipes <#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
121:ref:`distutils <ref-classes-distutils>` and
122: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``
164 configuration file as follows:
165 ::
166
167 IMAGE_VERSION_SUFFIX = "-${DATETIME}"
168
169- Several variables have changed names for consistency:
170 ::
171
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500172 Old Variable Name New Variable Name
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500173 ========================================================
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500174 KERNEL_IMAGE_BASE_NAME KERNEL_IMAGE_NAME
175 KERNEL_IMAGE_SYMLINK_NAME KERNEL_IMAGE_LINK_NAME
176 MODULE_TARBALL_BASE_NAME MODULE_TARBALL_NAME
177 MODULE_TARBALL_SYMLINK_NAME MODULE_TARBALL_LINK_NAME
178 INITRAMFS_BASE_NAME INITRAMFS_NAME
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500179
180- The ``MODULE_IMAGE_BASE_NAME`` variable has been removed. The module
181 tarball name is now controlled directly with the
182 :term:`MODULE_TARBALL_NAME` variable.
183
184- The :term:`KERNEL_DTB_NAME` and
185 :term:`KERNEL_DTB_LINK_NAME` variables
186 have been introduced to control kernel Device Tree Binary (DTB)
187 artifact names instead of mangling ``KERNEL_IMAGE_*`` variables.
188
189- The :term:`KERNEL_FIT_NAME` and
190 :term:`KERNEL_FIT_LINK_NAME` variables
191 have been introduced to specify the name of flattened image tree
192 (FIT) kernel images similar to other deployed artifacts.
193
194- The :term:`MODULE_TARBALL_NAME` and
195 :term:`MODULE_TARBALL_LINK_NAME`
196 variable values no longer include the "module-" prefix or ".tgz"
197 suffix. These parts are now hardcoded so that the values are
198 consistent with other artifact naming variables.
199
200- Added the :term:`INITRAMFS_LINK_NAME`
201 variable so that the symlink can be controlled similarly to other
202 artifact types.
203
204- :term:`INITRAMFS_NAME` now uses
205 "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}" instead
206 of "${PV}-${PR}-${MACHINE}-${DATETIME}", which makes it consistent
207 with other variables.
208
209.. _migration-2.6-serial-console-deprecated:
210
211``SERIAL_CONSOLE`` Deprecated
212-----------------------------
213
214The :term:`SERIAL_CONSOLE` variable has been
215functionally replaced by the
216:term:`SERIAL_CONSOLES` variable for some time.
217With the Yocto Project 2.6 release, ``SERIAL_CONSOLE`` has been
218officially deprecated.
219
220``SERIAL_CONSOLE`` will continue to work as before for the 2.6 release.
221However, for the sake of future compatibility, it is recommended that
222you replace all instances of ``SERIAL_CONSOLE`` with
223``SERIAL_CONSOLES``.
224
225.. note::
226
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500227 The only difference in usage is that ``SERIAL_CONSOLES``
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500228 expects entries to be separated using semicolons as compared to
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500229 ``SERIAL_CONSOLE``, which expects spaces.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500230
231.. _migration-2.6-poky-sets-unknown-configure-option-to-qa-error:
232
233Configure Script Reports Unknown Options as Errors
234--------------------------------------------------
235
236If the configure script reports an unknown option, this now triggers a
237QA error instead of a warning. Any recipes that previously got away with
238specifying such unknown options now need to be fixed.
239
240.. _migration-2.6-override-changes:
241
242Override Changes
243----------------
244
245The following changes have occurred:
246
247- The ``virtclass-native`` and ``virtclass-nativesdk`` Overrides Have
248 Been Removed: The ``virtclass-native`` and ``virtclass-nativesdk``
249 overrides have been deprecated since 2012 in favor of
250 ``class-native`` and ``class-nativesdk``, respectively. Both
251 ``virtclass-native`` and ``virtclass-nativesdk`` are now dropped.
252
253 .. note::
254
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500255 The ``virtclass-multilib-`` overrides for multilib are still valid.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500256
257- The ``forcevariable`` Override Now Has a Higher Priority Than
258 ``libc`` Overrides: The ``forcevariable`` override is documented to
259 be the highest priority override. However, due to a long-standing
260 quirk of how :term:`OVERRIDES` is set, the ``libc``
261 overrides (e.g. ``libc-glibc``, ``libc-musl``, and so forth)
262 erroneously had a higher priority. This issue is now corrected.
263
264 It is likely this change will not cause any problems. However, it is
265 possible with some unusual configurations that you might see a change
266 in behavior if you were relying on the previous behavior. Be sure to
267 check how you use ``forcevariable`` and ``libc-*`` overrides in your
268 custom layers and configuration files to ensure they make sense.
269
270- The ``build-${BUILD_OS}`` Override Has Been Removed: The
271 ``build-${BUILD_OS}``, which is typically ``build-linux``, override
272 has been removed because building on a host operating system other
273 than a recent version of Linux is neither supported nor recommended.
274 Dropping the override avoids giving the impression that other host
275 operating systems might be supported.
276
277- The "_remove" operator now preserves whitespace. Consequently, when
278 specifying list items to remove, be aware that leading and trailing
279 whitespace resulting from the removal is retained.
280
Andrew Geissler09209ee2020-12-13 08:44:15 -0600281 See the ":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata:removal (override style syntax)`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500282 section in the BitBake User Manual for a detailed example.
283
284.. _migration-2.6-systemd-configuration-now-split-out-to-system-conf:
285
286``systemd`` Configuration is Now Split Into ``systemd-conf``
287------------------------------------------------------------
288
289The configuration for the ``systemd`` recipe has been moved into a
290``system-conf`` recipe. Moving this configuration to a separate recipe
291avoids the ``systemd`` recipe from becoming machine-specific for cases
292where machine-specific configurations need to be applied (e.g. for
293``qemu*`` machines).
294
295Currently, the new recipe packages the following files:
296::
297
298 ${sysconfdir}/machine-id
299 ${sysconfdir}/systemd/coredump.conf
300 ${sysconfdir}/systemd/journald.conf
301 ${sysconfdir}/systemd/logind.conf
302 ${sysconfdir}/systemd/system.conf
303 ${sysconfdir}/systemd/user.conf
304
305If you previously used bbappend files to append the ``systemd`` recipe to
306change any of the listed files, you must do so for the ``systemd-conf``
307recipe instead.
308
309.. _migration-2.6-automatic-testing-changes:
310
311Automatic Testing Changes
312-------------------------
313
314This section provides information about automatic testing changes:
315
316- ``TEST_IMAGE`` Variable Removed: Prior to this release, you set the
317 ``TEST_IMAGE`` variable to "1" to enable automatic testing for
318 successfully built images. The ``TEST_IMAGE`` variable no longer
319 exists and has been replaced by the
320 :term:`TESTIMAGE_AUTO` variable.
321
322- Inheriting the ``testimage`` and ``testsdk`` Classes: Best
323 practices now dictate that you use the
324 :term:`IMAGE_CLASSES` variable rather than the
325 :term:`INHERIT` variable when you inherit the
326 :ref:`testimage <ref-classes-testimage*>` and
327 :ref:`testsdk <ref-classes-testsdk>` classes used for automatic
328 testing.
329
330.. _migration-2.6-openssl-changes:
331
332OpenSSL Changes
333---------------
334
335`OpenSSL <https://www.openssl.org/>`__ has been upgraded from 1.0 to
3361.1. By default, this upgrade could cause problems for recipes that have
337both versions in their dependency chains. The problem is that both
338versions cannot be installed together at build time.
339
340.. note::
341
342 It is possible to have both versions of the library at runtime.
343
344.. _migration-2.6-bitbake-changes:
345
346BitBake Changes
347---------------
348
349The server logfile ``bitbake-cookerdaemon.log`` is now always placed in
350the :term:`Build Directory` instead of the current
351directory.
352
353.. _migration-2.6-security-changes:
354
355Security Changes
356----------------
357
358The Poky distribution now uses security compiler flags by default.
359Inclusion of these flags could cause new failures due to stricter
360checking for various potential security issues in code.
361
362.. _migration-2.6-post-installation-changes:
363
364Post Installation Changes
365-------------------------
366
367You must explicitly mark post installs to defer to the target. If you
368want to explicitly defer a postinstall to first boot on the target
369rather than at rootfs creation time, use ``pkg_postinst_ontarget()`` or
370call ``postinst_intercept delay_to_first_boot`` from ``pkg_postinst()``.
371Any failure of a ``pkg_postinst()`` script (including exit 1) triggers
372an error during the :ref:`ref-tasks-rootfs` task.
373
374For more information on post-installation behavior, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600375":ref:`dev-manual/common-tasks:post-installation scripts`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500376section in the Yocto Project Development Tasks Manual.
377
378.. _migration-2.6-python-3-profile-guided-optimizations:
379
380Python 3 Profile-Guided Optimization
381------------------------------------
382
383The ``python3`` recipe now enables profile-guided optimization. Using
384this optimization requires a little extra build time in exchange for
385improved performance on the target at runtime. Additionally, the
386optimization is only enabled if the current
387:term:`MACHINE` has support for user-mode emulation in
388QEMU (i.e. "qemu-usermode" is in
389:term:`MACHINE_FEATURES`, which it is by
390default).
391
392If you wish to disable Python profile-guided optimization regardless of
393the value of ``MACHINE_FEATURES``, then ensure that
394:term:`PACKAGECONFIG` for the ``python3`` recipe
395does not contain "pgo". You could accomplish the latter using the
396following at the configuration level:
397::
398
399 PACKAGECONFIG_remove_pn-python3 = "pgo"
400
401Alternatively, you can set ``PACKAGECONFIG`` using an append file
402for the ``python3`` recipe.
403
404.. _migration-2.6-miscellaneous-changes:
405
406Miscellaneous Changes
407---------------------
408
409The following miscellaneous changes occurred:
410
411- Default to using the Thumb-2 instruction set for armv7a and above. If
412 you have any custom recipes that build software that needs to be
413 built with the ARM instruction set, change the recipe to set the
414 instruction set as follows:
415 ::
416
417 ARM_INSTRUCTION_SET = "arm"
418
419- ``run-postinsts`` no longer uses ``/etc/*-postinsts`` for
420 ``dpkg/opkg`` in favor of built-in postinst support. RPM behavior
421 remains unchanged.
422
423- The ``NOISO`` and ``NOHDD`` variables are no longer used. You now
424 control building ``*.iso`` and ``*.hddimg`` image types directly by
425 using the :term:`IMAGE_FSTYPES` variable.
426
427- The ``scripts/contrib/mkefidisk.sh`` has been removed in favor of
428 Wic.
429
430- ``kernel-modules`` has been removed from
431 :term:`RRECOMMENDS` for ``qemumips`` and
432 ``qemumips64`` machines. Removal also impacts the ``x86-base.inc``
433 file.
434
435 .. note::
436
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500437 ``genericx86`` and ``genericx86-64`` retain ``kernel-modules`` as part of
438 the ``RRECOMMENDS`` variable setting.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500439
440- The ``LGPLv2_WHITELIST_GPL-3.0`` variable has been removed. If you
441 are setting this variable in your configuration, set or append it to
442 the ``WHITELIST_GPL-3.0`` variable instead.
443
444- ``${ASNEEDED}`` is now included in the
445 :term:`TARGET_LDFLAGS` variable directly. The
446 remaining definitions from ``meta/conf/distro/include/as-needed.inc``
447 have been moved to corresponding recipes.
448
449- Support for DSA host keys has been dropped from the OpenSSH recipes.
450 If you are still using DSA keys, you must switch over to a more
451 secure algorithm as recommended by OpenSSH upstream.
452
453- The ``dhcp`` recipe now uses the ``dhcpd6.conf`` configuration file
454 in ``dhcpd6.service`` for IPv6 DHCP rather than re-using
455 ``dhcpd.conf``, which is now reserved for IPv4.
456
457