1.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
2
3Release 2.5 (sumo)
4==================
5
6This section provides migration information for moving to the Yocto
7Project 2.5 Release (codename "sumo") from the prior release.
8
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
142   :ref:`ref-classes-archiver` classes). There is a BitBake option to complete this for
143   any arbitrary task. For example::
144
145      bitbake <target> -c fetchall
146
147   should now be replaced with::
148
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
172expected::
173
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
182change please see :yocto_git:`this commit
183</poky/commit/?id=8d94b9db221d1def42f091b991903faa2d1651ce>`.
184
185.. _migration-2.5-miscellaneous-changes:
186
187Miscellaneous Changes
188---------------------
189
190The following are additional changes:
191
192-  The :ref:`ref-classes-kernel` class supports building packages for multiple kernels.
193   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
200-  The :ref:`ref-classes-buildhistory` class commits changes to the repository by
201   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
212-  The :ref:`ref-classes-update-alternatives` class no longer works with SysV ``init``
213   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
217-  By default, the :ref:`ref-classes-cmake` class uses
218   ``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``)
266   will trigger a warning during :ref:`ref-tasks-rootfs`.
267
268   For more information, see the
269   ":ref:`dev-manual/new-recipe:post-installation scripts`"
270   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
283   :term:`IMAGE_FSTYPES`.
284
285-  Recipes with an unconditional dependency on ``libpam`` are only
286   buildable with ``pam`` in :term:`DISTRO_FEATURES`. If the dependency is
287   truly optional then it is recommended that the dependency be
288   conditional upon ``pam`` being in :term:`DISTRO_FEATURES`.
289
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
292   bootloader into separate boot and root filesystem partitions if necessary.
293
294-  Patches whose context does not match exactly (i.e. where patch
295   reports "fuzz" when applying) will generate a warning. For an example
296   of this see :yocto_git:`this commit
297   </poky/commit/?id=cc97bc08125b63821ce3f616771830f77c456f57>`.
298
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
311