1Release 2.1 (krogoth) 2===================== 3 4This section provides migration information for moving to the Yocto 5Project 2.1 Release (codename "krogoth") from the prior release. 6 7.. _migration-2.1-variable-expansion-in-python-functions: 8 9Variable Expansion in Python Functions 10-------------------------------------- 11 12Variable expressions, such as ``${VARNAME}`` no longer expand 13automatically within Python functions. Suppressing expansion was done to 14allow Python functions to construct shell scripts or other code for 15situations in which you do not want such expressions expanded. For any 16existing code that relies on these expansions, you need to change the 17expansions to expand the value of individual variables through 18``d.getVar()``. To alternatively expand more complex expressions, use 19``d.expand()``. 20 21.. _migration-2.1-overrides-must-now-be-lower-case: 22 23Overrides Must Now be Lower-Case 24-------------------------------- 25 26The convention for overrides has always been for them to be lower-case 27characters. This practice is now a requirement as BitBake's datastore 28now assumes lower-case characters in order to give a slight performance 29boost during parsing. In practical terms, this requirement means that 30anything that ends up in :term:`OVERRIDES` must now 31appear in lower-case characters (e.g. values for :term:`MACHINE`, 32:term:`TARGET_ARCH`, :term:`DISTRO`, and also recipe names if 33``_pn-``\ recipename overrides are to be effective). 34 35.. _migration-2.1-expand-parameter-to-getvar-and-getvarflag-now-mandatory: 36 37Expand Parameter to ``getVar()`` and ``getVarFlag()`` is Now Mandatory 38---------------------------------------------------------------------- 39 40The expand parameter to ``getVar()`` and ``getVarFlag()`` previously 41defaulted to False if not specified. Now, however, no default exists so 42one must be specified. You must change any ``getVar()`` calls that do 43not specify the final expand parameter to calls that do specify the 44parameter. You can run the following ``sed`` command at the base of a 45layer to make this change:: 46 47 sed -e 's:\(\.getVar([^,()]*\)):\1, False):g' -i `grep -ril getVar *` 48 sed -e 's:\(\.getVarFlag([^,()]*,[^,()]*\)):\1, False):g' -i `grep -ril getVarFlag *` 49 50.. note:: 51 52 The reason for this change is that it prepares the way for changing 53 the default to True in a future Yocto Project release. This future 54 change is a much more sensible default than False. However, the 55 change needs to be made gradually as a sudden change of the default 56 would potentially cause side-effects that would be difficult to 57 detect. 58 59.. _migration-2.1-makefile-environment-changes: 60 61Makefile Environment Changes 62---------------------------- 63 64:term:`EXTRA_OEMAKE` now defaults to "" instead of 65"-e MAKEFLAGS=". Setting :term:`EXTRA_OEMAKE` to "-e MAKEFLAGS=" by default 66was a historical accident that has required many classes (e.g. 67``autotools``, ``module``) and recipes to override this default in order 68to work with sensible build systems. When upgrading to the release, you 69must edit any recipe that relies upon this old default by either setting 70:term:`EXTRA_OEMAKE` back to "-e MAKEFLAGS=" or by explicitly setting any 71required variable value overrides using :term:`EXTRA_OEMAKE`, which is 72typically only needed when a Makefile sets a default value for a 73variable that is inappropriate for cross-compilation using the "=" 74operator rather than the "?=" operator. 75 76.. _migration-2.1-libexecdir-reverted-to-prefix-libexec: 77 78``libexecdir`` Reverted to ``${prefix}/libexec`` 79------------------------------------------------ 80 81The use of ``${libdir}/${BPN}`` as ``libexecdir`` is different as 82compared to all other mainstream distributions, which either uses 83``${prefix}/libexec`` or ``${libdir}``. The use is also contrary to the 84GNU Coding Standards (i.e. 85https://www.gnu.org/prep/standards/html_node/Directory-Variables.html) 86that suggest ``${prefix}/libexec`` and also notes that any 87package-specific nesting should be done by the package itself. Finally, 88having ``libexecdir`` change between recipes makes it very difficult for 89different recipes to invoke binaries that have been installed into 90``libexecdir``. The Filesystem Hierarchy Standard (i.e. 91https://refspecs.linuxfoundation.org/FHS_3.0/fhs/ch04s07.html) now 92recognizes the use of ``${prefix}/libexec/``, giving distributions the 93choice between ``${prefix}/lib`` or ``${prefix}/libexec`` without 94breaking FHS. 95 96.. _migration-2.1-ac-cv-sizeof-off-t-no-longer-cached-in-site-files: 97 98``ac_cv_sizeof_off_t`` is No Longer Cached in Site Files 99-------------------------------------------------------- 100 101For recipes inheriting the :ref:`autotools <ref-classes-autotools>` 102class, ``ac_cv_sizeof_off_t`` is no longer cached in the site files for 103``autoconf``. The reason for this change is because the 104``ac_cv_sizeof_off_t`` value is not necessarily static per architecture 105as was previously assumed. Rather, the value changes based on whether 106large file support is enabled. For most software that uses ``autoconf``, 107this change should not be a problem. However, if you have a recipe that 108bypasses the standard :ref:`ref-tasks-configure` task 109from the :ref:`autotools <ref-classes-autotools>` class and the software the recipe is building 110uses a very old version of ``autoconf``, the recipe might be incapable 111of determining the correct size of ``off_t`` during ``do_configure``. 112 113The best course of action is to patch the software as necessary to allow 114the default implementation from the :ref:`autotools <ref-classes-autotools>` class to work such 115that ``autoreconf`` succeeds and produces a working configure script, 116and to remove the overridden ``do_configure`` task such that the default 117implementation does get used. 118 119.. _migration-2.1-image-generation-split-out-from-filesystem-generation: 120 121Image Generation is Now Split Out from Filesystem Generation 122------------------------------------------------------------ 123 124Previously, for image recipes the :ref:`ref-tasks-rootfs` 125task assembled the filesystem and then from that filesystem generated 126images. With this Yocto Project release, image generation is split into 127separate :ref:`ref-tasks-image` tasks for clarity both in 128operation and in the code. 129 130For most cases, this change does not present any problems. However, if 131you have made customizations that directly modify the ``do_rootfs`` task 132or that mention ``do_rootfs``, you might need to update those changes. 133In particular, if you had added any tasks after ``do_rootfs``, you 134should make edits so that those tasks are after the 135:ref:`ref-tasks-image-complete` task rather than 136after ``do_rootfs`` so that your added tasks run at the correct 137time. 138 139A minor part of this restructuring is that the post-processing 140definitions and functions have been moved from the 141:ref:`image <ref-classes-image>` class to the 142:ref:`rootfs-postcommands <ref-classes-rootfs*>` class. Functionally, 143however, they remain unchanged. 144 145.. _migration-2.1-removed-recipes: 146 147Removed Recipes 148--------------- 149 150The following recipes have been removed in the 2.1 release: 151 152- ``gcc`` version 4.8: Versions 4.9 and 5.3 remain. 153 154- ``qt4``: All support for Qt 4.x has been moved out to a separate 155 ``meta-qt4`` layer because Qt 4 is no longer supported upstream. 156 157- ``x11vnc``: Moved to the ``meta-oe`` layer. 158 159- ``linux-yocto-3.14``: No longer supported. 160 161- ``linux-yocto-3.19``: No longer supported. 162 163- ``libjpeg``: Replaced by the ``libjpeg-turbo`` recipe. 164 165- ``pth``: Became obsolete. 166 167- ``liboil``: Recipe is no longer needed and has been moved to the 168 ``meta-multimedia`` layer. 169 170- ``gtk-theme-torturer``: Recipe is no longer needed and has been moved 171 to the ``meta-gnome`` layer. 172 173- ``gnome-mime-data``: Recipe is no longer needed and has been moved to 174 the ``meta-gnome`` layer. 175 176- ``udev``: Replaced by the ``eudev`` recipe for compatibility when 177 using ``sysvinit`` with newer kernels. 178 179- ``python-pygtk``: Recipe became obsolete. 180 181- ``adt-installer``: Recipe became obsolete. See the 182 ":ref:`migration-guides/migration-2.1:adt removed`" section for more information. 183 184.. _migration-2.1-class-changes: 185 186Class Changes 187------------- 188 189The following classes have changed: 190 191- ``autotools_stage``: Removed because the 192 :ref:`autotools <ref-classes-autotools>` class now provides its 193 functionality. Recipes that inherited from ``autotools_stage`` should 194 now inherit from ``autotools`` instead. 195 196- ``boot-directdisk``: Merged into the ``image-vm`` class. The 197 ``boot-directdisk`` class was rarely directly used. Consequently, 198 this change should not cause any issues. 199 200- ``bootimg``: Merged into the 201 :ref:`image-live <ref-classes-image-live>` class. The ``bootimg`` 202 class was rarely directly used. Consequently, this change should not 203 cause any issues. 204 205- ``packageinfo``: Removed due to its limited use by the Hob UI, which 206 has itself been removed. 207 208.. _migration-2.1-build-system-ui-changes: 209 210Build System User Interface Changes 211----------------------------------- 212 213The following changes have been made to the build system user interface: 214 215- *Hob GTK+-based UI*: Removed because it is unmaintained and based on 216 the outdated GTK+ 2 library. The Toaster web-based UI is much more 217 capable and is actively maintained. See the 218 ":ref:`toaster-manual/setup-and-use:using the toaster web interface`" 219 section in the Toaster User Manual for more information on this 220 interface. 221 222- *"puccho" BitBake UI*: Removed because is unmaintained and no longer 223 useful. 224 225.. _migration-2.1-adt-removed: 226 227ADT Removed 228----------- 229 230The Application Development Toolkit (ADT) has been removed because its 231functionality almost completely overlapped with the :ref:`standard 232SDK <sdk-manual/using:using the standard sdk>` and the 233:ref:`extensible SDK <sdk-manual/extensible:using the extensible sdk>`. For 234information on these SDKs and how to build and use them, see the 235:doc:`/sdk-manual/index` manual. 236 237.. note:: 238 239 The Yocto Project Eclipse IDE Plug-in is still supported and is not 240 affected by this change. 241 242.. _migration-2.1-poky-reference-distribution-changes: 243 244Poky Reference Distribution Changes 245----------------------------------- 246 247The following changes have been made for the Poky distribution: 248 249- The ``meta-yocto`` layer has been renamed to ``meta-poky`` to better 250 match its purpose, which is to provide the Poky reference 251 distribution. The ``meta-yocto-bsp`` layer retains its original name 252 since it provides reference machines for the Yocto Project and it is 253 otherwise unrelated to Poky. References to ``meta-yocto`` in your 254 ``conf/bblayers.conf`` should automatically be updated, so you should 255 not need to change anything unless you are relying on this naming 256 elsewhere. 257 258- The :ref:`uninative <ref-classes-uninative>` class is now enabled 259 by default in Poky. This class attempts to isolate the build system 260 from the host distribution's C library and makes re-use of native 261 shared state artifacts across different host distributions practical. 262 With this class enabled, a tarball containing a pre-built C library 263 is downloaded at the start of the build. 264 265 The :ref:`uninative <ref-classes-uninative>` class is enabled through the 266 ``meta/conf/distro/include/yocto-uninative.inc`` file, which for 267 those not using the Poky distribution, can include to easily enable 268 the same functionality. 269 270 Alternatively, if you wish to build your own ``uninative`` tarball, 271 you can do so by building the ``uninative-tarball`` recipe, making it 272 available to your build machines (e.g. over HTTP/HTTPS) and setting a 273 similar configuration as the one set by ``yocto-uninative.inc``. 274 275- Static library generation, for most cases, is now disabled by default 276 in the Poky distribution. Disabling this generation saves some build 277 time as well as the size used for build output artifacts. 278 279 Disabling this library generation is accomplished through a 280 ``meta/conf/distro/include/no-static-libs.inc``, which for those not 281 using the Poky distribution can easily include to enable the same 282 functionality. 283 284 Any recipe that needs to opt-out of having the ``--disable-static`` 285 option specified on the configure command line either because it is 286 not a supported option for the configure script or because static 287 libraries are needed should set the following variable:: 288 289 DISABLE_STATIC = "" 290 291- The separate ``poky-tiny`` distribution now uses the musl C library 292 instead of a heavily pared down ``glibc``. Using musl results in a 293 smaller distribution and facilitates much greater maintainability 294 because musl is designed to have a small footprint. 295 296 If you have used ``poky-tiny`` and have customized the ``glibc`` 297 configuration you will need to redo those customizations with musl 298 when upgrading to the new release. 299 300.. _migration-2.1-packaging-changes: 301 302Packaging Changes 303----------------- 304 305The following changes have been made to packaging: 306 307- The ``runuser`` and ``mountpoint`` binaries, which were previously in 308 the main ``util-linux`` package, have been split out into the 309 ``util-linux-runuser`` and ``util-linux-mountpoint`` packages, 310 respectively. 311 312- The ``python-elementtree`` package has been merged into the 313 ``python-xml`` package. 314 315.. _migration-2.1-tuning-file-changes: 316 317Tuning File Changes 318------------------- 319 320The following changes have been made to the tuning files: 321 322- The "no-thumb-interwork" tuning feature has been dropped from the ARM 323 tune include files. Because interworking is required for ARM EABI, 324 attempting to disable it through a tuning feature no longer makes 325 sense. 326 327 .. note:: 328 329 Support for ARM OABI was deprecated in gcc 4.7. 330 331- The ``tune-cortexm*.inc`` and ``tune-cortexr4.inc`` files have been 332 removed because they are poorly tested. Until the OpenEmbedded build 333 system officially gains support for CPUs without an MMU, these tuning 334 files would probably be better maintained in a separate layer if 335 needed. 336 337.. _migration-2.1-supporting-gobject-introspection: 338 339Supporting GObject Introspection 340-------------------------------- 341 342This release supports generation of GLib Introspective Repository (GIR) 343files through GObject introspection, which is the standard mechanism for 344accessing GObject-based software from runtime environments. You can 345enable, disable, and test the generation of this data. See the 346":ref:`dev-manual/common-tasks:enabling gobject introspection support`" 347section in the Yocto Project Development Tasks Manual for more 348information. 349 350.. _migration-2.1-miscellaneous-changes: 351 352Miscellaneous Changes 353--------------------- 354 355These additional changes exist: 356 357- The minimum Git version has been increased to 1.8.3.1. If your host 358 distribution does not provide a sufficiently recent version, you can 359 install the buildtools, which will provide it. See the 360 :ref:`ref-manual/system-requirements:required git, tar, python and gcc versions` 361 section for more information on the buildtools tarball. 362 363- The buggy and incomplete support for the RPM version 4 package 364 manager has been removed. The well-tested and maintained support for 365 RPM version 5 remains. 366 367- Previously, the following list of packages were removed if 368 package-management was not in 369 :term:`IMAGE_FEATURES`, regardless of any 370 dependencies:: 371 372 update-rc.d 373 base-passwd 374 shadow 375 update-alternatives 376 run-postinsts 377 378 With the Yocto Project 2.1 release, these packages are 379 only removed if "read-only-rootfs" is in :term:`IMAGE_FEATURES`, since 380 they might still be needed for a read-write image even in the absence 381 of a package manager (e.g. if users need to be added, modified, or 382 removed at runtime). 383 384- The 385 :ref:`devtool modify <sdk-manual/extensible:use \`\`devtool modify\`\` to modify the source of an existing component>` 386 command now defaults to extracting the source since that is most 387 commonly expected. The ``-x`` or ``--extract`` options are now no-ops. If 388 you wish to provide your own existing source tree, you will now need 389 to specify either the ``-n`` or ``--no-extract`` options when running 390 ``devtool modify``. 391 392- If the formfactor for a machine is either not supplied or does not 393 specify whether a keyboard is attached, then the default is to assume 394 a keyboard is attached rather than assume no keyboard. This change 395 primarily affects the Sato UI. 396 397- The ``.debug`` directory packaging is now automatic. If your recipe 398 builds software that installs binaries into directories other than 399 the standard ones, you no longer need to take care of setting 400 ``FILES_${PN}-dbg`` to pick up the resulting ``.debug`` directories 401 as these directories are automatically found and added. 402 403- Inaccurate disk and CPU percentage data has been dropped from 404 ``buildstats`` output. This data has been replaced with 405 ``getrusage()`` data and corrected IO statistics. You will probably 406 need to update any custom code that reads the ``buildstats`` data. 407 408- The ``meta/conf/distro/include/package_regex.inc`` is now deprecated. 409 The contents of this file have been moved to individual recipes. 410 411 .. note:: 412 413 Because this file will likely be removed in a future Yocto Project 414 release, it is suggested that you remove any references to the 415 file that might be in your configuration. 416 417- The ``v86d/uvesafb`` has been removed from the ``genericx86`` and 418 ``genericx86-64`` reference machines, which are provided by the 419 ``meta-yocto-bsp`` layer. Most modern x86 boards do not rely on this 420 file and it only adds kernel error messages during startup. If you do 421 still need to support ``uvesafb``, you can simply add ``v86d`` to 422 your image. 423 424- Build sysroot paths are now removed from debug symbol files. Removing 425 these paths means that remote GDB using an unstripped build system 426 sysroot will no longer work (although this was never documented to 427 work). The supported method to accomplish something similar is to set 428 ``IMAGE_GEN_DEBUGFS`` to "1", which will generate a companion debug 429 image containing unstripped binaries and associated debug sources 430 alongside the image. 431 432 433