summaryrefslogtreecommitdiffstats
path: root/documentation/ref-manual/migration-2.2.rst
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/ref-manual/migration-2.2.rst')
-rw-r--r--documentation/ref-manual/migration-2.2.rst451
1 files changed, 451 insertions, 0 deletions
diff --git a/documentation/ref-manual/migration-2.2.rst b/documentation/ref-manual/migration-2.2.rst
new file mode 100644
index 0000000000..59d0eeeb9d
--- /dev/null
+++ b/documentation/ref-manual/migration-2.2.rst
@@ -0,0 +1,451 @@
1Moving 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
19 For x86 and x86_64, you can reset
20 OLDEST_KERNEL
21 to anything down to 2.6.32 if desired.
22
23.. _migration-2.2-staging-directories-in-sysroot-simplified:
24
25Staging Directories in Sysroot Has Been Simplified
26--------------------------------------------------
27
28The way directories are staged in sysroot has been simplified and
29introduces the new :term:`SYSROOT_DIRS`,
30:term:`SYSROOT_DIRS_NATIVE`, and
31:term:`SYSROOT_DIRS_BLACKLIST`. See the
32`v2 patch series on the OE-Core Mailing
33List <http://lists.openembedded.org/pipermail/openembedded-core/2016-May/121365.html>`__
34for additional information.
35
36.. _migration-2.2-removal-of-old-images-from-tmp-deploy-now-enabled:
37
38Removal of Old Images and Other Files in ``tmp/deploy`` Now Enabled
39-------------------------------------------------------------------
40
41Removal of old images and other files in ``tmp/deploy/`` is now enabled
42by default due to a new staging method used for those files. As a result
43of this change, the ``RM_OLD_IMAGE`` variable is now redundant.
44
45.. _migration-2.2-python-changes:
46
47Python Changes
48--------------
49
50The following changes for Python occurred:
51
52.. _migration-2.2-bitbake-now-requires-python-3.4:
53
54BitBake Now Requires Python 3.4+
55~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
56
57BitBake requires Python 3.4 or greater.
58
59.. _migration-2.2-utf-8-locale-required-on-build-host:
60
61UTF-8 Locale Required on Build Host
62~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
63
64A UTF-8 locale is required on the build host due to Python 3. Since
65C.UTF-8 is not a standard, the default is en_US.UTF-8.
66
67.. _migration-2.2-metadata-now-must-use-python-3-syntax:
68
69Metadata Must Now Use Python 3 Syntax
70~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
71
72The metadata is now required to use Python 3 syntax. For help preparing
73metadata, see any of the many Python 3 porting guides available.
74Alternatively, you can reference the conversion commits for Bitbake and
75you can use :term:`OpenEmbedded-Core (OE-Core)` as a guide for changes. Following are
76particular areas of interest:
77
78 - subprocess command-line pipes needing locale decoding
79
80 - the syntax for octal values changed
81
82 - the ``iter*()`` functions changed name \* iterators now return views, not lists
83
84 - changed names for Python modules
85
86.. _migration-2.2-target-python-recipes-switched-to-python-3:
87
88Target Python Recipes Switched to Python 3
89~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
90
91Most target Python recipes have now been switched to Python 3.
92Unfortunately, systems using RPM as a package manager and providing
93online package-manager support through SMART still require Python 2.
94
95.. note::
96
97 Python 2 and recipes that use it can still be built for the target as
98 with previous versions.
99
100.. _migration-2.2-buildtools-tarball-includes-python-3:
101
102``buildtools-tarball`` Includes Python 3
103~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
104
105``buildtools-tarball`` now includes Python 3.
106
107.. _migration-2.2-uclibc-replaced-by-musl:
108
109uClibc Replaced by musl
110-----------------------
111
112uClibc has been removed in favor of musl. Musl has matured, is better
113maintained, and is compatible with a wider range of applications as
114compared to uClibc.
115
116.. _migration-2.2-B-no-longer-default-working-directory-for-tasks:
117
118``${B}`` No Longer Default Working Directory for Tasks
119------------------------------------------------------
120
121``${``\ :term:`B`\ ``}`` is no longer the default working
122directory for tasks. Consequently, any custom tasks you define now need
123to either have the
124``[``\ :ref:`dirs <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:variable flags>`\ ``]`` flag
125set, or the task needs to change into the appropriate working directory
126manually (e.g using ``cd`` for a shell task).
127
128.. note::
129
130 The preferred method is to use the
131 [dirs]
132 flag.
133
134.. _migration-2.2-runqemu-ported-to-python:
135
136``runqemu`` Ported to Python
137----------------------------
138
139``runqemu`` has been ported to Python and has changed behavior in some
140cases. Previous usage patterns continue to be supported.
141
142The new ``runqemu`` is a Python script. Machine knowledge is no longer
143hardcoded into ``runqemu``. You can choose to use the ``qemuboot``
144configuration file to define the BSP's own arguments and to make it
145bootable with ``runqemu``. If you use a configuration file, use the
146following form:
147::
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 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
162following command form:
163::
164
165 $ runqemu machine rootfs kernel [options]
166
167Supported machines are as follows:
168
169 - qemuarm
170 - qemuarm64
171 - qemux86
172 - qemux86-64
173 - qemuppc
174 - qemumips
175 - qemumips64
176 - qemumipsel
177 - qemumips64el
178
179Consider the
180following example, which uses the ``qemux86-64`` machine, provides a
181root filesystem, provides an image, and uses the ``nographic`` option: ::
182
183 $ runqemu qemux86-64 tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64.ext4 tmp/deploy/images/qemux86-64/bzImage nographic
184
185Following is a list of variables that can be set in configuration files
186such as ``bsp.conf`` to enable the BSP to be booted by ``runqemu``:
187
188.. note::
189
190 "QB" means "QEMU Boot".
191
192::
193
194 QB_SYSTEM_NAME: QEMU name (e.g. "qemu-system-i386")
195 QB_OPT_APPEND: Options to append to QEMU (e.g. "-show-cursor")
196 QB_DEFAULT_KERNEL: Default kernel to boot (e.g. "bzImage")
197 QB_DEFAULT_FSTYPE: Default FSTYPE to boot (e.g. "ext4")
198 QB_MEM: Memory (e.g. "-m 512")
199 QB_MACHINE: QEMU machine (e.g. "-machine virt")
200 QB_CPU: QEMU cpu (e.g. "-cpu qemu32")
201 QB_CPU_KVM: Similar to QB_CPU except used for kvm support (e.g. "-cpu kvm64")
202 QB_KERNEL_CMDLINE_APPEND: Options to append to the kernel's -append
203 option (e.g. "console=ttyS0 console=tty")
204 QB_DTB: QEMU dtb name
205 QB_AUDIO_DRV: QEMU audio driver (e.g. "alsa", set it when support audio)
206 QB_AUDIO_OPT: QEMU audio option (e.g. "-soundhw ac97,es1370"), which is used
207 when QB_AUDIO_DRV is set.
208 QB_KERNEL_ROOT: Kernel's root (e.g. /dev/vda)
209 QB_TAP_OPT: Network option for 'tap' mode (e.g.
210 "-netdev tap,id=net0,ifname=@TAP@,script=no,downscript=no -device virtio-net-device,netdev=net0").
211 runqemu will replace "@TAP@" with the one that is used, such as tap0, tap1 ...
212 QB_SLIRP_OPT: Network option for SLIRP mode (e.g. "-netdev user,id=net0 -device virtio-net-device,netdev=net0")
213 QB_ROOTFS_OPT: Used as rootfs (e.g.
214 "-drive id=disk0,file=@ROOTFS@,if=none,format=raw -device virtio-blk-device,drive=disk0").
215 runqemu will replace "@ROOTFS@" with the one which is used, such as
216 core-image-minimal-qemuarm64.ext4.
217 QB_SERIAL_OPT: Serial port (e.g. "-serial mon:stdio")
218 QB_TCPSERIAL_OPT: tcp serial port option (e.g.
219 " -device virtio-serial-device -chardev socket,id=virtcon,port=@PORT@,host=127.0.0.1 -device virtconsole,chardev=virtcon"
220 runqemu will replace "@PORT@" with the port number which is used.
221
222To use ``runqemu``, set :term:`IMAGE_CLASSES` as
223follows and run ``runqemu``:
224
225.. note::
226
227 For command-line syntax, use
228 runqemu help
229 .
230
231::
232
233 IMAGE_CLASSES += "qemuboot"
234
235.. _migration-2.2-default-linker-hash-style-changed:
236
237Default Linker Hash Style Changed
238---------------------------------
239
240The default linker hash style for ``gcc-cross`` is now "sysv" in order
241to catch recipes that are building software without using the
242OpenEmbedded :term:`LDFLAGS`. This change could result in
243seeing some "No GNU_HASH in the elf binary" QA issues when building such
244recipes. You need to fix these recipes so that they use the expected
245``LDFLAGS``. Depending on how the software is built, the build system
246used by the software (e.g. a Makefile) might need to be patched.
247However, sometimes making this fix is as simple as adding the following
248to the recipe:
249::
250
251 TARGET_CC_ARCH += "${LDFLAGS}"
252
253.. _migration-2.2-kernel-image-base-name-no-longer-uses-kernel-imagetype:
254
255``KERNEL_IMAGE_BASE_NAME`` no Longer Uses ``KERNEL_IMAGETYPE``
256--------------------------------------------------------------
257
258The ``KERNEL_IMAGE_BASE_NAME`` variable no longer uses the
259:term:`KERNEL_IMAGETYPE` variable to create the
260image's base name. Because the OpenEmbedded build system can now build
261multiple kernel image types, this part of the kernel image base name as
262been removed leaving only the following:
263::
264
265 KERNEL_IMAGE_BASE_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}-${DATETIME}"
266
267If you have recipes or
268classes that use ``KERNEL_IMAGE_BASE_NAME`` directly, you might need to
269update the references to ensure they continue to work.
270
271.. _migration-2.2-bitbake-changes:
272
273BitBake Changes
274---------------
275
276The following changes took place for BitBake:
277
278- The "goggle" UI and standalone image-writer tool have been removed as
279 they both require GTK+ 2.0 and were not being maintained.
280
281- The Perforce fetcher now supports :term:`SRCREV` for
282 specifying the source revision to use, be it
283 ``${``\ :term:`AUTOREV`\ ``}``, changelist number,
284 p4date, or label, in preference to separate
285 :term:`SRC_URI` parameters to specify these. This
286 change is more in-line with how the other fetchers work for source
287 control systems. Recipes that fetch from Perforce will need to be
288 updated to use ``SRCREV`` in place of specifying the source revision
289 within ``SRC_URI``.
290
291- Some of BitBake's internal code structures for accessing the recipe
292 cache needed to be changed to support the new multi-configuration
293 functionality. These changes will affect external tools that use
294 BitBake's tinfoil module. For information on these changes, see the
295 changes made to the scripts supplied with OpenEmbedded-Core:
296 `1 <http://git.yoctoproject.org/cgit/cgit.cgi/poky/commit/?id=189371f8393971d00bca0fceffd67cc07784f6ee>`__
297 and
298 `2 <http://git.yoctoproject.org/cgit/cgit.cgi/poky/commit/?id=4a5aa7ea4d07c2c90a1654b174873abb018acc67>`__.
299
300- The task management code has been rewritten to avoid using ID
301 indirection in order to improve performance. This change is unlikely
302 to cause any problems for most users. However, the setscene
303 verification function as pointed to by
304 ``BB_SETSCENE_VERIFY_FUNCTION`` needed to change signature.
305 Consequently, a new variable named ``BB_SETSCENE_VERIFY_FUNCTION2``
306 has been added allowing multiple versions of BitBake to work with
307 suitably written metadata, which includes OpenEmbedded-Core and Poky.
308 Anyone with custom BitBake task scheduler code might also need to
309 update the code to handle the new structure.
310
311.. _migration-2.2-swabber-has-been-removed:
312
313Swabber has Been Removed
314------------------------
315
316Swabber, a tool that was intended to detect host contamination in the
317build process, has been removed, as it has been unmaintained and unused
318for some time and was never particularly effective. The OpenEmbedded
319build system has since incorporated a number of mechanisms including
320enhanced QA checks that mean that there is less of a need for such a
321tool.
322
323.. _migration-2.2-removed-recipes:
324
325Removed Recipes
326---------------
327
328The following recipes have been removed:
329
330- ``augeas``: No longer needed and has been moved to ``meta-oe``.
331
332- ``directfb``: Unmaintained and has been moved to ``meta-oe``.
333
334- ``gcc``: Removed 4.9 version. Versions 5.4 and 6.2 are still present.
335
336- ``gnome-doc-utils``: No longer needed.
337
338- ``gtk-doc-stub``: Replaced by ``gtk-doc``.
339
340- ``gtk-engines``: No longer needed and has been moved to
341 ``meta-gnome``.
342
343- ``gtk-sato-engine``: Became obsolete.
344
345- ``libglade``: No longer needed and has been moved to ``meta-oe``.
346
347- ``libmad``: Unmaintained and functionally replaced by ``libmpg123``.
348 ``libmad`` has been moved to ``meta-oe``.
349
350- ``libowl``: Became obsolete.
351
352- ``libxsettings-client``: No longer needed.
353
354- ``oh-puzzles``: Functionally replaced by ``puzzles``.
355
356- ``oprofileui``: Became obsolete. OProfile has been largely supplanted
357 by perf.
358
359- ``packagegroup-core-directfb.bb``: Removed.
360
361- ``core-image-directfb.bb``: Removed.
362
363- ``pointercal``: No longer needed and has been moved to ``meta-oe``.
364
365- ``python-imaging``: No longer needed and moved to ``meta-python``
366
367- ``python-pyrex``: No longer needed and moved to ``meta-python``.
368
369- ``sato-icon-theme``: Became obsolete.
370
371- ``swabber-native``: Swabber has been removed. See the `entry on
372 Swabber <#migration-2.2-swabber-has-been-removed>`__.
373
374- ``tslib``: No longer needed and has been moved to ``meta-oe``.
375
376- ``uclibc``: Removed in favor of musl.
377
378- ``xtscal``: No longer needed and moved to ``meta-oe``
379
380.. _migration-2.2-removed-classes:
381
382Removed Classes
383---------------
384
385The following classes have been removed:
386
387- ``distutils-native-base``: No longer needed.
388
389- ``distutils3-native-base``: No longer needed.
390
391- ``sdl``: Only set :term:`DEPENDS` and
392 :term:`SECTION`, which are better set within the
393 recipe instead.
394
395- ``sip``: Mostly unused.
396
397- ``swabber``: See the `entry on
398 Swabber <#migration-2.2-swabber-has-been-removed>`__.
399
400.. _migration-2.2-minor-packaging-changes:
401
402Minor Packaging Changes
403-----------------------
404
405The following minor packaging changes have occurred:
406
407- ``grub``: Split ``grub-editenv`` into its own package.
408
409- ``systemd``: Split container and vm related units into a new package,
410 systemd-container.
411
412- ``util-linux``: Moved ``prlimit`` to a separate
413 ``util-linux-prlimit`` package.
414
415.. _migration-2.2-miscellaneous-changes:
416
417Miscellaneous Changes
418---------------------
419
420The following miscellaneous changes have occurred:
421
422- ``package_regex.inc``: Removed because the definitions
423 ``package_regex.inc`` previously contained have been moved to their
424 respective recipes.
425
426- Both ``devtool add`` and ``recipetool create`` now use a fixed
427 :term:`SRCREV` by default when fetching from a Git
428 repository. You can override this in either case to use
429 ``${``\ :term:`AUTOREV`\ ``}`` instead by using the
430 ``-a`` or ``DASHDASHautorev`` command-line option
431
432- ``distcc``: GTK+ UI is now disabled by default.
433
434- ``packagegroup-core-tools-testapps``: Removed Piglit.
435
436- ``image.bbclass``: Renamed COMPRESS(ION) to CONVERSION. This change
437 means that ``COMPRESSIONTYPES``, ``COMPRESS_DEPENDS`` and
438 ``COMPRESS_CMD`` are deprecated in favor of ``CONVERSIONTYPES``,
439 ``CONVERSION_DEPENDS`` and ``CONVERSION_CMD``. The ``COMPRESS*``
440 variable names will still work in the 2.2 release but metadata that
441 does not need to be backwards-compatible should be changed to use the
442 new names as the ``COMPRESS*`` ones will be removed in a future
443 release.
444
445- ``gtk-doc``: A full version of ``gtk-doc`` is now made available.
446 However, some old software might not be capable of using the current
447 version of ``gtk-doc`` to build documentation. You need to change
448 recipes that build such software so that they explicitly disable
449 building documentation with ``gtk-doc``.
450
451