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