summaryrefslogtreecommitdiffstats
path: root/documentation/migration-guides/migration-2.5.rst
diff options
context:
space:
mode:
authorMichael Opdenacker <michael.opdenacker@bootlin.com>2021-06-10 11:26:21 +0200
committerRichard Purdie <richard.purdie@linuxfoundation.org>2021-06-14 22:45:33 +0100
commit5f978a6ccacf9f7f9475207c5a2a1af1dc4c3d00 (patch)
treefa7ba7ced9e17426b72e07c50288163a5d8ba901 /documentation/migration-guides/migration-2.5.rst
parentdae1e986a0608d899f67f1ae62389d350824235f (diff)
downloadpoky-5f978a6ccacf9f7f9475207c5a2a1af1dc4c3d00.tar.gz
ref-manual: move migration guides to separate document
This makes the reference manual much lighter by moving the migration guides to a separate document. The migration guides are also reordered from last to first, and they appear directly in the left bar, making them easier to find in the documentation. (From yocto-docs rev: 5121b86ee97eb62a0c69c9ad1fc0e3fabbe3e934) Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/migration-guides/migration-2.5.rst')
-rw-r--r--documentation/migration-guides/migration-2.5.rst308
1 files changed, 308 insertions, 0 deletions
diff --git a/documentation/migration-guides/migration-2.5.rst b/documentation/migration-guides/migration-2.5.rst
new file mode 100644
index 0000000000..c7e0760463
--- /dev/null
+++ b/documentation/migration-guides/migration-2.5.rst
@@ -0,0 +1,308 @@
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 ``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 ``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 ``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 ``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 ``IMAGE_FSTYPES``.
282
283- Recipes with an unconditional dependency on ``libpam`` are only
284 buildable with ``pam`` in ``DISTRO_FEATURES``. If the dependency is
285 truly optional then it is recommended that the dependency be
286 conditional upon ``pam`` being in ``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 rootfs 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