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