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