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 3.5). 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 125directory for tasks. Consequently, any custom tasks you define now need 126to either have the 127``[``\ :ref:`dirs <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:variable flags>`\ ``]`` flag 128set, or the task needs to change into the appropriate working directory 129manually (e.g using ``cd`` for a shell task). 130 131.. note:: 132 133 The preferred method is to use the 134 [dirs] 135 flag. 136 137.. _migration-2.2-runqemu-ported-to-python: 138 139``runqemu`` Ported to Python 140---------------------------- 141 142``runqemu`` has been ported to Python and has changed behavior in some 143cases. Previous usage patterns continue to be supported. 144 145The new ``runqemu`` is a Python script. Machine knowledge is no longer 146hardcoded into ``runqemu``. You can choose to use the ``qemuboot`` 147configuration file to define the BSP's own arguments and to make it 148bootable with ``runqemu``. If you use a configuration file, use the 149following form:: 150 151 image-name-machine.qemuboot.conf 152 153The configuration file 154enables fine-grained tuning of options passed to QEMU without the 155``runqemu`` script hard-coding any knowledge about different machines. 156Using a configuration file is particularly convenient when trying to use 157QEMU with machines other than the ``qemu*`` machines in 158:term:`OpenEmbedded-Core (OE-Core)`. The ``qemuboot.conf`` file is generated by the 159``qemuboot`` class when the root filesystem is being built (i.e. build 160rootfs). QEMU boot arguments can be set in BSP's configuration file and 161the ``qemuboot`` class will save them to ``qemuboot.conf``. 162 163If you want to use ``runqemu`` without a configuration file, use the 164following command form:: 165 166 $ runqemu machine rootfs kernel [options] 167 168Supported machines are as follows: 169 170 - qemuarm 171 - qemuarm64 172 - qemux86 173 - qemux86-64 174 - qemuppc 175 - qemumips 176 - qemumips64 177 - qemumipsel 178 - qemumips64el 179 180Consider the 181following example, which uses the ``qemux86-64`` machine, provides a 182root filesystem, provides an image, and uses the ``nographic`` option:: 183 184 $ runqemu qemux86-64 tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64.ext4 tmp/deploy/images/qemux86-64/bzImage nographic 185 186Following is a list of variables that can be set in configuration files 187such as ``bsp.conf`` to enable the BSP to be booted by ``runqemu``:: 188 189 QB_SYSTEM_NAME: QEMU name (e.g. "qemu-system-i386") 190 QB_OPT_APPEND: Options to append to QEMU (e.g. "-show-cursor") 191 QB_DEFAULT_KERNEL: Default kernel to boot (e.g. "bzImage") 192 QB_DEFAULT_FSTYPE: Default FSTYPE to boot (e.g. "ext4") 193 QB_MEM: Memory (e.g. "-m 512") 194 QB_MACHINE: QEMU machine (e.g. "-machine virt") 195 QB_CPU: QEMU cpu (e.g. "-cpu qemu32") 196 QB_CPU_KVM: Similar to QB_CPU except used for kvm support (e.g. "-cpu kvm64") 197 QB_KERNEL_CMDLINE_APPEND: Options to append to the kernel's -append 198 option (e.g. "console=ttyS0 console=tty") 199 QB_DTB: QEMU dtb name 200 QB_AUDIO_DRV: QEMU audio driver (e.g. "alsa", set it when support audio) 201 QB_AUDIO_OPT: QEMU audio option (e.g. "-soundhw ac97,es1370"), which is used 202 when QB_AUDIO_DRV is set. 203 QB_KERNEL_ROOT: Kernel's root (e.g. /dev/vda) 204 QB_TAP_OPT: Network option for 'tap' mode (e.g. 205 "-netdev tap,id=net0,ifname=@TAP@,script=no,downscript=no -device virtio-net-device,netdev=net0"). 206 runqemu will replace "@TAP@" with the one that is used, such as tap0, tap1 ... 207 QB_SLIRP_OPT: Network option for SLIRP mode (e.g. "-netdev user,id=net0 -device virtio-net-device,netdev=net0") 208 QB_ROOTFS_OPT: Used as rootfs (e.g. 209 "-drive id=disk0,file=@ROOTFS@,if=none,format=raw -device virtio-blk-device,drive=disk0"). 210 runqemu will replace "@ROOTFS@" with the one which is used, such as 211 core-image-minimal-qemuarm64.ext4. 212 QB_SERIAL_OPT: Serial port (e.g. "-serial mon:stdio") 213 QB_TCPSERIAL_OPT: tcp serial port option (e.g. 214 " -device virtio-serial-device -chardev socket,id=virtcon,port=@PORT@,host=127.0.0.1 -device virtconsole,chardev=virtcon" 215 runqemu will replace "@PORT@" with the port number which is used. 216 217To use ``runqemu``, set :term:`IMAGE_CLASSES` as 218follows and run ``runqemu``: 219 220.. note:: 221 222 "QB" means "QEMU Boot". 223 224.. note:: 225 226 For command-line syntax, use ``runqemu help``. 227 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 242:term:`LDFLAGS`. Depending on how the software is built, the build system 243used by the software (e.g. a Makefile) might need to be patched. 244However, sometimes making this fix is as simple as adding the following 245to the recipe:: 246 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 258been removed leaving only the following:: 259 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 266.. _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 274:term:`IMGDEPLOYDIR` instead of :term:`DEPLOY_DIR_IMAGE`. :term:`IMAGE_MANIFEST` 275creation and symlinking of the most recent image file will fail otherwise. 276 277.. _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 294 updated to use :term:`SRCREV` in place of specifying the source revision 295 within :term:`SRC_URI`. 296 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: 302 :yocto_git:`1 </poky/commit/?id=189371f8393971d00bca0fceffd67cc07784f6ee>` 303 and 304 :yocto_git:`2 </poky/commit/?id=4a5aa7ea4d07c2c90a1654b174873abb018acc67>`. 305 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 377- ``swabber-native``: Swabber has been removed. See the :ref:`entry on 378 Swabber <migration-guides/migration-2.2:swabber has been removed>`. 379 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 403- ``swabber``: See the :ref:`entry on 404 Swabber <migration-guides/migration-2.2:swabber has been removed>`. 405 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 436 ``-a`` or ``--autorev`` command-line option 437 438- ``distcc``: GTK+ UI is now disabled by default. 439 440- ``packagegroup-core-tools-testapps``: Removed Piglit. 441 442- :ref:`ref-classes-image`: Renamed COMPRESS(ION) to CONVERSION. This change 443 means that ``COMPRESSIONTYPES``, ``COMPRESS_DEPENDS`` and 444 ``COMPRESS_CMD`` are deprecated in favor of ``CONVERSIONTYPES``, 445 ``CONVERSION_DEPENDS`` and :term:`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 458