blob: 5c6fecf328e452f220418281ef1660fe36d67256 [file] [log] [blame]
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001Moving to the Yocto Project 2.2 Release
2=======================================
3
4This section provides migration information for moving to the Yocto
5Project 2.2 Release 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
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 Geisslerc723b722021-01-08 16:14:09 -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
147following form:
148::
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 build (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
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.. note::
190
191 "QB" means "QEMU Boot".
192
193::
194
195 QB_SYSTEM_NAME: QEMU name (e.g. "qemu-system-i386")
196 QB_OPT_APPEND: Options to append to QEMU (e.g. "-show-cursor")
197 QB_DEFAULT_KERNEL: Default kernel to boot (e.g. "bzImage")
198 QB_DEFAULT_FSTYPE: Default FSTYPE to boot (e.g. "ext4")
199 QB_MEM: Memory (e.g. "-m 512")
200 QB_MACHINE: QEMU machine (e.g. "-machine virt")
201 QB_CPU: QEMU cpu (e.g. "-cpu qemu32")
202 QB_CPU_KVM: Similar to QB_CPU except used for kvm support (e.g. "-cpu kvm64")
203 QB_KERNEL_CMDLINE_APPEND: Options to append to the kernel's -append
204 option (e.g. "console=ttyS0 console=tty")
205 QB_DTB: QEMU dtb name
206 QB_AUDIO_DRV: QEMU audio driver (e.g. "alsa", set it when support audio)
207 QB_AUDIO_OPT: QEMU audio option (e.g. "-soundhw ac97,es1370"), which is used
208 when QB_AUDIO_DRV is set.
209 QB_KERNEL_ROOT: Kernel's root (e.g. /dev/vda)
210 QB_TAP_OPT: Network option for 'tap' mode (e.g.
211 "-netdev tap,id=net0,ifname=@TAP@,script=no,downscript=no -device virtio-net-device,netdev=net0").
212 runqemu will replace "@TAP@" with the one that is used, such as tap0, tap1 ...
213 QB_SLIRP_OPT: Network option for SLIRP mode (e.g. "-netdev user,id=net0 -device virtio-net-device,netdev=net0")
214 QB_ROOTFS_OPT: Used as rootfs (e.g.
215 "-drive id=disk0,file=@ROOTFS@,if=none,format=raw -device virtio-blk-device,drive=disk0").
216 runqemu will replace "@ROOTFS@" with the one which is used, such as
217 core-image-minimal-qemuarm64.ext4.
218 QB_SERIAL_OPT: Serial port (e.g. "-serial mon:stdio")
219 QB_TCPSERIAL_OPT: tcp serial port option (e.g.
220 " -device virtio-serial-device -chardev socket,id=virtcon,port=@PORT@,host=127.0.0.1 -device virtconsole,chardev=virtcon"
221 runqemu will replace "@PORT@" with the port number which is used.
222
223To use ``runqemu``, set :term:`IMAGE_CLASSES` as
224follows and run ``runqemu``:
225
226.. note::
227
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500228 For command-line syntax, use ``runqemu help``.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500229
230::
231
232 IMAGE_CLASSES += "qemuboot"
233
234.. _migration-2.2-default-linker-hash-style-changed:
235
236Default Linker Hash Style Changed
237---------------------------------
238
239The default linker hash style for ``gcc-cross`` is now "sysv" in order
240to catch recipes that are building software without using the
241OpenEmbedded :term:`LDFLAGS`. This change could result in
242seeing some "No GNU_HASH in the elf binary" QA issues when building such
243recipes. You need to fix these recipes so that they use the expected
244``LDFLAGS``. Depending on how the software is built, the build system
245used by the software (e.g. a Makefile) might need to be patched.
246However, sometimes making this fix is as simple as adding the following
247to the recipe:
248::
249
250 TARGET_CC_ARCH += "${LDFLAGS}"
251
252.. _migration-2.2-kernel-image-base-name-no-longer-uses-kernel-imagetype:
253
254``KERNEL_IMAGE_BASE_NAME`` no Longer Uses ``KERNEL_IMAGETYPE``
255--------------------------------------------------------------
256
257The ``KERNEL_IMAGE_BASE_NAME`` variable no longer uses the
258:term:`KERNEL_IMAGETYPE` variable to create the
259image's base name. Because the OpenEmbedded build system can now build
260multiple kernel image types, this part of the kernel image base name as
261been removed leaving only the following:
262::
263
264 KERNEL_IMAGE_BASE_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}-${DATETIME}"
265
266If you have recipes or
267classes that use ``KERNEL_IMAGE_BASE_NAME`` directly, you might need to
268update the references to ensure they continue to work.
269
270.. _migration-2.2-bitbake-changes:
271
272BitBake Changes
273---------------
274
275The following changes took place for BitBake:
276
277- The "goggle" UI and standalone image-writer tool have been removed as
278 they both require GTK+ 2.0 and were not being maintained.
279
280- The Perforce fetcher now supports :term:`SRCREV` for
281 specifying the source revision to use, be it
282 ``${``\ :term:`AUTOREV`\ ``}``, changelist number,
283 p4date, or label, in preference to separate
284 :term:`SRC_URI` parameters to specify these. This
285 change is more in-line with how the other fetchers work for source
286 control systems. Recipes that fetch from Perforce will need to be
287 updated to use ``SRCREV`` in place of specifying the source revision
288 within ``SRC_URI``.
289
290- Some of BitBake's internal code structures for accessing the recipe
291 cache needed to be changed to support the new multi-configuration
292 functionality. These changes will affect external tools that use
293 BitBake's tinfoil module. For information on these changes, see the
294 changes made to the scripts supplied with OpenEmbedded-Core:
Andrew Geissler09209ee2020-12-13 08:44:15 -0600295 :yocto_git:`1 </poky/commit/?id=189371f8393971d00bca0fceffd67cc07784f6ee>`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500296 and
Andrew Geissler09209ee2020-12-13 08:44:15 -0600297 :yocto_git:`2 </poky/commit/?id=4a5aa7ea4d07c2c90a1654b174873abb018acc67>`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500298
299- The task management code has been rewritten to avoid using ID
300 indirection in order to improve performance. This change is unlikely
301 to cause any problems for most users. However, the setscene
302 verification function as pointed to by
303 ``BB_SETSCENE_VERIFY_FUNCTION`` needed to change signature.
304 Consequently, a new variable named ``BB_SETSCENE_VERIFY_FUNCTION2``
305 has been added allowing multiple versions of BitBake to work with
306 suitably written metadata, which includes OpenEmbedded-Core and Poky.
307 Anyone with custom BitBake task scheduler code might also need to
308 update the code to handle the new structure.
309
310.. _migration-2.2-swabber-has-been-removed:
311
312Swabber has Been Removed
313------------------------
314
315Swabber, a tool that was intended to detect host contamination in the
316build process, has been removed, as it has been unmaintained and unused
317for some time and was never particularly effective. The OpenEmbedded
318build system has since incorporated a number of mechanisms including
319enhanced QA checks that mean that there is less of a need for such a
320tool.
321
322.. _migration-2.2-removed-recipes:
323
324Removed Recipes
325---------------
326
327The following recipes have been removed:
328
329- ``augeas``: No longer needed and has been moved to ``meta-oe``.
330
331- ``directfb``: Unmaintained and has been moved to ``meta-oe``.
332
333- ``gcc``: Removed 4.9 version. Versions 5.4 and 6.2 are still present.
334
335- ``gnome-doc-utils``: No longer needed.
336
337- ``gtk-doc-stub``: Replaced by ``gtk-doc``.
338
339- ``gtk-engines``: No longer needed and has been moved to
340 ``meta-gnome``.
341
342- ``gtk-sato-engine``: Became obsolete.
343
344- ``libglade``: No longer needed and has been moved to ``meta-oe``.
345
346- ``libmad``: Unmaintained and functionally replaced by ``libmpg123``.
347 ``libmad`` has been moved to ``meta-oe``.
348
349- ``libowl``: Became obsolete.
350
351- ``libxsettings-client``: No longer needed.
352
353- ``oh-puzzles``: Functionally replaced by ``puzzles``.
354
355- ``oprofileui``: Became obsolete. OProfile has been largely supplanted
356 by perf.
357
358- ``packagegroup-core-directfb.bb``: Removed.
359
360- ``core-image-directfb.bb``: Removed.
361
362- ``pointercal``: No longer needed and has been moved to ``meta-oe``.
363
364- ``python-imaging``: No longer needed and moved to ``meta-python``
365
366- ``python-pyrex``: No longer needed and moved to ``meta-python``.
367
368- ``sato-icon-theme``: Became obsolete.
369
370- ``swabber-native``: Swabber has been removed. See the `entry on
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500371 Swabber <#swabber-has-been-removed>`__.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500372
373- ``tslib``: No longer needed and has been moved to ``meta-oe``.
374
375- ``uclibc``: Removed in favor of musl.
376
377- ``xtscal``: No longer needed and moved to ``meta-oe``
378
379.. _migration-2.2-removed-classes:
380
381Removed Classes
382---------------
383
384The following classes have been removed:
385
386- ``distutils-native-base``: No longer needed.
387
388- ``distutils3-native-base``: No longer needed.
389
390- ``sdl``: Only set :term:`DEPENDS` and
391 :term:`SECTION`, which are better set within the
392 recipe instead.
393
394- ``sip``: Mostly unused.
395
396- ``swabber``: See the `entry on
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500397 Swabber <#swabber-has-been-removed>`__.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500398
399.. _migration-2.2-minor-packaging-changes:
400
401Minor Packaging Changes
402-----------------------
403
404The following minor packaging changes have occurred:
405
406- ``grub``: Split ``grub-editenv`` into its own package.
407
408- ``systemd``: Split container and vm related units into a new package,
409 systemd-container.
410
411- ``util-linux``: Moved ``prlimit`` to a separate
412 ``util-linux-prlimit`` package.
413
414.. _migration-2.2-miscellaneous-changes:
415
416Miscellaneous Changes
417---------------------
418
419The following miscellaneous changes have occurred:
420
421- ``package_regex.inc``: Removed because the definitions
422 ``package_regex.inc`` previously contained have been moved to their
423 respective recipes.
424
425- Both ``devtool add`` and ``recipetool create`` now use a fixed
426 :term:`SRCREV` by default when fetching from a Git
427 repository. You can override this in either case to use
428 ``${``\ :term:`AUTOREV`\ ``}`` instead by using the
429 ``-a`` or ``DASHDASHautorev`` command-line option
430
431- ``distcc``: GTK+ UI is now disabled by default.
432
433- ``packagegroup-core-tools-testapps``: Removed Piglit.
434
435- ``image.bbclass``: Renamed COMPRESS(ION) to CONVERSION. This change
436 means that ``COMPRESSIONTYPES``, ``COMPRESS_DEPENDS`` and
437 ``COMPRESS_CMD`` are deprecated in favor of ``CONVERSIONTYPES``,
438 ``CONVERSION_DEPENDS`` and ``CONVERSION_CMD``. The ``COMPRESS*``
439 variable names will still work in the 2.2 release but metadata that
440 does not need to be backwards-compatible should be changed to use the
441 new names as the ``COMPRESS*`` ones will be removed in a future
442 release.
443
444- ``gtk-doc``: A full version of ``gtk-doc`` is now made available.
445 However, some old software might not be capable of using the current
446 version of ``gtk-doc`` to build documentation. You need to change
447 recipes that build such software so that they explicitly disable
448 building documentation with ``gtk-doc``.
449
450