blob: 9f089bb93ba7c30332f4d5fe2f15e717899c4957 [file] [log] [blame]
Andrew Geissler517393d2023-01-13 08:55:19 -06001.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
2
Andrew Geissler09036742021-06-25 14:25:14 -05003Release 2.5 (sumo)
4==================
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005
6This section provides migration information for moving to the Yocto
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05007Project 2.5 Release (codename "sumo") from the prior release.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008
9.. _migration-2.5-packaging-changes:
10
11Packaging Changes
12-----------------
13
14This section provides information about packaging changes that have
15occurred:
16
17- ``bind-libs``: The libraries packaged by the bind recipe are in a
18 separate ``bind-libs`` package.
19
20- ``libfm-gtk``: The ``libfm`` GTK+ bindings are split into a
21 separate ``libfm-gtk`` package.
22
23- ``flex-libfl``: The flex recipe splits out libfl into a separate
24 ``flex-libfl`` package to avoid too many dependencies being pulled in
25 where only the library is needed.
26
27- ``grub-efi``: The ``grub-efi`` configuration is split into a
28 separate ``grub-bootconf`` recipe. However, the dependency
29 relationship from ``grub-efi`` is through a virtual/grub-bootconf
30 provider making it possible to have your own recipe provide the
31 dependency. Alternatively, you can use a BitBake append file to bring
32 the configuration back into the ``grub-efi`` recipe.
33
34- *armv7a Legacy Package Feed Support:* Legacy support is removed for
35 transitioning from ``armv7a`` to ``armv7a-vfp-neon`` in package
36 feeds, which was previously enabled by setting
37 ``PKGARCHCOMPAT_ARMV7A``. This transition occurred in 2011 and active
38 package feeds should by now be updated to the new naming.
39
40.. _migration-2.5-removed-recipes:
41
42Removed Recipes
43---------------
44
45The following recipes have been removed:
46
47- ``gcc``: The version 6.4 recipes are replaced by 7.x.
48
49- ``gst-player``: Renamed to ``gst-examples`` as per upstream.
50
51- ``hostap-utils``: This software package is obsolete.
52
53- ``latencytop``: This recipe is no longer maintained upstream. The
54 last release was in 2009.
55
56- ``libpfm4``: The only file that requires this recipe is
57 ``oprofile``, which has been removed.
58
59- ``linux-yocto``: The version 4.4, 4.9, and 4.10 recipes have been
60 removed. Versions 4.12, 4.14, and 4.15 remain.
61
62- ``man``: This recipe has been replaced by modern ``man-db``
63
64- ``mkelfimage``: This tool has been removed in the upstream coreboot
65 project, and is no longer needed with the removal of the ELF image
66 type.
67
68- ``nativesdk-postinst-intercept``: This recipe is not maintained.
69
70- ``neon``: This software package is no longer maintained upstream
71 and is no longer needed by anything in OpenEmbedded-Core.
72
73- ``oprofile``: The functionality of this recipe is replaced by
74 ``perf`` and keeping compatibility on an ongoing basis with ``musl``
75 is difficult.
76
77- ``pax``: This software package is obsolete.
78
79- ``stat``: This software package is not maintained upstream.
80 ``coreutils`` provides a modern stat binary.
81
82- ``zisofs-tools-native``: This recipe is no longer needed because
83 the compressed ISO image feature has been removed.
84
85.. _migration-2.5-scripts-and-tools-changes:
86
87Scripts and Tools Changes
88-------------------------
89
90The following are changes to scripts and tools:
91
92- ``yocto-bsp``, ``yocto-kernel``, and ``yocto-layer``: The
93 ``yocto-bsp``, ``yocto-kernel``, and ``yocto-layer`` scripts
94 previously shipped with poky but not in OpenEmbedded-Core have been
95 removed. These scripts are not maintained and are outdated. In many
96 cases, they are also limited in scope. The
97 ``bitbake-layers create-layer`` command is a direct replacement for
98 ``yocto-layer``. See the documentation to create a BSP or kernel
99 recipe in the ":ref:`bsp-guide/bsp:bsp kernel recipe example`" section.
100
101- ``devtool finish``: ``devtool finish`` now exits with an error if
102 there are uncommitted changes or a rebase/am in progress in the
103 recipe's source repository. If this error occurs, there might be
104 uncommitted changes that will not be included in updates to the
105 patches applied by the recipe. A -f/--force option is provided for
106 situations that the uncommitted changes are inconsequential and you
107 want to proceed regardless.
108
109- ``scripts/oe-setup-rpmrepo`` script: The functionality of
110 ``scripts/oe-setup-rpmrepo`` is replaced by
111 ``bitbake package-index``.
112
113- ``scripts/test-dependencies.sh`` script: The script is largely made
114 obsolete by the recipe-specific sysroots functionality introduced in
115 the previous release.
116
117.. _migration-2.5-bitbake-changes:
118
119BitBake Changes
120---------------
121
122The following are BitBake changes:
123
124- The ``--runall`` option has changed. There are two different
125 behaviors people might want:
126
127 - *Behavior A:* For a given target (or set of targets) look through
128 the task graph and run task X only if it is present and will be
129 built.
130
131 - *Behavior B:* For a given target (or set of targets) look through
132 the task graph and run task X if any recipe in the taskgraph has
133 such a target, even if it is not in the original task graph.
134
135 The ``--runall`` option now performs "Behavior B". Previously
136 ``--runall`` behaved like "Behavior A". A ``--runonly`` option has
137 been added to retain the ability to perform "Behavior A".
138
139- Several explicit "run this task for all recipes in the dependency
140 tree" tasks have been removed (e.g. ``fetchall``, ``checkuriall``,
141 and the ``*all`` tasks provided by the ``distrodata`` and
Andrew Geissler517393d2023-01-13 08:55:19 -0600142 :ref:`ref-classes-archiver` classes). There is a BitBake option to complete this for
Andrew Geisslerc926e172021-05-07 16:11:35 -0500143 any arbitrary task. For example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500144
145 bitbake <target> -c fetchall
146
Andrew Geisslerc926e172021-05-07 16:11:35 -0500147 should now be replaced with::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500148
149 bitbake <target> --runall=fetch
150
151.. _migration-2.5-python-and-python3-changes:
152
153Python and Python 3 Changes
154---------------------------
155
156The following are auto-packaging changes to Python and Python 3:
157
158The script-managed ``python-*-manifest.inc`` files that were previously
159used to generate Python and Python 3 packages have been replaced with a
160JSON-based file that is easier to read and maintain. A new task is
161available for maintainers of the Python recipes to update the JSON file
162when upgrading to new Python versions. You can now edit the file
163directly instead of having to edit a script and run it to update the
164file.
165
166One particular change to note is that the Python recipes no longer have
167build-time provides for their packages. This assumes ``python-foo`` is
168one of the packages provided by the Python recipe. You can no longer run
169``bitbake python-foo`` or have a
170:term:`DEPENDS` on ``python-foo``,
171but doing either of the following causes the package to work as
Andrew Geisslerc926e172021-05-07 16:11:35 -0500172expected::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500173
174 IMAGE_INSTALL_append = " python-foo"
175
176or ::
177
178 RDEPENDS_${PN} = "python-foo"
179
180The earlier build-time provides behavior was a quirk of the
181way the Python manifest file was created. For more information on this
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500182change please see :yocto_git:`this commit
Andrew Geissler09209ee2020-12-13 08:44:15 -0600183</poky/commit/?id=8d94b9db221d1def42f091b991903faa2d1651ce>`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500184
185.. _migration-2.5-miscellaneous-changes:
186
187Miscellaneous Changes
188---------------------
189
190The following are additional changes:
191
Andrew Geissler517393d2023-01-13 08:55:19 -0600192- The :ref:`ref-classes-kernel` class supports building packages for multiple kernels.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500193 If your kernel recipe or ``.bbappend`` file mentions packaging at
194 all, you should replace references to the kernel in package names
195 with ``${KERNEL_PACKAGE_NAME}``. For example, if you disable
196 automatic installation of the kernel image using
197 ``RDEPENDS_kernel-base = ""`` you can avoid warnings using
198 ``RDEPENDS_${KERNEL_PACKAGE_NAME}-base = ""`` instead.
199
Andrew Geissler517393d2023-01-13 08:55:19 -0600200- The :ref:`ref-classes-buildhistory` class commits changes to the repository by
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500201 default so you no longer need to set ``BUILDHISTORY_COMMIT = "1"``.
202 If you want to disable commits you need to set
203 ``BUILDHISTORY_COMMIT = "0"`` in your configuration.
204
205- The ``beaglebone`` reference machine has been renamed to
206 ``beaglebone-yocto``. The ``beaglebone-yocto`` BSP is a reference
207 implementation using only mainline components available in
208 OpenEmbedded-Core and ``meta-yocto-bsp``, whereas Texas Instruments
209 maintains a full-featured BSP in the ``meta-ti`` layer. This rename
210 avoids the previous name clash that existed between the two BSPs.
211
Andrew Geissler517393d2023-01-13 08:55:19 -0600212- The :ref:`ref-classes-update-alternatives` class no longer works with SysV ``init``
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500213 scripts because this usage has been problematic. Also, the
214 ``sysklogd`` recipe no longer uses ``update-alternatives`` because it
215 is incompatible with other implementations.
216
Andrew Geissler517393d2023-01-13 08:55:19 -0600217- By default, the :ref:`ref-classes-cmake` class uses
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500218 ``ninja`` instead of ``make`` for building. This improves build
219 performance. If a recipe is broken with ``ninja``, then the recipe
220 can set ``OECMAKE_GENERATOR = "Unix Makefiles"`` to change back to
221 ``make``.
222
223- The previously deprecated ``base_*`` functions have been removed in
224 favor of their replacements in ``meta/lib/oe`` and
225 ``bitbake/lib/bb``. These are typically used from recipes and
226 classes. Any references to the old functions must be updated. The
227 following table shows the removed functions and their replacements:
228
229 +------------------------------+----------------------------------------------------------+
230 | *Removed* | *Replacement* |
231 +==============================+==========================================================+
232 | base_path_join() | oe.path.join() |
233 +------------------------------+----------------------------------------------------------+
234 | base_path_relative() | oe.path.relative() |
235 +------------------------------+----------------------------------------------------------+
236 | base_path_out() | oe.path.format_display() |
237 +------------------------------+----------------------------------------------------------+
238 | base_read_file() | oe.utils.read_file() |
239 +------------------------------+----------------------------------------------------------+
240 | base_ifelse() | oe.utils.ifelse() |
241 +------------------------------+----------------------------------------------------------+
242 | base_conditional() | oe.utils.conditional() |
243 +------------------------------+----------------------------------------------------------+
244 | base_less_or_equal() | oe.utils.less_or_equal() |
245 +------------------------------+----------------------------------------------------------+
246 | base_version_less_or_equal() | oe.utils.version_less_or_equal() |
247 +------------------------------+----------------------------------------------------------+
248 | base_contains() | bb.utils.contains() |
249 +------------------------------+----------------------------------------------------------+
250 | base_both_contain() | oe.utils.both_contain() |
251 +------------------------------+----------------------------------------------------------+
252 | base_prune_suffix() | oe.utils.prune_suffix() |
253 +------------------------------+----------------------------------------------------------+
254 | oe_filter() | oe.utils.str_filter() |
255 +------------------------------+----------------------------------------------------------+
256 | oe_filter_out() | oe.utils.str_filter_out() (or use the \_remove operator) |
257 +------------------------------+----------------------------------------------------------+
258
259- Using ``exit 1`` to explicitly defer a postinstall script until first
260 boot is now deprecated since it is not an obvious mechanism and can
261 mask actual errors. If you want to explicitly defer a postinstall to
262 first boot on the target rather than at ``rootfs`` creation time, use
263 ``pkg_postinst_ontarget()`` or call
264 ``postinst_intercept delay_to_first_boot`` from ``pkg_postinst()``.
265 Any failure of a ``pkg_postinst()`` script (including ``exit 1``)
Patrick Williams2194f502022-10-16 14:26:09 -0500266 will trigger a warning during :ref:`ref-tasks-rootfs`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500267
268 For more information, see the
Andrew Geissler517393d2023-01-13 08:55:19 -0600269 ":ref:`dev-manual/new-recipe:post-installation scripts`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500270 section in the Yocto Project Development Tasks Manual.
271
272- The ``elf`` image type has been removed. This image type was removed
273 because the ``mkelfimage`` tool that was required to create it is no
274 longer provided by coreboot upstream and required updating every time
275 ``binutils`` updated.
276
277- Support for .iso image compression (previously enabled through
278 ``COMPRESSISO = "1"``) has been removed. The userspace tools
279 (``zisofs-tools``) are unmaintained and ``squashfs`` provides better
280 performance and compression. In order to build a live image with
281 squashfs+lz4 compression enabled you should now set
282 ``LIVE_ROOTFS_TYPE = "squashfs-lz4"`` and ensure that ``live`` is in
Andrew Geissler5f350902021-07-23 13:09:54 -0400283 :term:`IMAGE_FSTYPES`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500284
285- Recipes with an unconditional dependency on ``libpam`` are only
Andrew Geissler09036742021-06-25 14:25:14 -0500286 buildable with ``pam`` in :term:`DISTRO_FEATURES`. If the dependency is
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500287 truly optional then it is recommended that the dependency be
Andrew Geissler5f350902021-07-23 13:09:54 -0400288 conditional upon ``pam`` being in :term:`DISTRO_FEATURES`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500289
290- For EFI-based machines, the bootloader (``grub-efi`` by default) is
291 installed into the image at /boot. Wic can be used to split the
Andrew Geissler595f6302022-01-24 19:11:47 +0000292 bootloader into separate boot and root filesystem partitions if necessary.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500293
294- Patches whose context does not match exactly (i.e. where patch
295 reports "fuzz" when applying) will generate a warning. For an example
Andrew Geissler09209ee2020-12-13 08:44:15 -0600296 of this see :yocto_git:`this commit
297 </poky/commit/?id=cc97bc08125b63821ce3f616771830f77c456f57>`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500298
299- Layers are expected to set ``LAYERSERIES_COMPAT_layername`` to match
300 the version(s) of OpenEmbedded-Core they are compatible with. This is
301 specified as codenames using spaces to separate multiple values (e.g.
302 "rocko sumo"). If a layer does not set
303 ``LAYERSERIES_COMPAT_layername``, a warning will is shown. If a layer
304 sets a value that does not include the current version ("sumo" for
305 the 2.5 release), then an error will be produced.
306
307- The ``TZ`` environment variable is set to "UTC" within the build
308 environment in order to fix reproducibility problems in some recipes.
309
310