Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame^] | 1 | .. SPDX-License-Identifier: CC-BY-SA-2.0-UK |
| 2 | |
Patrick Williams | 03907ee | 2022-05-01 06:28:52 -0500 | [diff] [blame] | 3 | Release 4.0 (kirkstone) |
| 4 | ======================= |
| 5 | |
| 6 | Migration notes for 4.0 (kirkstone) |
| 7 | ----------------------------------- |
| 8 | |
| 9 | This section provides migration information for moving to the Yocto |
| 10 | Project 4.0 Release (codename "kirkstone") from the prior release. |
| 11 | |
| 12 | .. _migration-4.0-inclusive-language: |
| 13 | |
| 14 | Inclusive language improvements |
| 15 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 16 | |
| 17 | To use more `inclusive language <https://inclusivenaming.org/>`__ |
| 18 | in the code and documentation, some variables have been renamed, and |
| 19 | some have been deleted where they are no longer needed. In many cases the |
| 20 | new names are also easier to understand. BitBake will stop with an error when |
| 21 | renamed or removed variables still exist in your recipes or configuration. |
| 22 | |
| 23 | Please note that the change applies also to environmental variables, so |
| 24 | make sure you use a fresh environment for your build. |
| 25 | |
| 26 | The 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 Geissler | 615f2f1 | 2022-07-15 14:00:58 -0500 | [diff] [blame] | 50 | - ``WHITELIST_<license>`` became :term:`INCOMPATIBLE_LICENSE_EXCEPTIONS` |
Patrick Williams | 03907ee | 2022-05-01 06:28:52 -0500 | [diff] [blame] | 51 | |
| 52 | In addition, ``BB_STAMP_WHITELIST``, ``BB_STAMP_POLICY``, ``INHERIT_BLACKLIST``, |
| 53 | ``TUNEABI``, ``TUNEABI_WHITELIST``, and ``TUNEABI_OVERRIDE`` have been removed. |
| 54 | |
| 55 | Many internal variable names have been also renamed accordingly. |
| 56 | |
| 57 | In addition, in the ``cve-check`` output, the CVE issue status ``Whitelisted`` |
| 58 | has been renamed to ``Ignored``. |
| 59 | |
| 60 | The :term:`BB_DISKMON_DIRS` variable value now uses the term ``HALT`` |
| 61 | instead of ``ABORT``. |
| 62 | |
| 63 | A :oe_git:`convert-variable-renames.py |
| 64 | </openembedded-core/tree/scripts/contrib/convert-variable-renames.py>` |
| 65 | script is provided to convert your recipes and configuration, |
| 66 | and also warns you about the use of problematic words. The script performs |
| 67 | changes and you need to review them before committing. An example warning |
| 68 | looks like:: |
| 69 | |
| 70 | poky/scripts/lib/devtool/upgrade.py needs further work at line 275 since it contains abort |
| 71 | |
| 72 | Fetching 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 Williams | 2194f50 | 2022-10-16 14:26:09 -0500 | [diff] [blame] | 98 | 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 Williams | 03907ee | 2022-05-01 06:28:52 -0500 | [diff] [blame] | 100 | usually undermines fetcher source mirroring, image and licence manifests, software |
| 101 | auditing and supply chain security. |
| 102 | |
| 103 | License 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 Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame^] | 122 | function has been removed from the :ref:`ref-classes-license` class as |
Patrick Williams | 03907ee | 2022-05-01 06:28:52 -0500 | [diff] [blame] | 123 | it is no longer needed. |
| 124 | |
| 125 | Removed recipes |
| 126 | ~~~~~~~~~~~~~~~ |
| 127 | |
| 128 | The 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 | |
| 137 | Python 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/>`__. |
| 145 | Here are the new Python packaging classes that should be used: |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame^] | 146 | :ref:`ref-classes-python_flit_core`, :ref:`ref-classes-python_setuptools_build_meta` |
| 147 | and :ref:`ref-classes-python_poetry_core`. |
Patrick Williams | 03907ee | 2022-05-01 06:28:52 -0500 | [diff] [blame] | 148 | |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame^] | 149 | - The :ref:`ref-classes-setuptools3` class :ref:`ref-tasks-install` task now |
Patrick Williams | 03907ee | 2022-05-01 06:28:52 -0500 | [diff] [blame] | 150 | 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 Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame^] | 153 | entry points, then :ref:`ref-classes-setuptools3_legacy` should |
Patrick Williams | 03907ee | 2022-05-01 06:28:52 -0500 | [diff] [blame] | 154 | be used instead. |
| 155 | |
| 156 | Prelink removed |
| 157 | ~~~~~~~~~~~~~~~ |
| 158 | |
| 159 | Prelink has been dropped by ``glibc`` upstream in 2.36. It already caused issues with |
| 160 | binary corruption, has a number of open bugs and is of questionable benefit |
| 161 | without disabling load address randomization and PIE executables. |
| 162 | |
| 163 | We disabled prelinking by default in the honister (3.4) release, but left it able |
| 164 | to be enabled if desired. However, without glibc support it cannot be maintained |
| 165 | any further, so all of the prelinking functionality has been removed in this release. |
| 166 | If 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 |
| 168 | reference(s). |
| 169 | |
| 170 | Reproducible as standard |
| 171 | ~~~~~~~~~~~~~~~~~~~~~~~~ |
| 172 | |
| 173 | Reproducibility is now considered as standard functionality, thus the |
| 174 | ``reproducible`` class has been removed and its previous contents merged into the |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame^] | 175 | :ref:`ref-classes-base` class. If you have references in your configuration to |
Patrick Williams | 03907ee | 2022-05-01 06:28:52 -0500 | [diff] [blame] | 176 | ``reproducible`` in :term:`INHERIT`, :term:`USER_CLASSES` etc. then they should be |
| 177 | removed. |
| 178 | |
| 179 | Additionally, the ``BUILD_REPRODUCIBLE_BINARIES`` variable is no longer used. |
| 180 | Specifically for the kernel, if you wish to enable build timestamping functionality |
| 181 | that is normally disabled for reproducibility reasons, you can do so by setting |
| 182 | a new :term:`KERNEL_DEBUG_TIMESTAMPS` variable to "1". |
| 183 | |
| 184 | Supported host distribution changes |
| 185 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 186 | |
Patrick Williams | 7784c42 | 2022-11-17 07:29:11 -0600 | [diff] [blame] | 187 | - Support for :wikipedia:`AlmaLinux <AlmaLinux>` |
| 188 | hosts replacing :wikipedia:`CentOS <CentOS>`. |
Patrick Williams | 03907ee | 2022-05-01 06:28:52 -0500 | [diff] [blame] | 189 | 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 Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame^] | 193 | :term:`buildtools-extended` tarball (easily installable using |
Patrick Williams | 03907ee | 2022-05-01 06:28:52 -0500 | [diff] [blame] | 194 | ``scripts/install-buildtools``). |
| 195 | |
| 196 | :append/:prepend in combination with other operators |
| 197 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 198 | |
| 199 | The ``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 |
| 203 | confusion on how the override style syntax operators work and should be used. |
| 204 | Therefore, those combinations should be replaced by a single ``append``, |
| 205 | ``prepend`` or ``remove`` operator without any additional change. |
| 206 | For the ``append`` plus ``+=`` (and ``prepend`` plus ``=+``) combinations, |
| 207 | the content should be prefixed (respectively suffixed) by a space to maintain |
| 208 | the same behavior. You can learn more about override style syntax operators |
| 209 | (``append``, ``prepend`` and ``remove``) in the BitBake documentation: |
| 210 | :ref:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata:appending and prepending (override style syntax)` |
| 211 | and :ref:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata:removal (override style syntax)`. |
| 212 | |
| 213 | Miscellaneous changes |
| 214 | ~~~~~~~~~~~~~~~~~~~~~ |
| 215 | |
| 216 | - ``blacklist.bbclass`` is removed and the functionality moved to the |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame^] | 217 | :ref:`ref-classes-base` class with a more descriptive |
Patrick Williams | 03907ee | 2022-05-01 06:28:52 -0500 | [diff] [blame] | 218 | ``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 Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame^] | 223 | - :ref:`ref-classes-allarch` packagegroups can no longer depend on packages |
Patrick Williams | 03907ee | 2022-05-01 06:28:52 -0500 | [diff] [blame] | 224 | which use :term:`PKG` renaming such as :ref:`ref-classes-debian`. Such packagegroups |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame^] | 225 | recipes should be changed to avoid inheriting :ref:`ref-classes-allarch`. |
Patrick Williams | 03907ee | 2022-05-01 06:28:52 -0500 | [diff] [blame] | 226 | |
| 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 Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame^] | 234 | - The ``package_qa_handle_error()`` function formerly in the :ref:`ref-classes-insane` |
Patrick Williams | 03907ee | 2022-05-01 06:28:52 -0500 | [diff] [blame] | 235 | 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 Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame^] | 269 | - 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``. |