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