blob: c19ba5501cc7ffd4c9eabf57bf37a601a2adaa6e [file] [log] [blame]
Andrew Geissler09036742021-06-25 14:25:14 -05001Release 2.1 (krogoth)
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.1 Release (codename "krogoth") from the prior release.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006
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
Andrew Geissler09036742021-06-25 14:25:14 -050031appear in lower-case characters (e.g. values for :term:`MACHINE`,
32:term:`TARGET_ARCH`, :term:`DISTRO`, and also recipe names if
Andrew Geisslerc9f78652020-09-18 14:11:35 -050033``_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
Andrew Geisslerc926e172021-05-07 16:11:35 -050045layer to make this change::
Andrew Geisslerc9f78652020-09-18 14:11:35 -050046
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
Andrew Geissler5f350902021-07-23 13:09:54 -040065"-e MAKEFLAGS=". Setting :term:`EXTRA_OEMAKE` to "-e MAKEFLAGS=" by default
Andrew Geisslerc9f78652020-09-18 14:11:35 -050066was 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
Andrew Geissler5f350902021-07-23 13:09:54 -040070:term:`EXTRA_OEMAKE` back to "-e MAKEFLAGS=" or by explicitly setting any
Andrew Geissler09036742021-06-25 14:25:14 -050071required variable value overrides using :term:`EXTRA_OEMAKE`, which is
Andrew Geisslerc9f78652020-09-18 14:11:35 -050072typically 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.
Andrew Geisslerd1e89492021-02-12 15:35:20 -060091https://refspecs.linuxfoundation.org/FHS_3.0/fhs/ch04s07.html) now
Andrew Geisslerc9f78652020-09-18 14:11:35 -050092recognizes 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
Andrew Geissler595f6302022-01-24 19:11:47 +0000109from the :ref:`autotools <ref-classes-autotools>` class and the software the recipe is building
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500110uses a very old version of ``autoconf``, the recipe might be incapable
Patrick Williams2194f502022-10-16 14:26:09 -0500111of determining the correct size of ``off_t`` during :ref:`ref-tasks-configure`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500112
113The best course of action is to patch the software as necessary to allow
Andrew Geissler595f6302022-01-24 19:11:47 +0000114the default implementation from the :ref:`autotools <ref-classes-autotools>` class to work such
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500115that ``autoreconf`` succeeds and produces a working configure script,
Patrick Williams2194f502022-10-16 14:26:09 -0500116and to remove the overridden :ref:`ref-tasks-configure` task such that the default
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500117implementation 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
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500127separate :ref:`ref-tasks-image` tasks for clarity both in
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500128operation and in the code.
129
130For most cases, this change does not present any problems. However, if
Patrick Williams2194f502022-10-16 14:26:09 -0500131you have made customizations that directly modify the :ref:`ref-tasks-rootfs` task
132or that mention :ref:`ref-tasks-rootfs`, you might need to update those changes.
133In particular, if you had added any tasks after :ref:`ref-tasks-rootfs`, you
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500134should make edits so that those tasks are after the
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500135:ref:`ref-tasks-image-complete` task rather than
Patrick Williams2194f502022-10-16 14:26:09 -0500136after :ref:`ref-tasks-rootfs` so that your added tasks run at the correct
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500137time.
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
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500181- ``adt-installer``: Recipe became obsolete. See the
Andrew Geissler09036742021-06-25 14:25:14 -0500182 ":ref:`migration-guides/migration-2.1:adt removed`" section for more information.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500183
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
Andrew Geissler09209ee2020-12-13 08:44:15 -0600218 ":ref:`toaster-manual/setup-and-use:using the toaster web interface`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500219 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
Andrew Geissler09209ee2020-12-13 08:44:15 -0600232SDK <sdk-manual/using:using the standard sdk>` and the
233:ref:`extensible SDK <sdk-manual/extensible:using the extensible sdk>`. For
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500234information on these SDKs and how to build and use them, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600235:doc:`/sdk-manual/index` manual.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500236
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
Andrew Geissler595f6302022-01-24 19:11:47 +0000265 The :ref:`uninative <ref-classes-uninative>` class is enabled through the
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500266 ``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
Patrick Williams45852732022-04-02 08:58:32 -0500284 Any recipe that needs to opt-out of having the ``--disable-static``
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500285 option specified on the configure command line either because it is
286 not a supported option for the configure script or because static
Andrew Geisslerc926e172021-05-07 16:11:35 -0500287 libraries are needed should set the following variable::
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500288
289 DISABLE_STATIC = ""
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500290
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
Andrew Geissler09209ee2020-12-13 08:44:15 -0600346":ref:`dev-manual/common-tasks:enabling gobject introspection support`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500347section 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
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500359 install the buildtools, which will provide it. See the
Andrew Geissler615f2f12022-07-15 14:00:58 -0500360 :ref:`ref-manual/system-requirements:required git, tar, python, make and gcc versions`
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500361 section for more information on the buildtools tarball.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500362
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
Andrew Geisslerc926e172021-05-07 16:11:35 -0500370 dependencies::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500371
372 update-rc.d
373 base-passwd
374 shadow
375 update-alternatives
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500376 run-postinsts
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500377
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500378 With the Yocto Project 2.1 release, these packages are
Andrew Geissler09036742021-06-25 14:25:14 -0500379 only removed if "read-only-rootfs" is in :term:`IMAGE_FEATURES`, since
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500380 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
Andrew Geissler09209ee2020-12-13 08:44:15 -0600385 :ref:`devtool modify <sdk-manual/extensible:use \`\`devtool modify\`\` to modify the source of an existing component>`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500386 command now defaults to extracting the source since that is most
Patrick Williams45852732022-04-02 08:58:32 -0500387 commonly expected. The ``-x`` or ``--extract`` options are now no-ops. If
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500388 you wish to provide your own existing source tree, you will now need
Patrick Williams45852732022-04-02 08:58:32 -0500389 to specify either the ``-n`` or ``--no-extract`` options when running
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500390 ``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