blob: 54358351029fa12af704dd0f94098c4549f285e8 [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.2 (morty)
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.2 Release (codename "morty") from the prior release.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008
9.. _migration-2.2-minimum-kernel-version:
10
11Minimum Kernel Version
12----------------------
13
14The minimum kernel version for the target system and for SDK is now
153.2.0, due to the upgrade to ``glibc 2.24``. Specifically, for
16AArch64-based targets the version is 3.14. For Nios II-based targets,
17the minimum kernel version is 3.19.
18
19.. note::
20
Andrew Geissler4c19ea12020-10-27 13:52:24 -050021 For x86 and x86_64, you can reset :term:`OLDEST_KERNEL`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050022 to anything down to 2.6.32 if desired.
23
24.. _migration-2.2-staging-directories-in-sysroot-simplified:
25
26Staging Directories in Sysroot Has Been Simplified
27--------------------------------------------------
28
29The way directories are staged in sysroot has been simplified and
30introduces the new :term:`SYSROOT_DIRS`,
Andrew Geissler9aee5002022-03-30 16:27:02 +000031:term:`SYSROOT_DIRS_NATIVE`, and ``SYSROOT_DIRS_BLACKLIST``
32(replaced by :term:`SYSROOT_DIRS_IGNORE` in version 3.5). See the
Andrew Geisslerd1e89492021-02-12 15:35:20 -060033:oe_lists:`v2 patch series on the OE-Core Mailing List
34</pipermail/openembedded-core/2016-May/121365.html>`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050035for additional information.
36
37.. _migration-2.2-removal-of-old-images-from-tmp-deploy-now-enabled:
38
39Removal of Old Images and Other Files in ``tmp/deploy`` Now Enabled
40-------------------------------------------------------------------
41
42Removal of old images and other files in ``tmp/deploy/`` is now enabled
43by default due to a new staging method used for those files. As a result
44of this change, the ``RM_OLD_IMAGE`` variable is now redundant.
45
46.. _migration-2.2-python-changes:
47
48Python Changes
49--------------
50
51The following changes for Python occurred:
52
53.. _migration-2.2-bitbake-now-requires-python-3.4:
54
55BitBake Now Requires Python 3.4+
56~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
57
58BitBake requires Python 3.4 or greater.
59
60.. _migration-2.2-utf-8-locale-required-on-build-host:
61
62UTF-8 Locale Required on Build Host
63~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
64
65A UTF-8 locale is required on the build host due to Python 3. Since
66C.UTF-8 is not a standard, the default is en_US.UTF-8.
67
68.. _migration-2.2-metadata-now-must-use-python-3-syntax:
69
70Metadata Must Now Use Python 3 Syntax
71~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
72
73The metadata is now required to use Python 3 syntax. For help preparing
74metadata, see any of the many Python 3 porting guides available.
Andrew Geisslerd5838332022-05-27 11:33:10 -050075Alternatively, you can reference the conversion commits for BitBake and
Andrew Geisslerc9f78652020-09-18 14:11:35 -050076you can use :term:`OpenEmbedded-Core (OE-Core)` as a guide for changes. Following are
77particular areas of interest:
78
79 - subprocess command-line pipes needing locale decoding
80
81 - the syntax for octal values changed
82
Andrew Geissler4c19ea12020-10-27 13:52:24 -050083 - the ``iter*()`` functions changed name
84
85 - iterators now return views, not lists
Andrew Geisslerc9f78652020-09-18 14:11:35 -050086
87 - changed names for Python modules
88
89.. _migration-2.2-target-python-recipes-switched-to-python-3:
90
91Target Python Recipes Switched to Python 3
92~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
93
94Most target Python recipes have now been switched to Python 3.
95Unfortunately, systems using RPM as a package manager and providing
96online package-manager support through SMART still require Python 2.
97
98.. note::
99
100 Python 2 and recipes that use it can still be built for the target as
101 with previous versions.
102
103.. _migration-2.2-buildtools-tarball-includes-python-3:
104
105``buildtools-tarball`` Includes Python 3
106~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
107
Andrew Geissler517393d2023-01-13 08:55:19 -0600108The :term:`buildtools` tarball now includes Python 3.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500109
110.. _migration-2.2-uclibc-replaced-by-musl:
111
112uClibc Replaced by musl
113-----------------------
114
115uClibc has been removed in favor of musl. Musl has matured, is better
116maintained, and is compatible with a wider range of applications as
117compared to uClibc.
118
119.. _migration-2.2-B-no-longer-default-working-directory-for-tasks:
120
121``${B}`` No Longer Default Working Directory for Tasks
122------------------------------------------------------
123
Andrew Geisslerfc113ea2023-03-31 09:59:46 -0500124``${``\ :term:`B`\ ``}`` is no longer the default working directory for tasks.
125Consequently, any custom tasks you define now need to either have the
126``[``\ :ref:`dirs <bitbake-user-manual/bitbake-user-manual-metadata:variable flags>`\ ``]``
127flag set, or the task needs to change into the appropriate working directory
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500128manually (e.g using ``cd`` for a shell task).
129
130.. note::
131
132 The preferred method is to use the
133 [dirs]
134 flag.
135
136.. _migration-2.2-runqemu-ported-to-python:
137
138``runqemu`` Ported to Python
139----------------------------
140
141``runqemu`` has been ported to Python and has changed behavior in some
142cases. Previous usage patterns continue to be supported.
143
144The new ``runqemu`` is a Python script. Machine knowledge is no longer
145hardcoded into ``runqemu``. You can choose to use the ``qemuboot``
146configuration file to define the BSP's own arguments and to make it
147bootable with ``runqemu``. If you use a configuration file, use the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500148following form::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500149
150 image-name-machine.qemuboot.conf
151
152The configuration file
153enables fine-grained tuning of options passed to QEMU without the
154``runqemu`` script hard-coding any knowledge about different machines.
155Using a configuration file is particularly convenient when trying to use
156QEMU with machines other than the ``qemu*`` machines in
157:term:`OpenEmbedded-Core (OE-Core)`. The ``qemuboot.conf`` file is generated by the
Andrew Geissler595f6302022-01-24 19:11:47 +0000158``qemuboot`` class when the root filesystem is being built (i.e. build
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500159rootfs). QEMU boot arguments can be set in BSP's configuration file and
160the ``qemuboot`` class will save them to ``qemuboot.conf``.
161
162If you want to use ``runqemu`` without a configuration file, use the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500163following command form::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500164
165 $ runqemu machine rootfs kernel [options]
166
167Supported machines are as follows:
168
169 - qemuarm
170 - qemuarm64
171 - qemux86
172 - qemux86-64
173 - qemuppc
174 - qemumips
175 - qemumips64
176 - qemumipsel
177 - qemumips64el
178
179Consider the
180following example, which uses the ``qemux86-64`` machine, provides a
Andrew Geisslerc926e172021-05-07 16:11:35 -0500181root filesystem, provides an image, and uses the ``nographic`` option::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500182
183 $ runqemu qemux86-64 tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64.ext4 tmp/deploy/images/qemux86-64/bzImage nographic
184
185Following is a list of variables that can be set in configuration files
Andrew Geissler517393d2023-01-13 08:55:19 -0600186such as ``bsp.conf`` to enable the BSP to be booted by ``runqemu``::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500187
188 QB_SYSTEM_NAME: QEMU name (e.g. "qemu-system-i386")
189 QB_OPT_APPEND: Options to append to QEMU (e.g. "-show-cursor")
190 QB_DEFAULT_KERNEL: Default kernel to boot (e.g. "bzImage")
191 QB_DEFAULT_FSTYPE: Default FSTYPE to boot (e.g. "ext4")
192 QB_MEM: Memory (e.g. "-m 512")
193 QB_MACHINE: QEMU machine (e.g. "-machine virt")
194 QB_CPU: QEMU cpu (e.g. "-cpu qemu32")
195 QB_CPU_KVM: Similar to QB_CPU except used for kvm support (e.g. "-cpu kvm64")
196 QB_KERNEL_CMDLINE_APPEND: Options to append to the kernel's -append
197 option (e.g. "console=ttyS0 console=tty")
198 QB_DTB: QEMU dtb name
199 QB_AUDIO_DRV: QEMU audio driver (e.g. "alsa", set it when support audio)
200 QB_AUDIO_OPT: QEMU audio option (e.g. "-soundhw ac97,es1370"), which is used
201 when QB_AUDIO_DRV is set.
202 QB_KERNEL_ROOT: Kernel's root (e.g. /dev/vda)
203 QB_TAP_OPT: Network option for 'tap' mode (e.g.
204 "-netdev tap,id=net0,ifname=@TAP@,script=no,downscript=no -device virtio-net-device,netdev=net0").
205 runqemu will replace "@TAP@" with the one that is used, such as tap0, tap1 ...
206 QB_SLIRP_OPT: Network option for SLIRP mode (e.g. "-netdev user,id=net0 -device virtio-net-device,netdev=net0")
207 QB_ROOTFS_OPT: Used as rootfs (e.g.
208 "-drive id=disk0,file=@ROOTFS@,if=none,format=raw -device virtio-blk-device,drive=disk0").
209 runqemu will replace "@ROOTFS@" with the one which is used, such as
210 core-image-minimal-qemuarm64.ext4.
211 QB_SERIAL_OPT: Serial port (e.g. "-serial mon:stdio")
212 QB_TCPSERIAL_OPT: tcp serial port option (e.g.
213 " -device virtio-serial-device -chardev socket,id=virtcon,port=@PORT@,host=127.0.0.1 -device virtconsole,chardev=virtcon"
214 runqemu will replace "@PORT@" with the port number which is used.
215
216To use ``runqemu``, set :term:`IMAGE_CLASSES` as
217follows and run ``runqemu``:
218
219.. note::
220
Andrew Geissler517393d2023-01-13 08:55:19 -0600221 "QB" means "QEMU Boot".
222
223.. note::
224
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500225 For command-line syntax, use ``runqemu help``.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500226
227::
228
229 IMAGE_CLASSES += "qemuboot"
230
231.. _migration-2.2-default-linker-hash-style-changed:
232
233Default Linker Hash Style Changed
234---------------------------------
235
236The default linker hash style for ``gcc-cross`` is now "sysv" in order
237to catch recipes that are building software without using the
238OpenEmbedded :term:`LDFLAGS`. This change could result in
239seeing some "No GNU_HASH in the elf binary" QA issues when building such
240recipes. You need to fix these recipes so that they use the expected
Andrew Geissler09036742021-06-25 14:25:14 -0500241:term:`LDFLAGS`. Depending on how the software is built, the build system
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500242used by the software (e.g. a Makefile) might need to be patched.
243However, sometimes making this fix is as simple as adding the following
Andrew Geisslerc926e172021-05-07 16:11:35 -0500244to the recipe::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500245
246 TARGET_CC_ARCH += "${LDFLAGS}"
247
248.. _migration-2.2-kernel-image-base-name-no-longer-uses-kernel-imagetype:
249
250``KERNEL_IMAGE_BASE_NAME`` no Longer Uses ``KERNEL_IMAGETYPE``
251--------------------------------------------------------------
252
253The ``KERNEL_IMAGE_BASE_NAME`` variable no longer uses the
254:term:`KERNEL_IMAGETYPE` variable to create the
255image's base name. Because the OpenEmbedded build system can now build
256multiple kernel image types, this part of the kernel image base name as
Andrew Geisslerc926e172021-05-07 16:11:35 -0500257been removed leaving only the following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500258
259 KERNEL_IMAGE_BASE_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}-${DATETIME}"
260
261If you have recipes or
262classes that use ``KERNEL_IMAGE_BASE_NAME`` directly, you might need to
263update the references to ensure they continue to work.
264
Andrew Geissler09036742021-06-25 14:25:14 -0500265.. _migration-2.2-imgdeploydir-replaces-deploy-dir-image-for-most-use-cases:
266
267``IMGDEPLOYDIR`` Replaces ``DEPLOY_DIR_IMAGE`` for Most Use Cases
268-----------------------------------------------------------------
269
270The :term:`IMGDEPLOYDIR` variable was introduced to allow sstate caching of
271image creation results. Image recipes defining custom :term:`IMAGE_CMD` or
272doing postprocessing on the generated images need to be adapted to use
Andrew Geissler5f350902021-07-23 13:09:54 -0400273:term:`IMGDEPLOYDIR` instead of :term:`DEPLOY_DIR_IMAGE`. :term:`IMAGE_MANIFEST`
Andrew Geissler09036742021-06-25 14:25:14 -0500274creation and symlinking of the most recent image file will fail otherwise.
275
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500276.. _migration-2.2-bitbake-changes:
277
278BitBake Changes
279---------------
280
281The following changes took place for BitBake:
282
283- The "goggle" UI and standalone image-writer tool have been removed as
284 they both require GTK+ 2.0 and were not being maintained.
285
286- The Perforce fetcher now supports :term:`SRCREV` for
287 specifying the source revision to use, be it
288 ``${``\ :term:`AUTOREV`\ ``}``, changelist number,
289 p4date, or label, in preference to separate
290 :term:`SRC_URI` parameters to specify these. This
291 change is more in-line with how the other fetchers work for source
292 control systems. Recipes that fetch from Perforce will need to be
Andrew Geissler09036742021-06-25 14:25:14 -0500293 updated to use :term:`SRCREV` in place of specifying the source revision
Andrew Geissler5f350902021-07-23 13:09:54 -0400294 within :term:`SRC_URI`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500295
296- Some of BitBake's internal code structures for accessing the recipe
297 cache needed to be changed to support the new multi-configuration
298 functionality. These changes will affect external tools that use
299 BitBake's tinfoil module. For information on these changes, see the
300 changes made to the scripts supplied with OpenEmbedded-Core:
Andrew Geissler09209ee2020-12-13 08:44:15 -0600301 :yocto_git:`1 </poky/commit/?id=189371f8393971d00bca0fceffd67cc07784f6ee>`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500302 and
Andrew Geissler09209ee2020-12-13 08:44:15 -0600303 :yocto_git:`2 </poky/commit/?id=4a5aa7ea4d07c2c90a1654b174873abb018acc67>`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500304
305- The task management code has been rewritten to avoid using ID
306 indirection in order to improve performance. This change is unlikely
307 to cause any problems for most users. However, the setscene
308 verification function as pointed to by
309 ``BB_SETSCENE_VERIFY_FUNCTION`` needed to change signature.
310 Consequently, a new variable named ``BB_SETSCENE_VERIFY_FUNCTION2``
311 has been added allowing multiple versions of BitBake to work with
312 suitably written metadata, which includes OpenEmbedded-Core and Poky.
313 Anyone with custom BitBake task scheduler code might also need to
314 update the code to handle the new structure.
315
316.. _migration-2.2-swabber-has-been-removed:
317
318Swabber has Been Removed
319------------------------
320
321Swabber, a tool that was intended to detect host contamination in the
322build process, has been removed, as it has been unmaintained and unused
323for some time and was never particularly effective. The OpenEmbedded
324build system has since incorporated a number of mechanisms including
325enhanced QA checks that mean that there is less of a need for such a
326tool.
327
328.. _migration-2.2-removed-recipes:
329
330Removed Recipes
331---------------
332
333The following recipes have been removed:
334
335- ``augeas``: No longer needed and has been moved to ``meta-oe``.
336
337- ``directfb``: Unmaintained and has been moved to ``meta-oe``.
338
339- ``gcc``: Removed 4.9 version. Versions 5.4 and 6.2 are still present.
340
341- ``gnome-doc-utils``: No longer needed.
342
343- ``gtk-doc-stub``: Replaced by ``gtk-doc``.
344
345- ``gtk-engines``: No longer needed and has been moved to
346 ``meta-gnome``.
347
348- ``gtk-sato-engine``: Became obsolete.
349
350- ``libglade``: No longer needed and has been moved to ``meta-oe``.
351
352- ``libmad``: Unmaintained and functionally replaced by ``libmpg123``.
353 ``libmad`` has been moved to ``meta-oe``.
354
355- ``libowl``: Became obsolete.
356
357- ``libxsettings-client``: No longer needed.
358
359- ``oh-puzzles``: Functionally replaced by ``puzzles``.
360
361- ``oprofileui``: Became obsolete. OProfile has been largely supplanted
362 by perf.
363
364- ``packagegroup-core-directfb.bb``: Removed.
365
366- ``core-image-directfb.bb``: Removed.
367
368- ``pointercal``: No longer needed and has been moved to ``meta-oe``.
369
370- ``python-imaging``: No longer needed and moved to ``meta-python``
371
372- ``python-pyrex``: No longer needed and moved to ``meta-python``.
373
374- ``sato-icon-theme``: Became obsolete.
375
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500376- ``swabber-native``: Swabber has been removed. See the :ref:`entry on
Andrew Geissler09036742021-06-25 14:25:14 -0500377 Swabber <migration-guides/migration-2.2:swabber has been removed>`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500378
379- ``tslib``: No longer needed and has been moved to ``meta-oe``.
380
381- ``uclibc``: Removed in favor of musl.
382
383- ``xtscal``: No longer needed and moved to ``meta-oe``
384
385.. _migration-2.2-removed-classes:
386
387Removed Classes
388---------------
389
390The following classes have been removed:
391
392- ``distutils-native-base``: No longer needed.
393
394- ``distutils3-native-base``: No longer needed.
395
396- ``sdl``: Only set :term:`DEPENDS` and
397 :term:`SECTION`, which are better set within the
398 recipe instead.
399
400- ``sip``: Mostly unused.
401
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500402- ``swabber``: See the :ref:`entry on
Andrew Geissler09036742021-06-25 14:25:14 -0500403 Swabber <migration-guides/migration-2.2:swabber has been removed>`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500404
405.. _migration-2.2-minor-packaging-changes:
406
407Minor Packaging Changes
408-----------------------
409
410The following minor packaging changes have occurred:
411
412- ``grub``: Split ``grub-editenv`` into its own package.
413
414- ``systemd``: Split container and vm related units into a new package,
415 systemd-container.
416
417- ``util-linux``: Moved ``prlimit`` to a separate
418 ``util-linux-prlimit`` package.
419
420.. _migration-2.2-miscellaneous-changes:
421
422Miscellaneous Changes
423---------------------
424
425The following miscellaneous changes have occurred:
426
427- ``package_regex.inc``: Removed because the definitions
428 ``package_regex.inc`` previously contained have been moved to their
429 respective recipes.
430
431- Both ``devtool add`` and ``recipetool create`` now use a fixed
432 :term:`SRCREV` by default when fetching from a Git
433 repository. You can override this in either case to use
434 ``${``\ :term:`AUTOREV`\ ``}`` instead by using the
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700435 ``-a`` or ``--autorev`` command-line option
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500436
437- ``distcc``: GTK+ UI is now disabled by default.
438
439- ``packagegroup-core-tools-testapps``: Removed Piglit.
440
Andrew Geissler7e0e3c02022-02-25 20:34:39 +0000441- :ref:`ref-classes-image`: Renamed COMPRESS(ION) to CONVERSION. This change
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500442 means that ``COMPRESSIONTYPES``, ``COMPRESS_DEPENDS`` and
443 ``COMPRESS_CMD`` are deprecated in favor of ``CONVERSIONTYPES``,
Andrew Geissler615f2f12022-07-15 14:00:58 -0500444 ``CONVERSION_DEPENDS`` and :term:`CONVERSION_CMD`. The ``COMPRESS*``
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500445 variable names will still work in the 2.2 release but metadata that
446 does not need to be backwards-compatible should be changed to use the
447 new names as the ``COMPRESS*`` ones will be removed in a future
448 release.
449
450- ``gtk-doc``: A full version of ``gtk-doc`` is now made available.
451 However, some old software might not be capable of using the current
452 version of ``gtk-doc`` to build documentation. You need to change
453 recipes that build such software so that they explicitly disable
454 building documentation with ``gtk-doc``.
455
456