diff options
Diffstat (limited to 'documentation/migration-guides/migration-4.1.rst')
-rw-r--r-- | documentation/migration-guides/migration-4.1.rst | 214 |
1 files changed, 214 insertions, 0 deletions
diff --git a/documentation/migration-guides/migration-4.1.rst b/documentation/migration-guides/migration-4.1.rst new file mode 100644 index 0000000000..bb8c6dd697 --- /dev/null +++ b/documentation/migration-guides/migration-4.1.rst | |||
@@ -0,0 +1,214 @@ | |||
1 | Release 4.1 (langdale) | ||
2 | ====================== | ||
3 | |||
4 | Migration notes for 4.1 (langdale) | ||
5 | ----------------------------------- | ||
6 | |||
7 | This section provides migration information for moving to the Yocto | ||
8 | Project 4.1 Release (codename "langdale") from the prior release. | ||
9 | |||
10 | |||
11 | .. _migration-4.1-make-4.0: | ||
12 | |||
13 | make 4.0 is now the minimum required make version | ||
14 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
15 | |||
16 | glibc now requires ``make`` 4.0 to build, thus it is now the version required to | ||
17 | be installed on the build host. A new ``buildtools-make-tarball`` has been | ||
18 | introduced to provide just make 4.0 for host distros without a current/working | ||
19 | make 4.x version; if you also need other tools you can use the updated | ||
20 | ``buildtools-tarball``. For more information see | ||
21 | :ref:`ref-manual/system-requirements:required packages for the build host`. | ||
22 | |||
23 | |||
24 | .. _migration-4.1-complementary-deps: | ||
25 | |||
26 | Complementary package installation ignores recommends | ||
27 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
28 | |||
29 | When installing complementary packages (e.g. ``-dev`` and ``-dbg`` packages when | ||
30 | building an SDK, or if you have added ``dev-deps`` to :term:`IMAGE_FEATURES`), | ||
31 | recommends (as defined by :term:`RRECOMMENDS`) are no longer installed. | ||
32 | |||
33 | If you wish to double-check the contents of your images after this change, see | ||
34 | :ref:`Checking Image / SDK Changes <migration-general-buildhistory>`. If needed | ||
35 | you can explicitly install items by adding them to :term:`IMAGE_INSTALL` in | ||
36 | image recipes or :term:`TOOLCHAIN_TARGET_TASK` for the SDK. | ||
37 | |||
38 | |||
39 | .. _migration-4.1-dev-recommends: | ||
40 | |||
41 | dev dependencies are now recommends | ||
42 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
43 | |||
44 | The default for ``${PN}-dev`` package is now to use :term:`RRECOMMENDS` instead | ||
45 | of :term:`RDEPENDS` to pull in the main package. This takes advantage of a | ||
46 | change to complimentary package installation to not follow :term:`RRECOMMENDS` | ||
47 | (as mentioned above) and for example means an SDK for an image with both openssh | ||
48 | and dropbear components will now build successfully. | ||
49 | |||
50 | |||
51 | .. _migration-4.1-dropbear-sftp: | ||
52 | |||
53 | dropbear now recommends openssh-sftp-server | ||
54 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
55 | |||
56 | openssh has switched the scp client to use the sftp protocol instead of scp to | ||
57 | move files. This means scp from Fedora 36 and other current distributions will | ||
58 | no longer be able to move files to/from a system running dropbear with no sftp | ||
59 | server installed. | ||
60 | |||
61 | The sftp server from openssh is small (200kb uncompressed) and standalone, so | ||
62 | adding it to the packagegroup seems to be the best way to preserve the | ||
63 | functionality for user sanity. However, if you wish to avoid this dependency, | ||
64 | you can either: | ||
65 | |||
66 | A. Use ``dropbear`` in :term:`IMAGE_INSTALL` instead of | ||
67 | ``packagegroup-core-ssh-dropbear`` (or ``ssh-server-dropbear`` in | ||
68 | :term:`IMAGE_FEATURES`), or | ||
69 | B. Add ``openssh-sftp-server`` to :term:`BAD_RECOMMENDATIONS`. | ||
70 | |||
71 | |||
72 | .. _migration-4.1-classes-split: | ||
73 | |||
74 | Classes now split by usage context | ||
75 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
76 | |||
77 | A split directory structure has now been set up for ``.bbclass`` files - classes | ||
78 | that are intended to be inherited only by recipes (e.g. ``inherit`` in a recipe | ||
79 | file, :term:`IMAGE_CLASSES` or :term:`KERNEL_CLASSES`) should be in a | ||
80 | ``classes-recipe`` subdirectory and classes that are intended to be inherited | ||
81 | globally (e.g. via ``INHERIT +=``, :term:`PACKAGE_CLASSES`, :term:`USER_CLASSES` | ||
82 | or :term:`INHERIT_DISTRO`) should be in ``classes-global``. Classes in the | ||
83 | existing ``classes`` subdirectory will continue to work in any context as before. | ||
84 | |||
85 | Other than knowing where to look when manually browsing the class files, this is | ||
86 | not likely to require any changes to your configuration. However, if in your | ||
87 | configuration you were using some classes in the incorrect context, you will now | ||
88 | receive an error during parsing. For example, the following in ``local.conf`` will | ||
89 | now cause an error:: | ||
90 | |||
91 | INHERIT += "testimage" | ||
92 | |||
93 | Since :ref:`testimage <ref-classes-testimage>` is a class intended solely to | ||
94 | affect image recipes, this would be correctly specified as:: | ||
95 | |||
96 | IMAGE_CLASSES += "testimage" | ||
97 | |||
98 | |||
99 | .. _migration-4.1-local-file-error: | ||
100 | |||
101 | Missing local files in SRC_URI now triggers an error | ||
102 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
103 | |||
104 | If a file referenced in :term:`SRC_URI` does not exist, in 4.1 this will trigger | ||
105 | an error at parse time where previously this only triggered a warning. In the past | ||
106 | you could ignore these warnings for example if you have multiple build | ||
107 | configurations (e.g. for several different target machines) and there were recipes | ||
108 | that you were not building in one of the configurations. If you have this scenario | ||
109 | you will now need to conditionally add entries to :term:`SRC_URI` where they are | ||
110 | valid, or use :term:`COMPATIBLE_MACHINE` / :term:`COMPATIBLE_HOST` to prevent the | ||
111 | recipe from being available (and therefore avoid it being parsed) in configurations | ||
112 | where the files aren't available. | ||
113 | |||
114 | |||
115 | .. _migration-4.1-qa-checks: | ||
116 | |||
117 | QA check changes | ||
118 | ~~~~~~~~~~~~~~~~ | ||
119 | |||
120 | - The :ref:`buildpaths <qa-check-buildpaths>` QA check is now enabled by default | ||
121 | in :term:`WARN_QA`, and thus any build system paths found in output files will | ||
122 | trigger a warning. If you see these warnings for your own recipes, for full | ||
123 | binary reproducibility you should make the necessary changes to the recipe build | ||
124 | to remove these paths. If you wish to disable the warning for a particular | ||
125 | recipe you can use :term:`INSANE_SKIP`, or for the entire build you can adjust | ||
126 | :term:`WARN_QA`. For more information, see the :ref:`buildpaths QA check | ||
127 | <qa-check-buildpaths>` section. | ||
128 | |||
129 | - ``do_qa_staging`` now checks shebang length in all directories specified by | ||
130 | :term:`SYSROOT_DIRS`, since there is a maximum length defined in the kernel. For | ||
131 | native recipes which write scripts to the sysroot, if the shebang line in one of | ||
132 | these scripts is too long you will get an error. This can be skipped using | ||
133 | :term:`INSANE_SKIP` if necessary, but the best course of action is of course to | ||
134 | fix the script. There is now also a ``create_cmdline_shebang_wrapper`` function | ||
135 | that you can call e.g. from ``do_install`` (or ``do_install:append``) within a | ||
136 | recipe to create a wrapper to fix such scripts - see the ``libcheck`` recipe | ||
137 | for an example usage. | ||
138 | |||
139 | |||
140 | |||
141 | Miscellaneous changes | ||
142 | ~~~~~~~~~~~~~~~~~~~~~ | ||
143 | |||
144 | - ``mount.blacklist`` has been renamed to ``mount.ignorelist`` in | ||
145 | ``udev-extraconf``. If you are customising this file via ``udev-extraconf`` then | ||
146 | you will need to update your ``udev-extraconf`` ``.bbappend`` as appropriate. | ||
147 | - ``help2man-native`` has been removed from implicit sysroot dependencies. If a | ||
148 | recipe needs ``help2man-native`` it should now be explicitly added to | ||
149 | :term:`DEPENDS` within the recipe. | ||
150 | - For images using systemd, the reboot watchdog timeout has been set to 60 | ||
151 | seconds (from the upstream default of 10 minutes). If you wish to override this | ||
152 | you can set :term:`WATCHDOG_TIMEOUT` to the desired timeout in seconds. Note | ||
153 | that the same :term:`WATCHDOG_TIMEOUT` variable also specifies the timeout used | ||
154 | for the ``watchdog`` tool (if that is being built). | ||
155 | - The :ref:`image-buildinfo <ref-classes-image-buildinfo>` class now writes to | ||
156 | ``${sysconfdir}/buildinfo`` instead of ``${sysconfdir}/build`` by default (i.e. | ||
157 | the default value of :term:`IMAGE_BUILDINFO_FILE` has been changed). If you have | ||
158 | code that reads this from images at build or runtime you will need to update it | ||
159 | or specify your own value for :term:`IMAGE_BUILDINFO_FILE`. | ||
160 | - In the :ref:`archiver <ref-classes-archiver>` class, the default | ||
161 | ``ARCHIVER_OUTDIR`` value no longer includes the :term:`MACHINE` value in order | ||
162 | to avoid the archive task running multiple times in a multiconfig setup. If you | ||
163 | have custom code that does something with the files archived by the | ||
164 | :ref:`archiver <ref-classes-archiver>` class then you may need to adjust it to | ||
165 | the new structure. | ||
166 | - If you are not using `systemd` then udev is now configured to use labels | ||
167 | (``LABEL`` or ``PARTLABEL``) to set the mount point for the device. For example:: | ||
168 | |||
169 | /run/media/rootfs-sda2 | ||
170 | |||
171 | instead of:: | ||
172 | |||
173 | /run/media/sda2 | ||
174 | |||
175 | - ``icu`` no longer provides the ``icu-config`` configuration tool - upstream | ||
176 | have indicated ``icu-config`` is deprecated and should no longer be used. Code | ||
177 | with references to it will need to be updated, for example to use ``pkg-config`` | ||
178 | instead. | ||
179 | - The ``rng-tools`` systemd service name has changed from ``rngd`` to ``rng-tools`` | ||
180 | - The ``largefile`` :term:`DISTRO_FEATURES` item has been removed, large file | ||
181 | support is now always enabled where it was previously optional. | ||
182 | - The Python ``zoneinfo`` module is now split out to its own ``python3-zoneinfo`` | ||
183 | package. | ||
184 | - The :term:`PACKAGECONFIG` option to enable wpa_supplicant in the ``connman`` | ||
185 | recipe has been renamed to "wpa-supplicant". If you have set PACKAGECONFIG for | ||
186 | the ``connman`` recipe to include this option you will need to update | ||
187 | your configuration. Related to this, the :term:`WIRELESS_DAEMON` variable | ||
188 | now expects the new ``wpa-supplicant`` naming and affects ``packagegroup-base`` | ||
189 | as well as ``connman``. | ||
190 | - The ``wpa-supplicant`` recipe no longer uses a static (and stale) ``defconfig`` | ||
191 | file, instead it uses the upstream version with appropriate edits for the | ||
192 | :term:`PACKAGECONFIG`. If you are customising this file you will need to | ||
193 | update your customisations. | ||
194 | - With the introduction of picobuild in | ||
195 | :ref:`python_pep517 <ref-classes-python_pep517>`, The ``PEP517_BUILD_API`` | ||
196 | variable is no longer supported. If you have any references to this variable | ||
197 | you should remove them. | ||
198 | |||
199 | |||
200 | .. _migration-4.1-removed-recipes: | ||
201 | |||
202 | Removed recipes | ||
203 | ~~~~~~~~~~~~~~~ | ||
204 | |||
205 | The following recipes have been removed in this release: | ||
206 | |||
207 | - ``alsa-utils-scripts``: merged into alsa-utils | ||
208 | - ``cargo-cross-canadian``: optimised out | ||
209 | - ``lzop``: obsolete, unmaintained upstream | ||
210 | - ``linux-yocto (5.10)``: 5.15 and 5.19 are currently provided | ||
211 | - ``rust-cross``: optimised out | ||
212 | - ``rust-crosssdk``: optimised out | ||
213 | - ``rust-tools-cross-canadian``: optimised out | ||
214 | - ``xf86-input-keyboard``: obsolete (replaced by libinput/evdev) | ||