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