1.. SPDX-License-Identifier: CC-BY-SA-2.0-UK 2 3Release 2.2 (morty) 4=================== 5 6This section provides migration information for moving to the Yocto 7Project 2.2 Release (codename "morty") from the prior release. 8 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 21 For x86 and x86_64, you can reset :term:`OLDEST_KERNEL` 22 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`, 31:term:`SYSROOT_DIRS_NATIVE`, and ``SYSROOT_DIRS_BLACKLIST`` 32(replaced by :term:`SYSROOT_DIRS_IGNORE` in version 4.0). See the 33:oe_lists:`v2 patch series on the OE-Core Mailing List 34</pipermail/openembedded-core/2016-May/121365.html>` 35for 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. 75Alternatively, you can reference the conversion commits for BitBake and 76you 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 83 - the ``iter*()`` functions changed name 84 85 - iterators now return views, not lists 86 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 108The :term:`buildtools` tarball now includes Python 3. 109 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 124``${``\ :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 128manually (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 148following form:: 149 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 158``qemuboot`` class when the root filesystem is being built (i.e. build 159rootfs). 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 163following command form:: 164 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 181root filesystem, provides an image, and uses the ``nographic`` option:: 182 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 186such as ``bsp.conf`` to enable the BSP to be booted by ``runqemu``:: 187 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 221 "QB" means "QEMU Boot". 222 223.. note:: 224 225 For command-line syntax, use ``runqemu help``. 226 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 241:term:`LDFLAGS`. Depending on how the software is built, the build system 242used by the software (e.g. a Makefile) might need to be patched. 243However, sometimes making this fix is as simple as adding the following 244to the recipe:: 245 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 257been removed leaving only the following:: 258 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 265.. _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 273:term:`IMGDEPLOYDIR` instead of :term:`DEPLOY_DIR_IMAGE`. :term:`IMAGE_MANIFEST` 274creation and symlinking of the most recent image file will fail otherwise. 275 276.. _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 293 updated to use :term:`SRCREV` in place of specifying the source revision 294 within :term:`SRC_URI`. 295 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: 301 :yocto_git:`1 </poky/commit/?id=189371f8393971d00bca0fceffd67cc07784f6ee>` 302 and 303 :yocto_git:`2 </poky/commit/?id=4a5aa7ea4d07c2c90a1654b174873abb018acc67>`. 304 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 376- ``swabber-native``: Swabber has been removed. See the :ref:`entry on 377 Swabber <migration-guides/migration-2.2:swabber has been removed>`. 378 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 402- ``swabber``: See the :ref:`entry on 403 Swabber <migration-guides/migration-2.2:swabber has been removed>`. 404 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 435 ``-a`` or ``--autorev`` command-line option 436 437- ``distcc``: GTK+ UI is now disabled by default. 438 439- ``packagegroup-core-tools-testapps``: Removed Piglit. 440 441- :ref:`ref-classes-image`: Renamed COMPRESS(ION) to CONVERSION. This change 442 means that ``COMPRESSIONTYPES``, ``COMPRESS_DEPENDS`` and 443 ``COMPRESS_CMD`` are deprecated in favor of ``CONVERSIONTYPES``, 444 ``CONVERSION_DEPENDS`` and :term:`CONVERSION_CMD`. The ``COMPRESS*`` 445 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 457