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