blob: a60ce8d52b314ce656b9c1b8fa82b7ffa0b1a165 [file] [log] [blame]
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05001Moving to the Yocto Project 2.2 Release (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`,
29:term:`SYSROOT_DIRS_NATIVE`, and
30:term:`SYSROOT_DIRS_BLACKLIST`. 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
157``qemuboot`` class when the root filesystem is being build (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
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
242``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
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
266.. _migration-2.2-bitbake-changes:
267
268BitBake Changes
269---------------
270
271The following changes took place for BitBake:
272
273- The "goggle" UI and standalone image-writer tool have been removed as
274 they both require GTK+ 2.0 and were not being maintained.
275
276- The Perforce fetcher now supports :term:`SRCREV` for
277 specifying the source revision to use, be it
278 ``${``\ :term:`AUTOREV`\ ``}``, changelist number,
279 p4date, or label, in preference to separate
280 :term:`SRC_URI` parameters to specify these. This
281 change is more in-line with how the other fetchers work for source
282 control systems. Recipes that fetch from Perforce will need to be
283 updated to use ``SRCREV`` in place of specifying the source revision
284 within ``SRC_URI``.
285
286- Some of BitBake's internal code structures for accessing the recipe
287 cache needed to be changed to support the new multi-configuration
288 functionality. These changes will affect external tools that use
289 BitBake's tinfoil module. For information on these changes, see the
290 changes made to the scripts supplied with OpenEmbedded-Core:
Andrew Geissler09209ee2020-12-13 08:44:15 -0600291 :yocto_git:`1 </poky/commit/?id=189371f8393971d00bca0fceffd67cc07784f6ee>`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500292 and
Andrew Geissler09209ee2020-12-13 08:44:15 -0600293 :yocto_git:`2 </poky/commit/?id=4a5aa7ea4d07c2c90a1654b174873abb018acc67>`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500294
295- The task management code has been rewritten to avoid using ID
296 indirection in order to improve performance. This change is unlikely
297 to cause any problems for most users. However, the setscene
298 verification function as pointed to by
299 ``BB_SETSCENE_VERIFY_FUNCTION`` needed to change signature.
300 Consequently, a new variable named ``BB_SETSCENE_VERIFY_FUNCTION2``
301 has been added allowing multiple versions of BitBake to work with
302 suitably written metadata, which includes OpenEmbedded-Core and Poky.
303 Anyone with custom BitBake task scheduler code might also need to
304 update the code to handle the new structure.
305
306.. _migration-2.2-swabber-has-been-removed:
307
308Swabber has Been Removed
309------------------------
310
311Swabber, a tool that was intended to detect host contamination in the
312build process, has been removed, as it has been unmaintained and unused
313for some time and was never particularly effective. The OpenEmbedded
314build system has since incorporated a number of mechanisms including
315enhanced QA checks that mean that there is less of a need for such a
316tool.
317
318.. _migration-2.2-removed-recipes:
319
320Removed Recipes
321---------------
322
323The following recipes have been removed:
324
325- ``augeas``: No longer needed and has been moved to ``meta-oe``.
326
327- ``directfb``: Unmaintained and has been moved to ``meta-oe``.
328
329- ``gcc``: Removed 4.9 version. Versions 5.4 and 6.2 are still present.
330
331- ``gnome-doc-utils``: No longer needed.
332
333- ``gtk-doc-stub``: Replaced by ``gtk-doc``.
334
335- ``gtk-engines``: No longer needed and has been moved to
336 ``meta-gnome``.
337
338- ``gtk-sato-engine``: Became obsolete.
339
340- ``libglade``: No longer needed and has been moved to ``meta-oe``.
341
342- ``libmad``: Unmaintained and functionally replaced by ``libmpg123``.
343 ``libmad`` has been moved to ``meta-oe``.
344
345- ``libowl``: Became obsolete.
346
347- ``libxsettings-client``: No longer needed.
348
349- ``oh-puzzles``: Functionally replaced by ``puzzles``.
350
351- ``oprofileui``: Became obsolete. OProfile has been largely supplanted
352 by perf.
353
354- ``packagegroup-core-directfb.bb``: Removed.
355
356- ``core-image-directfb.bb``: Removed.
357
358- ``pointercal``: No longer needed and has been moved to ``meta-oe``.
359
360- ``python-imaging``: No longer needed and moved to ``meta-python``
361
362- ``python-pyrex``: No longer needed and moved to ``meta-python``.
363
364- ``sato-icon-theme``: Became obsolete.
365
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500366- ``swabber-native``: Swabber has been removed. See the :ref:`entry on
367 Swabber <ref-manual/migration-2.2:swabber has been removed>`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500368
369- ``tslib``: No longer needed and has been moved to ``meta-oe``.
370
371- ``uclibc``: Removed in favor of musl.
372
373- ``xtscal``: No longer needed and moved to ``meta-oe``
374
375.. _migration-2.2-removed-classes:
376
377Removed Classes
378---------------
379
380The following classes have been removed:
381
382- ``distutils-native-base``: No longer needed.
383
384- ``distutils3-native-base``: No longer needed.
385
386- ``sdl``: Only set :term:`DEPENDS` and
387 :term:`SECTION`, which are better set within the
388 recipe instead.
389
390- ``sip``: Mostly unused.
391
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500392- ``swabber``: See the :ref:`entry on
393 Swabber <ref-manual/migration-2.2:swabber has been removed>`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500394
395.. _migration-2.2-minor-packaging-changes:
396
397Minor Packaging Changes
398-----------------------
399
400The following minor packaging changes have occurred:
401
402- ``grub``: Split ``grub-editenv`` into its own package.
403
404- ``systemd``: Split container and vm related units into a new package,
405 systemd-container.
406
407- ``util-linux``: Moved ``prlimit`` to a separate
408 ``util-linux-prlimit`` package.
409
410.. _migration-2.2-miscellaneous-changes:
411
412Miscellaneous Changes
413---------------------
414
415The following miscellaneous changes have occurred:
416
417- ``package_regex.inc``: Removed because the definitions
418 ``package_regex.inc`` previously contained have been moved to their
419 respective recipes.
420
421- Both ``devtool add`` and ``recipetool create`` now use a fixed
422 :term:`SRCREV` by default when fetching from a Git
423 repository. You can override this in either case to use
424 ``${``\ :term:`AUTOREV`\ ``}`` instead by using the
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700425 ``-a`` or ``--autorev`` command-line option
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500426
427- ``distcc``: GTK+ UI is now disabled by default.
428
429- ``packagegroup-core-tools-testapps``: Removed Piglit.
430
431- ``image.bbclass``: Renamed COMPRESS(ION) to CONVERSION. This change
432 means that ``COMPRESSIONTYPES``, ``COMPRESS_DEPENDS`` and
433 ``COMPRESS_CMD`` are deprecated in favor of ``CONVERSIONTYPES``,
434 ``CONVERSION_DEPENDS`` and ``CONVERSION_CMD``. The ``COMPRESS*``
435 variable names will still work in the 2.2 release but metadata that
436 does not need to be backwards-compatible should be changed to use the
437 new names as the ``COMPRESS*`` ones will be removed in a future
438 release.
439
440- ``gtk-doc``: A full version of ``gtk-doc`` is now made available.
441 However, some old software might not be capable of using the current
442 version of ``gtk-doc`` to build documentation. You need to change
443 recipes that build such software so that they explicitly disable
444 building documentation with ``gtk-doc``.
445
446