1.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
2
3Release 3.1 (dunfell)
4=====================
5
6This section provides migration information for moving to the Yocto
7Project 3.1 Release (codename "dunfell") from the prior release.
8
9.. _migration-3.1-minimum-system-requirements:
10
11Minimum system requirements
12---------------------------
13
14The following versions / requirements of build host components have been
15updated:
16
17-  gcc 5.0
18
19-  python 3.5
20
21-  tar 1.28
22
23-  ``rpcgen`` is now required on the host (part of the ``libc-dev-bin``
24   package on Ubuntu, Debian and related distributions, and the
25   ``glibc`` package on RPM-based distributions).
26
27Additionally, the ``makeinfo`` and ``pod2man`` tools are *no longer*
28required on the host.
29
30.. _migration-3.1-mpc8315e-rdb-removed:
31
32mpc8315e-rdb machine removed
33----------------------------
34
35The MPC8315E-RDB machine is old/obsolete and unobtainable, thus given
36the maintenance burden the ``mpc8315e-rdb`` machine configuration that
37supported it has been removed in this release. The removal does leave a
38gap in official PowerPC reference hardware support; this may change in
39future if a suitable machine with accompanying support resources is
40found.
41
42.. _migration-3.1-python-2-removed:
43
44Python 2 removed
45----------------
46
47Due to the expiration of upstream support in January 2020, support for
48Python 2 has now been removed; it is recommended that you use Python 3
49instead. If absolutely needed there is a meta-python2 community layer
50containing Python 2, related classes and various Python 2-based modules,
51however it should not be considered as supported.
52
53.. _migration-3.1-reproducible-builds:
54
55Reproducible builds now enabled by default
56------------------------------------------
57
58In order to avoid unnecessary differences in output files (aiding binary
59reproducibility), the Poky distribution configuration
60(``DISTRO = "poky"``) now inherits the ``reproducible_build`` class by
61default.
62
63.. _migration-3.1-ptest-feature-impact:
64
65Impact of ptest feature is now more significant
66-----------------------------------------------
67
68The Poky distribution configuration (``DISTRO = "poky"``) enables ptests
69by default to enable runtime testing of various components. In this
70release, a dependency needed to be added that has resulted in a
71significant increase in the number of components that will be built just
72when building a simple image such as core-image-minimal. If you do not
73need runtime tests enabled for core components, then it is recommended
74that you remove "ptest" from
75:term:`DISTRO_FEATURES` to save a significant
76amount of build time e.g. by adding the following in your configuration::
77
78   DISTRO_FEATURES_remove = "ptest"
79
80.. _migration-3.1-removed-recipes:
81
82Removed recipes
83---------------
84
85The following recipes have been removed:
86
87-  ``chkconfig``: obsolete
88
89-  ``console-tools``: obsolete
90
91-  ``enchant``: replaced by ``enchant2``
92
93-  ``foomatic-filters``: obsolete
94
95-  ``libidn``: no longer needed, moved to meta-oe
96
97-  ``libmodulemd``: replaced by ``libmodulemd-v1``
98
99-  ``linux-yocto``: drop 4.19, 5.2 version recipes (5.4 now provided)
100
101-  ``nspr``: no longer needed, moved to meta-oe
102
103-  ``nss``: no longer needed, moved to meta-oe
104
105-  ``python``: Python 2 removed (Python 3 preferred)
106
107-  ``python-setuptools``: Python 2 version removed (python3-setuptools
108   preferred)
109
110-  ``sysprof``: no longer needed, moved to meta-oe
111
112-  ``texi2html``: obsolete
113
114-  ``u-boot-fw-utils``: functionally replaced by ``libubootenv``
115
116.. _migration-3.1-features-check:
117
118features_check class replaces distro_features_check
119---------------------------------------------------
120
121The ``distro_features_check`` class has had its functionality expanded,
122now supporting ``ANY_OF_MACHINE_FEATURES``,
123``REQUIRED_MACHINE_FEATURES``, ``CONFLICT_MACHINE_FEATURES``,
124``ANY_OF_COMBINED_FEATURES``, ``REQUIRED_COMBINED_FEATURES``,
125``CONFLICT_COMBINED_FEATURES``. As a result the class has now been
126renamed to ``features_check``; the ``distro_features_check`` class still
127exists but generates a warning and redirects to the new class. In
128preparation for a future removal of the old class it is recommended that
129you update recipes currently inheriting ``distro_features_check`` to
130inherit :ref:`ref-classes-features_check` instead.
131
132.. _migration-3.1-removed-classes:
133
134Removed classes
135---------------
136
137The following classes have been removed:
138
139-  ``distutils-base``: moved to meta-python2
140
141-  ``distutils``: moved to meta-python2
142
143-  ``libc-common``: merged into the glibc recipe as nothing else used
144   it.
145
146-  ``python-dir``: moved to meta-python2
147
148-  ``pythonnative``: moved to meta-python2
149
150-  ``setuptools``: moved to meta-python2
151
152-  ``tinderclient``: dropped as it was obsolete.
153
154.. _migration-3.1-src-uri-checksums:
155
156SRC_URI checksum behaviour
157--------------------------
158
159Previously, recipes by tradition included both SHA256 and MD5 checksums
160for remotely fetched files in :term:`SRC_URI`, even
161though only one is actually mandated. However, the MD5 checksum does not
162add much given its inherent weakness; thus when a checksum fails only
163the SHA256 sum will now be printed. The md5sum will still be verified if
164it is specified.
165
166.. _migration-3.1-npm:
167
168npm fetcher changes
169-------------------
170
171The npm fetcher has been completely reworked in this release. The npm
172fetcher now only fetches the package source itself and no longer the
173dependencies; there is now also an npmsw fetcher which explicitly
174fetches the shrinkwrap file and the dependencies. This removes the
175slightly awkward ``NPM_LOCKDOWN`` and ``NPM_SHRINKWRAP`` variables which
176pointed to local files; the lockdown file is no longer needed at all.
177Additionally, the package name in ``npm://`` entries in
178:term:`SRC_URI` is now specified using a ``package``
179parameter instead of the earlier ``name`` which overlapped with the
180generic ``name`` parameter. All recipes using the npm fetcher will need
181to be changed as a result.
182
183An example of the new scheme::
184
185   SRC_URI = "npm://registry.npmjs.org;package=array-flatten;version=1.1.1 \
186              npmsw://${THISDIR}/npm-shrinkwrap.json"
187
188Another example where the sources are fetched from git rather than an npm repository::
189
190   SRC_URI = "git://github.com/foo/bar.git;protocol=https \
191              npmsw://${THISDIR}/npm-shrinkwrap.json"
192
193devtool and recipetool have also been updated to match with the npm
194fetcher changes. Other than producing working and more complete recipes
195for npm sources, there is also a minor change to the command line for
196devtool: the ``--fetch-dev`` option has been renamed to ``--npm-dev`` as
197it is npm-specific.
198
199.. _migration-3.1-packaging-changes:
200
201Packaging changes
202-----------------
203
204-  ``intltool`` has been removed from ``packagegroup-core-sdk`` as it is
205   rarely needed to build modern software --- gettext can do most of the
206   things it used to be needed for. ``intltool`` has also been removed
207   from ``packagegroup-core-self-hosted`` as it is not needed to for
208   standard builds.
209
210-  git: ``git-am``, ``git-difftool``, ``git-submodule``, and
211   ``git-request-pull`` are no longer perl-based, so are now installed
212   with the main ``git`` package instead of within ``git-perltools``.
213
214-  The ``ldconfig`` binary built as part of glibc has now been moved to
215   its own ``ldconfig`` package (note no ``glibc-`` prefix). This
216   package is in the :term:`RRECOMMENDS` of the main
217   ``glibc`` package if ``ldconfig`` is present in
218   :term:`DISTRO_FEATURES`.
219
220-  ``libevent`` now splits each shared library into its own package (as
221   Debian does). Since these are shared libraries and will be pulled in
222   through the normal shared library dependency handling, there should
223   be no impact to existing configurations other than less unnecessary
224   libraries being installed in some cases.
225
226-  linux-firmware now has a new package for ``bcm4366c`` and includes
227   available NVRAM config files into the ``bcm43340``, ``bcm43362``,
228   ``bcm43430`` and ``bcm4356-pcie`` packages.
229
230-  ``harfbuzz`` now splits the new ``libharfbuzz-subset.so`` library
231   into its own package to reduce the main package size in cases where
232   ``libharfbuzz-subset.so`` is not needed.
233
234.. _migration-3.1-package-qa-warnings:
235
236Additional warnings
237-------------------
238
239Warnings will now be shown at :ref:`ref-tasks-package_qa` time in the following
240circumstances:
241
242-  A recipe installs ``.desktop`` files containing ``MimeType`` keys but
243   does not inherit the new :ref:`ref-classes-mime-xdg` class
244
245-  A recipe installs ``.xml`` files into ``${datadir}/mime/packages``
246   but does not inherit the :ref:`ref-classes-mime` class
247
248.. _migration-3.1-x86-live-wic:
249
250``wic`` image type now used instead of ``live`` by default for x86
251------------------------------------------------------------------
252
253``conf/machine/include/x86-base.inc`` (inherited by most x86 machine
254configurations) now specifies ``wic`` instead of ``live`` by default in
255:term:`IMAGE_FSTYPES`. The ``live`` image type will
256likely be removed in a future release so it is recommended that you use
257``wic`` instead.
258
259.. _migration-3.1-misc:
260
261Miscellaneous changes
262---------------------
263
264-  The undocumented ``SRC_DISTRIBUTE_LICENSES`` variable has now been
265   removed in favour of a new ``AVAILABLE_LICENSES`` variable which is
266   dynamically set based upon license files found in
267   ``${COMMON_LICENSE_DIR}`` and ``${LICENSE_PATH}``.
268
269-  The tune definition for big-endian microblaze machines is now
270   ``microblaze`` instead of ``microblazeeb``.
271
272-  ``newlib`` no longer has built-in syscalls. ``libgloss`` should then
273   provide the syscalls, ``crt0.o`` and other functions that are no
274   longer part of ``newlib`` itself. If you are using
275   ``TCLIBC = "newlib"`` this now means that you must link applications
276   with both ``newlib`` and ``libgloss``, whereas before ``newlib``
277   would run in many configurations by itself.
278