blob: b5bd57c3128a0f437f901ba2f7cc658745035b17 [file] [log] [blame]
Andrew Geissler517393d2023-01-13 08:55:19 -06001.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
2
Patrick Williams03907ee2022-05-01 06:28:52 -05003Release 4.0 (kirkstone)
4=======================
5
6Migration notes for 4.0 (kirkstone)
7-----------------------------------
8
9This section provides migration information for moving to the Yocto
10Project 4.0 Release (codename "kirkstone") from the prior release.
11
12.. _migration-4.0-inclusive-language:
13
14Inclusive language improvements
15~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
16
17To use more `inclusive language <https://inclusivenaming.org/>`__
18in the code and documentation, some variables have been renamed, and
19some have been deleted where they are no longer needed. In many cases the
20new names are also easier to understand. BitBake will stop with an error when
21renamed or removed variables still exist in your recipes or configuration.
22
23Please note that the change applies also to environmental variables, so
24make sure you use a fresh environment for your build.
25
26The following variables have changed their names:
27
28- ``BB_ENV_WHITELIST`` became :term:`BB_ENV_PASSTHROUGH`
29- ``BB_ENV_EXTRAWHITE`` became :term:`BB_ENV_PASSTHROUGH_ADDITIONS`
30- ``BB_HASHBASE_WHITELIST`` became :term:`BB_BASEHASH_IGNORE_VARS`
31- ``BB_HASHCONFIG_WHITELIST`` became :term:`BB_HASHCONFIG_IGNORE_VARS`
32- ``BB_HASHTASK_WHITELIST`` became ``BB_TASKHASH_IGNORE_TASKS``
33- ``BB_SETSCENE_ENFORCE_WHITELIST`` became ``BB_SETSCENE_ENFORCE_IGNORE_TASKS``
34- ``CVE_CHECK_PN_WHITELIST`` became :term:`CVE_CHECK_SKIP_RECIPE`
35- ``CVE_CHECK_WHITELIST`` became :term:`CVE_CHECK_IGNORE`
36- ``ICECC_USER_CLASS_BL`` became :term:`ICECC_CLASS_DISABLE`
37- ``ICECC_SYSTEM_CLASS_BL`` became :term:`ICECC_CLASS_DISABLE`
38- ``ICECC_USER_PACKAGE_WL`` became :term:`ICECC_RECIPE_ENABLE`
39- ``ICECC_USER_PACKAGE_BL`` became :term:`ICECC_RECIPE_DISABLE`
40- ``ICECC_SYSTEM_PACKAGE_BL`` became :term:`ICECC_RECIPE_DISABLE`
41- ``LICENSE_FLAGS_WHITELIST`` became :term:`LICENSE_FLAGS_ACCEPTED`
42- ``MULTI_PROVIDER_WHITELIST`` became :term:`BB_MULTI_PROVIDER_ALLOWED`
43- ``PNBLACKLIST`` became :term:`SKIP_RECIPE`
44- ``SDK_LOCAL_CONF_BLACKLIST`` became :term:`ESDK_LOCALCONF_REMOVE`
45- ``SDK_LOCAL_CONF_WHITELIST`` became :term:`ESDK_LOCALCONF_ALLOW`
46- ``SDK_INHERIT_BLACKLIST`` became :term:`ESDK_CLASS_INHERIT_DISABLE`
47- ``SSTATE_DUPWHITELIST`` became ``SSTATE_ALLOW_OVERLAP_FILES``
48- ``SYSROOT_DIRS_BLACKLIST`` became :term:`SYSROOT_DIRS_IGNORE`
49- ``UNKNOWN_CONFIGURE_WHITELIST`` became :term:`UNKNOWN_CONFIGURE_OPT_IGNORE`
Andrew Geissler615f2f12022-07-15 14:00:58 -050050- ``WHITELIST_<license>`` became :term:`INCOMPATIBLE_LICENSE_EXCEPTIONS`
Patrick Williams03907ee2022-05-01 06:28:52 -050051
52In addition, ``BB_STAMP_WHITELIST``, ``BB_STAMP_POLICY``, ``INHERIT_BLACKLIST``,
53``TUNEABI``, ``TUNEABI_WHITELIST``, and ``TUNEABI_OVERRIDE`` have been removed.
54
55Many internal variable names have been also renamed accordingly.
56
57In addition, in the ``cve-check`` output, the CVE issue status ``Whitelisted``
58has been renamed to ``Ignored``.
59
60The :term:`BB_DISKMON_DIRS` variable value now uses the term ``HALT``
61instead of ``ABORT``.
62
63A :oe_git:`convert-variable-renames.py
64</openembedded-core/tree/scripts/contrib/convert-variable-renames.py>`
65script is provided to convert your recipes and configuration,
66and also warns you about the use of problematic words. The script performs
67changes and you need to review them before committing. An example warning
68looks like::
69
70 poky/scripts/lib/devtool/upgrade.py needs further work at line 275 since it contains abort
71
72Fetching changes
73~~~~~~~~~~~~~~~~
74
75- Because of the uncertainty in future default branch names in git repositories,
76 it is now required to add a branch name to all URLs described
77 by ``git://`` and ``gitsm://`` :term:`SRC_URI` entries. For example::
78
79 SRC_URI = "git://git.denx.de/u-boot.git;branch=master"
80
81 A :oe_git:`convert-srcuri </openembedded-core/tree/scripts/contrib/convert-srcuri.py>`
82 script to convert your recipes is available in :term:`OpenEmbedded-Core (OE-Core)`
83 and in :term:`Poky`.
84
85- Because of `GitHub dropping support for the git:
86 protocol <https://github.blog/2021-09-01-improving-git-protocol-security-github/>`__,
87 recipes now need to use ``;protocol=https`` at the end of GitHub
88 URLs. The same ``convert-srcuri`` script mentioned above can be used to convert
89 your recipes.
90
91- Network access from tasks is now disabled by default on kernels which support
92 this feature (on most recent distros such as CentOS 8 and Debian 11 onwards).
93 This means that tasks accessing the network need to be marked as such with the ``network``
94 flag. For example::
95
96 do_mytask[network] = "1"
97
Patrick Williams2194f502022-10-16 14:26:09 -050098 This is allowed by default from :ref:`ref-tasks-fetch` but not from any of our other standard
99 tasks. Recipes shouldn't be accessing the network outside of :ref:`ref-tasks-fetch` as it
Patrick Williams03907ee2022-05-01 06:28:52 -0500100 usually undermines fetcher source mirroring, image and licence manifests, software
101 auditing and supply chain security.
102
103License changes
104~~~~~~~~~~~~~~~
105
106- The ambiguous "BSD" license has been removed from the ``common-licenses`` directory.
107 Each recipe that fetches or builds BSD-licensed code should specify the proper
108 version of the BSD license in its :term:`LICENSE` value.
109
110- :term:`LICENSE` variable values should now use `SPDX identifiers <https://spdx.org/licenses/>`__.
111 If they do not, by default a warning will be shown. A
112 :oe_git:`convert-spdx-licenses.py </openembedded-core/tree/scripts/contrib/convert-spdx-licenses.py>`
113 script can be used to update your recipes.
114
115- :term:`INCOMPATIBLE_LICENSE` should now use `SPDX identifiers <https://spdx.org/licenses/>`__.
116 Additionally, wildcarding is now limited to specifically supported values -
117 see the :term:`INCOMPATIBLE_LICENSE` documentation for further information.
118
119- The ``AVAILABLE_LICENSES`` variable has been removed. This variable was a performance
120 liability and is highly dependent on which layers are added to the configuration,
121 which can cause signature issues for users. In addition the ``available_licenses()``
Andrew Geissler517393d2023-01-13 08:55:19 -0600122 function has been removed from the :ref:`ref-classes-license` class as
Patrick Williams03907ee2022-05-01 06:28:52 -0500123 it is no longer needed.
124
125Removed recipes
126~~~~~~~~~~~~~~~
127
128The following recipes have been removed in this release:
129
130- ``dbus-test``: merged into main dbus recipe
131- ``libid3tag``: moved to meta-oe - no longer needed by anything in OE-Core
132- ``libportal``: moved to meta-gnome - no longer needed by anything in OE-Core
133- ``linux-yocto``: removed version 5.14 recipes (5.15 and 5.10 still provided)
134- ``python3-nose``: has not changed since 2016 upstream, and no longer needed by anything in OE-Core
135- ``rustfmt``: not especially useful as a standalone recipe
136
137Python changes
138~~~~~~~~~~~~~~
139
140- ``distutils`` has been deprecated upstream in Python 3.10 and thus the ``distutils*``
141 classes have been moved to ``meta-python``. Recipes that inherit the ``distutils*``
142 classes should be updated to inherit ``setuptools*`` equivalents instead.
143
144- The Python package build process is now based on `wheels <https://pythonwheels.com/>`__.
Patrick Williams39653562024-03-01 08:54:02 -0600145 The new Python packaging classes that should be used are
Andrew Geissler517393d2023-01-13 08:55:19 -0600146 :ref:`ref-classes-python_flit_core`, :ref:`ref-classes-python_setuptools_build_meta`
147 and :ref:`ref-classes-python_poetry_core`.
Patrick Williams03907ee2022-05-01 06:28:52 -0500148
Andrew Geissler517393d2023-01-13 08:55:19 -0600149- The :ref:`ref-classes-setuptools3` class :ref:`ref-tasks-install` task now
Patrick Williams03907ee2022-05-01 06:28:52 -0500150 installs the ``wheel`` binary archive. In current versions of ``setuptools`` the
151 legacy ``setup.py install`` method is deprecated. If the ``setup.py`` cannot be used
152 with wheels, for example it creates files outside of the Python module or standard
Andrew Geissler517393d2023-01-13 08:55:19 -0600153 entry points, then :ref:`ref-classes-setuptools3_legacy` should
Patrick Williams03907ee2022-05-01 06:28:52 -0500154 be used instead.
155
156Prelink removed
157~~~~~~~~~~~~~~~
158
159Prelink has been dropped by ``glibc`` upstream in 2.36. It already caused issues with
160binary corruption, has a number of open bugs and is of questionable benefit
161without disabling load address randomization and PIE executables.
162
163We disabled prelinking by default in the honister (3.4) release, but left it able
164to be enabled if desired. However, without glibc support it cannot be maintained
165any further, so all of the prelinking functionality has been removed in this release.
166If you were enabling the ``image-prelink`` class in :term:`INHERIT`, :term:`IMAGE_CLASSES`,
167:term:`USER_CLASSES` etc in your configuration, then you will need to remove the
168reference(s).
169
170Reproducible as standard
171~~~~~~~~~~~~~~~~~~~~~~~~
172
173Reproducibility is now considered as standard functionality, thus the
174``reproducible`` class has been removed and its previous contents merged into the
Andrew Geissler517393d2023-01-13 08:55:19 -0600175:ref:`ref-classes-base` class. If you have references in your configuration to
Patrick Williams03907ee2022-05-01 06:28:52 -0500176``reproducible`` in :term:`INHERIT`, :term:`USER_CLASSES` etc. then they should be
177removed.
178
179Additionally, the ``BUILD_REPRODUCIBLE_BINARIES`` variable is no longer used.
180Specifically for the kernel, if you wish to enable build timestamping functionality
181that is normally disabled for reproducibility reasons, you can do so by setting
182a new :term:`KERNEL_DEBUG_TIMESTAMPS` variable to "1".
183
184Supported host distribution changes
185~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
186
Patrick Williams7784c422022-11-17 07:29:11 -0600187- Support for :wikipedia:`AlmaLinux <AlmaLinux>`
188 hosts replacing :wikipedia:`CentOS <CentOS>`.
Patrick Williams03907ee2022-05-01 06:28:52 -0500189 The following distribution versions were dropped: CentOS 8, Ubuntu 16.04 and Fedora 30, 31 and 32.
190
191- ``gcc`` version 7.5 is now required at minimum on the build host. For older
192 host distributions where this is not available, you can use the
Andrew Geissler517393d2023-01-13 08:55:19 -0600193 :term:`buildtools-extended` tarball (easily installable using
Patrick Williams03907ee2022-05-01 06:28:52 -0500194 ``scripts/install-buildtools``).
195
196:append/:prepend in combination with other operators
197~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
198
199The ``append``, ``prepend`` and ``remove`` operators can now only be combined with
200``=`` and ``:=`` operators. To the exception of the ``append`` plus ``+=`` and
201``prepend`` plus ``=+`` combinations, all combinations could be factored up to the
202``append``, ``prepend`` or ``remove`` in the combination. This brought a lot of
203confusion on how the override style syntax operators work and should be used.
204Therefore, those combinations should be replaced by a single ``append``,
205``prepend`` or ``remove`` operator without any additional change.
206For the ``append`` plus ``+=`` (and ``prepend`` plus ``=+``) combinations,
207the content should be prefixed (respectively suffixed) by a space to maintain
208the same behavior. You can learn more about override style syntax operators
209(``append``, ``prepend`` and ``remove``) in the BitBake documentation:
Andrew Geisslerfc113ea2023-03-31 09:59:46 -0500210:ref:`bitbake-user-manual/bitbake-user-manual-metadata:appending and prepending (override style syntax)`
211and :ref:`bitbake-user-manual/bitbake-user-manual-metadata:removal (override style syntax)`.
Patrick Williams03907ee2022-05-01 06:28:52 -0500212
213Miscellaneous changes
214~~~~~~~~~~~~~~~~~~~~~
215
216- ``blacklist.bbclass`` is removed and the functionality moved to the
Andrew Geissler517393d2023-01-13 08:55:19 -0600217 :ref:`ref-classes-base` class with a more descriptive
Patrick Williams03907ee2022-05-01 06:28:52 -0500218 ``varflag`` variable named :term:`SKIP_RECIPE` which will use the `bb.parse.SkipRecipe()`
219 function. The usage remains the same, for example::
220
221 SKIP_RECIPE[my-recipe] = "Reason for skipping recipe"
222
Andrew Geissler517393d2023-01-13 08:55:19 -0600223- :ref:`ref-classes-allarch` packagegroups can no longer depend on packages
Patrick Williams03907ee2022-05-01 06:28:52 -0500224 which use :term:`PKG` renaming such as :ref:`ref-classes-debian`. Such packagegroups
Andrew Geissler517393d2023-01-13 08:55:19 -0600225 recipes should be changed to avoid inheriting :ref:`ref-classes-allarch`.
Patrick Williams03907ee2022-05-01 06:28:52 -0500226
227- The ``lnr`` script has been removed. ``lnr`` implemented the same behaviour as `ln --relative --symbolic`,
228 since at the time of creation `--relative` was only available in coreutils 8.16
229 onwards which was too new for the older supported distros. Current supported host
230 distros have a new enough version of coreutils, so it is no longer needed. If you have
231 any calls to ``lnr`` in your recipes or classes, they should be replaced with
232 `ln --relative --symbolic` or `ln -rs` if you prefer the short version.
233
Andrew Geissler517393d2023-01-13 08:55:19 -0600234- The ``package_qa_handle_error()`` function formerly in the :ref:`ref-classes-insane`
Patrick Williams03907ee2022-05-01 06:28:52 -0500235 class has been moved and renamed - if you have any references in your own custom
236 classes they should be changed to ``oe.qa.handle_error()``.
237
238- When building ``perl``, Berkeley db support is no longer enabled by default, since
239 Berkeley db is largely obsolete. If you wish to reenable it, you can append ``bdb``
240 to :term:`PACKAGECONFIG` in a ``perl`` bbappend or ``PACKAGECONFIG:pn-perl`` at
241 the configuration level.
242
243- For the ``xserver-xorg`` recipe, the ``xshmfence``, ``xmlto`` and ``systemd`` options
244 previously supported in :term:`PACKAGECONFIG` have been removed, as they are no
245 longer supported since the move from building it with autotools to meson in this release.
246
247- For the ``libsdl2`` recipe, various X11 features are now disabled by default (primarily
248 for reproducibility purposes in the native case) with options in :term:`EXTRA_OECMAKE`
249 within the recipe. These can be changed within a bbappend if desired. See the
250 ``libsdl2`` recipe for more details.
251
252- The ``cortexa72-crc`` and ``cortexa72-crc-crypto`` tunes have been removed since
253 the crc extension is now enabled by default for cortexa72. Replace any references to
254 these with ``cortexa72`` and ``cortexa72-crypto`` respectively.
255
256- The Python development shell (previously known as ``devpyshell``) feature has been
257 renamed to ``pydevshell``. To start it you should now run::
258
259 bitbake <target> -c pydevshell
260
261- The ``packagegroups-core-full-cmdline-libs`` packagegroup is no longer produced, as
262 libraries should normally be brought in via dependencies. If you have any references
263 to this then remove them.
264
265- The :term:`TOPDIR` variable and the current working directory are no longer modified
266 when parsing recipes. Any code depending on the previous behaviour will no longer
267 work - change any such code to explicitly use appropriate path variables instead.
268
Andrew Geissler517393d2023-01-13 08:55:19 -0600269- In order to exclude the kernel image from the image rootfs,
270 :term:`RRECOMMENDS`\ ``:${KERNEL_PACKAGE_NAME}-base`` should be set instead of
271 :term:`RDEPENDS`\ ``:${KERNEL_PACKAGE_NAME}-base``.