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