1Release 2.2 (morty) 2=================== 3 4This section provides migration information for moving to the Yocto 5Project 2.2 Release (codename "morty") from the prior release. 6 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 19 For x86 and x86_64, you can reset :term:`OLDEST_KERNEL` 20 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`, 29:term:`SYSROOT_DIRS_NATIVE`, and ``SYSROOT_DIRS_BLACKLIST`` 30(replaced by :term:`SYSROOT_DIRS_IGNORE` in version 3.5). See the 31:oe_lists:`v2 patch series on the OE-Core Mailing List 32</pipermail/openembedded-core/2016-May/121365.html>` 33for 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 81 - the ``iter*()`` functions changed name 82 83 - iterators now return views, not lists 84 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 147following form:: 148 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 157``qemuboot`` class when the root filesystem is being built (i.e. build 158rootfs). 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 162following command form:: 163 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 180root filesystem, provides an image, and uses the ``nographic`` option:: 181 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 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 ``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