summaryrefslogtreecommitdiffstats
path: root/documentation/ref-manual
diff options
context:
space:
mode:
authorPaul Eggleton <paul.eggleton@microsoft.com>2020-10-27 18:18:35 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2020-10-30 12:09:21 +0000
commit38a2462bc77f0ed3e794614404e979cf79237a63 (patch)
tree81f39fe73dfad51dfbf75592badd36e276428df1 /documentation/ref-manual
parent2e59fedd5236471b696a54d76dc8d4b6bd22f131 (diff)
downloadpoky-38a2462bc77f0ed3e794614404e979cf79237a63.tar.gz
ref-manual: add migration section for 3.2
This covers most of the changes that would require action on the part of the user that I was able to see by scouring the commits. Some of the text was borrowed from commit messages and edited. (From yocto-docs rev: 35e9349ba6417765274d7d1ce542e7e6f19dbe26) Signed-off-by: Paul Eggleton <paul.eggleton@microsoft.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/ref-manual')
-rw-r--r--documentation/ref-manual/migration-3.2.rst261
-rw-r--r--documentation/ref-manual/migration.rst1
2 files changed, 262 insertions, 0 deletions
diff --git a/documentation/ref-manual/migration-3.2.rst b/documentation/ref-manual/migration-3.2.rst
new file mode 100644
index 0000000000..073176bf20
--- /dev/null
+++ b/documentation/ref-manual/migration-3.2.rst
@@ -0,0 +1,261 @@
1Moving to the Yocto Project 3.2 Release
2=======================================
3
4This section provides migration information for moving to the Yocto
5Project 3.2 Release from the prior release.
6
7.. _migration-3.2-minimum-system-requirements:
8
9Minimum system requirements
10---------------------------
11
12``gcc`` version 6.0 is now required at minimum on the build host. For older
13host distributions where this is not available, you can use the
14``buildtools-extended-tarball`` (easily installable using
15``scripts/install-buildtools``).
16
17
18.. _migration-3.2-removed-recipes:
19
20Removed recipes
21---------------
22
23The following recipes have been removed:
24
25- ``bjam-native``: replaced by ``boost-build-native``
26- ``avahi-ui``: folded into the main ``avahi`` recipe - the GTK UI can be disabled using :term:`PACKAGECONFIG` for ``avahi``.
27- ``build-compare``: no longer needed with the removal of the ``packagefeed-stability`` class
28- ``dhcp``: obsolete, functionally replaced by ``dhcpcd`` and ``kea``
29- ``libmodulemd-v1``: replaced by ``libmodulemd``
30- ``packagegroup-core-device-devel``: obsolete
31
32
33.. _migration-3.2-removed-classes:
34
35Removed classes
36---------------
37
38The following classes (.bbclass files) have been removed:
39
40- ``spdx``: obsolete - the Yocto Project is a strong supporter of SPDX, but this class was old code using a dated approach and had the potential to be misleading. The ``meta-sdpxscanner`` layer is a much more modern and active approach to handling this and is recommended as a replacement.
41
42- ``packagefeed-stability``: this class had become obsolete with the advent of hash equivalence and reproducible builds.
43
44
45pseudo path filtering and mismatch behaviour
46--------------------------------------------
47
48pseudo now operates on a filtered subset of files. This is a significant change
49to the way pseudo operates within OpenEmbedded - by default, pseudo monitors and
50logs (adds to its database) any file created or modified whilst in a ``fakeroot``
51environment. However, there are large numbers of files that we simply don't care
52about the permissions of whilst in that ``fakeroot`` context, for example ${:term:`S`}, ${:term:`B`}, ${:term:`T`},
53${:term:`SSTATE_DIR`}, the central sstate control directories, and others.
54
55As of this release, new functionality in pseudo is enabled to ignore these
56directory trees (controlled using a new :term:`PSEUDO_IGNORE_PATHS` variable)
57resulting in a cleaner database with less chance of "stray" mismatches if files
58are modified outside pseudo context. It also should reduce some overhead from
59pseudo as the interprocess round trip to the server is avoided.
60
61There is a possible complication where some existing recipe may break, for
62example, a recipe was found to be writing to ``${B}/install`` for
63``make install`` in ``do_install`` and since ``${B}`` is listed as not to be tracked,
64there were errors trying to ``chown root`` for files in this location. Another
65example was the ``tcl`` recipe where the source directory ``S`` is set to a
66subdirectory of the source tree but files were written out to the directory
67structure above that subdirectory. For these types of cases in your own recipes,
68extend ``PSEUDO_IGNORE_PATHS`` to cover additional paths that pseudo should not
69be monitoring.
70
71In addition, pseudo's behaviour on mismatches has now been changed - rather
72than doing what turns out to be a rather dangerous "fixup" if it sees a file
73with a different path but the same inode as another file it has previously seen,
74pseudo will throw an ``abort()`` and direct you to a :yocto_wiki:`wiki page </wiki/Pseudo_Abort>`
75that explains how to deal with this.
76
77
78.. _migration-3.2-packagegroup-core-device-devel:
79
80packagegroup-core-device-devel no longer included in images built for qemu* machines
81------------------------------------------------------------------------------------
82
83``packagegroup-core-device-devel`` was previously added automatically to
84images built for ``qemu*`` machines, however the purpose of the group and what
85it should contain is no longer clear, and in general, adding userspace
86development items to images is best done at the image/class level; thus this
87packagegroup was removed.
88
89This packagegroup previously pulled in the following:
90
91- ``distcc-config``
92- ``nfs-export-root``
93- ``bash``
94- ``binutils-symlinks``
95
96If you still need any of these in your image built for a ``qemu*`` machine
97then you will add them explicitly to :term:`IMAGE_INSTALL` or another
98appropriate place in the dependency chain for your image (if you have not
99already done so).
100
101
102.. _migration-3.2-dhcp:
103
104DHCP server/client replaced
105---------------------------
106
107The ``dhcp`` software package has become unmaintained and thus has been
108functionally replaced by ``dhcpcd`` (client) and ``kea`` (server). You will
109need to replace references to the recipe/package names as appropriate - most
110commonly, at the package level ``dhcp-client`` should be replaced by
111``dhcpcd`` and ``dhcp-server`` should be replaced by ``kea``. If you have any
112custom configuration files for these they will need to be adapted - refer to
113the upstream documentation for ``dhcpcd`` and ``kea`` for further details.
114
115
116.. _migration-3.2-packaging-changes:
117
118Packaging changes
119-----------------
120
121- ``python3``: the ``urllib`` python package has now moved into the core package, as it is used more commonly than just netclient (e.g. email, xml, mimetypes, pydoc). In addition, the ``pathlib`` module is now also part of the core package.
122
123- ``iptables``: ``iptables-apply`` and ``ip6tables-apply`` have been split out to their own package to avoid a bash dependency in the main ``iptables`` package
124
125
126.. _migration-3.2-package-qa-checks:
127
128Package QA check changes
129------------------------
130
131Previously, the following package QA checks triggered warnings, however they can
132be indicators of genuine underlying problems and are therefore now treated as
133errors:
134
135- :ref:`already-stripped <qa-check-already-stripped>`
136- :ref:`compile-host-path <qa-check-compile-host-path>`
137- :ref:`installed-vs-shipped <qa-check-installed-vs-shipped>`
138- :ref:`ldflags <qa-check-ldflags>`
139- :ref:`pn-overrides <qa-check-pn-overrides>`
140- :ref:`rpaths <qa-check-rpaths>`
141- :ref:`staticdev <qa-check-staticdev>`
142- :ref:`unknown-configure-option <qa-check-unknown-configure-option>`
143- :ref:`useless-rpaths <qa-check-useless-rpaths>`
144
145In addition, the following new checks were added and default to triggering an error:
146
147- :ref:`shebang-size <qa-check-shebang-size>`: Check for shebang (#!) lines longer than 128 characters, which can give an error at runtime depending on the operating system.
148
149- :ref:`unhandled-features-check <qa-check-unhandled-features-check>`: Check if any of the variables supported by the :ref:`features_check <ref-classes-features_check>` class is set while not inheriting the class itself.
150
151- :ref:`missing-update-alternatives <qa-check-missing-update-alternatives>`: Check if the recipe sets the :term:`ALTERNATIVE` variable for any of its packages, and does not inherit the :ref:`update-alternatives <ref-classes-update-alternatives>` class.
152
153- A trailing slash or duplicated slashes in the value of :term:`S` or :term:`B` will now trigger a warning so that they can be removed and path comparisons can be more reliable - remove any instances of these in your recipes if the warning is displayed.
154
155
156.. _migration-3.2-src-uri-file-globbing:
157
158Globbing no longer supported in ``file://`` entries in ``SRC_URI``
159------------------------------------------------------------------
160
161Globbing (``*`` and ``?`` wildcards) in ``file://`` URLs within :term:`SRC_URI`
162did not properly support file checksums, thus changes to the source files
163would not always change the do_fetch task checksum, and consequently would
164not ensure that the changed files would be incorporated in subsequent builds.
165
166Unfortunately it is not practical to make globbing work generically here, so
167the decision was taken to remove support for globs in ``file://`` URLs.
168If you have any usage of these in your recipes, then you will now need to
169either add each of the files that you expect to match explicitly, or
170alternatively if you still need files to be pulled in dynamically, put the
171files into a subdirectory and reference that instead.
172
173
174.. _migration-3.2-deploydir-clean:
175
176deploy class now cleans ``DEPLOYDIR`` before ``do_deploy``
177----------------------------------------------------------
178
179``do_deploy`` as implemented in the :ref:`deploy <ref-classes-deploy>` class now cleans up ${:term:`DEPLOYDIR`} before running, just as ``do_install`` cleans up ${:term:`D`} before running. This reduces the risk of ``DEPLOYDIR`` being accidentally contaminated by files from previous runs, possibly even with different config, in case of incremental builds.
180
181Most recipes and classes that inherit the ``deploy`` class or interact with ``do_deploy`` are unlikely to be affected by this unless they add ``prefuncs`` to ``do_deploy`` *which also* put files into ``${DEPLOYDIR}`` - these should be refactored to use ``do_deploy_prepend`` instead.
182
183
184.. _migration-3.2-nativesdk-sdk-provides-dummy:
185
186Custom SDK / SDK-style recipes need to include ``nativesdk-sdk-provides-dummy``
187-------------------------------------------------------------------------------
188
189All ``nativesdk`` packages require ``/bin/sh`` due to their postinstall scriptlets, thus this package has to be dummy-provided within the SDK and ``nativesdk-sdk-provides-dummy`` now does this. If you have a custom SDK recipe (or your own SDK-style recipe similar to e.g. ``buildtools-tarball``), you will need to ensure ``nativesdk-sdk-provides-dummy`` or an equivalent is included in :term:`TOOLCHAIN_HOST_TASK`.
190
191
192``ld.so.conf`` now moved back to main ``glibc`` package
193-------------------------------------------------------
194
195There are cases where one doesn't want ``ldconfig`` on target (e.g. for
196read-only root filesystems, it's rather pointless), yet one still
197needs ``/etc/ld.so.conf`` to be present at image build time:
198
199When some recipe installs libraries to a non-standard location, and
200therefore installs in a file in ``/etc/ld.so.conf.d/foo.conf``, we
201need ``/etc/ld.so.conf`` containing: ::
202
203 include /etc/ld.so.conf.d/*.conf
204
205in order to get those other locations picked up.
206
207Thus ``/etc/ld.so.conf`` is now in the main ``glibc`` package so that
208there's always an ``ld.so.conf`` present when the build-time ``ldconfig``
209runs towards the end of image construction.
210
211The ``ld.so.conf`` and ``ld.so.conf.d/*.conf`` files do not take up
212significant space (at least not compared to the ~700kB ``ldconfig`` binary), and they
213might be needed in case ``ldconfig`` is installable, so they are left
214in place after the image is built. Technically it would be possible to
215remove them if desired, though it would not be trivial if you still
216wanted the build-time ldconfig to function (:term:`ROOTFS_POSTPROCESS_COMMAND`
217will not work as ``ldconfig`` is run after the functions referred to
218by that variable).
219
220
221.. _migration-3.2-virgl:
222
223Host DRI drivers now used for GL support within ``runqemu``
224-----------------------------------------------------------
225
226``runqemu`` now uses the mesa-native libraries everywhere virgl is used
227(i.e. when ``gl``, ``gl-es`` or ``egl-headless`` options are specified),
228but instructs them to load DRI drivers from the host. Unfortunately this
229may not work well with proprietary graphics drivers such as those from
230Nvidia; if you are using such drivers then you may need to switch to an
231alternative (such as Nouveau in the case of Nvidia hardware) or avoid
232using the GL options.
233
234
235.. _migration-3.2-initramfs-suffix:
236
237initramfs images now use a blank suffix
238---------------------------------------
239
240The reference initramfs images (``core-image-minimal-initramfs``,
241``core-image-tiny-initramfs`` and ``core-image-testmaster-initramfs``) now
242set an empty string for :term:`IMAGE_NAME_SUFFIX`, which otherwise defaults
243to ``".rootfs"``. These images aren't root filesystems and thus the rootfs
244label didn't make sense. If you are looking for the output files generated
245by these image recipes directly then you will need to adapt to the new
246naming without the ``.rootfs`` part.
247
248
249.. _migration-3.2-misc:
250
251Miscellaneous changes
252---------------------
253
254- Support for the long-deprecated ``PACKAGE_GROUP`` variable has now been removed - replace any remaining instances with :term:`FEATURE_PACKAGES`.
255- The ``FILESPATHPKG`` variable, having been previously deprecated, has now been removed. Replace any remaining references with appropriate use of :term:`FILESEXTRAPATHS`.
256- Erroneous use of ``inherit +=`` (instead of ``INHERIT +=``) in a configuration file now triggers an error instead of silently being ignored.
257- ptest support has been removed from the ``kbd`` recipe, as upstream has moved to autotest which is difficult to work with in a cross-compilation environment.
258- ``oe.utils.is_machine_specific()`` and ``oe.utils.machine_paths()`` have been removed as their utility was questionable. In the unlikely event that you have references to these in your own code, then the code will need to be reworked.
259- The ``i2ctransfer`` module is now disabled by default when building ``busybox`` in order to be consistent with disabling the other i2c tools there. If you do wish the i2ctransfer module to be built in busybox then add ``CONFIG_I2CTRANSFER=y`` to your custom busybox configuration.
260- In the ``Upstream-Status`` header convention for patches, ``Accepted`` has been replaced with ``Backport`` as these almost always mean the same thing i.e. the patch is already upstream and may need to be removed in a future recipe upgrade. If you are adding these headers to your own patches then use ``Backport`` to indicate that the patch has been sent upstream.
261- The ``tune-supersparc.inc`` tune file has been removed as it does not appear to be widely used and no longer works.
diff --git a/documentation/ref-manual/migration.rst b/documentation/ref-manual/migration.rst
index 20288b0de8..8d64a7daab 100644
--- a/documentation/ref-manual/migration.rst
+++ b/documentation/ref-manual/migration.rst
@@ -27,4 +27,5 @@ notes for a given release.
27 migration-2.7 27 migration-2.7
28 migration-3.0 28 migration-3.0
29 migration-3.1 29 migration-3.1
30 migration-3.2
30 31