diff options
Diffstat (limited to 'documentation/migration-guides/migration-4.0.rst')
-rw-r--r-- | documentation/migration-guides/migration-4.0.rst | 170 |
1 files changed, 170 insertions, 0 deletions
diff --git a/documentation/migration-guides/migration-4.0.rst b/documentation/migration-guides/migration-4.0.rst new file mode 100644 index 0000000000..202999ece8 --- /dev/null +++ b/documentation/migration-guides/migration-4.0.rst | |||
@@ -0,0 +1,170 @@ | |||
1 | Release 4.0 (kirkstone) | ||
2 | ======================= | ||
3 | |||
4 | This section provides migration information for moving to the Yocto | ||
5 | Project 4.0 Release (codename "kirkstone") from the prior release. | ||
6 | |||
7 | Recipe changes | ||
8 | -------------- | ||
9 | |||
10 | - To use more `inclusive language <https://inclusivenaming.org/>`__ | ||
11 | in the code and documentation, some variables have been renamed or even | ||
12 | deleted. BitBake will stop with an error when renamed or removed variables | ||
13 | still exist in your recipes or configuration. | ||
14 | |||
15 | Please note that the change applies also to environmental variables, so | ||
16 | make sure you use a fresh environment for your build. | ||
17 | |||
18 | The following variables have changed their names: | ||
19 | |||
20 | - ``BB_ENV_WHITELIST`` became :term:`BB_ENV_PASSTHROUGH` | ||
21 | - ``BB_ENV_EXTRAWHITE`` became :term:`BB_ENV_PASSTHROUGH_ADDITIONS` | ||
22 | - ``BB_HASHBASE_WHITELIST`` became :term:`BB_BASEHASH_IGNORE_VARS` | ||
23 | - ``BB_HASHCONFIG_WHITELIST`` became :term:`BB_HASHCONFIG_IGNORE_VARS` | ||
24 | - ``BB_HASHTASK_WHITELIST`` became ``BB_TASKHASH_IGNORE_TASKS`` | ||
25 | - ``BB_SETSCENE_ENFORCE_WHITELIST`` became ``BB_SETSCENE_ENFORCE_IGNORE_TASKS`` | ||
26 | - ``CVE_CHECK_PN_WHITELIST`` became :term:`CVE_CHECK_SKIP_RECIPE` | ||
27 | - ``CVE_CHECK_WHITELIST`` became :term:`CVE_CHECK_IGNORE` | ||
28 | - ``ICECC_USER_CLASS_BL`` became :term:`ICECC_CLASS_DISABLE` | ||
29 | - ``ICECC_SYSTEM_CLASS_BL`` became :term:`ICECC_CLASS_DISABLE` | ||
30 | - ``ICECC_USER_PACKAGE_WL`` became :term:`ICECC_RECIPE_ENABLE` | ||
31 | - ``ICECC_USER_PACKAGE_BL`` became :term:`ICECC_RECIPE_DISABLE` | ||
32 | - ``ICECC_SYSTEM_PACKAGE_BL`` became :term:`ICECC_RECIPE_DISABLE` | ||
33 | - ``LICENSE_FLAGS_WHITELIST`` became :term:`LICENSE_FLAGS_ACCEPTED` | ||
34 | - ``MULTI_PROVIDER_WHITELIST`` became :term:`BB_MULTI_PROVIDER_ALLOWED` | ||
35 | - ``PNBLACKLIST`` became :term:`SKIP_RECIPE` | ||
36 | - ``SDK_LOCAL_CONF_BLACKLIST`` became :term:`ESDK_LOCALCONF_REMOVE` | ||
37 | - ``SDK_LOCAL_CONF_WHITELIST`` became :term:`ESDK_LOCALCONF_ALLOW` | ||
38 | - ``SDK_INHERIT_BLACKLIST`` became :term:`ESDK_CLASS_INHERIT_DISABLE` | ||
39 | - ``SSTATE_DUPWHITELIST`` became ``SSTATE_ALLOW_OVERLAP_FILES`` | ||
40 | - ``SYSROOT_DIRS_BLACKLIST`` became :term:`SYSROOT_DIRS_IGNORE` | ||
41 | - ``UNKNOWN_CONFIGURE_WHITELIST`` became :term:`UNKNOWN_CONFIGURE_OPT_IGNORE` | ||
42 | |||
43 | In addition, ``BB_STAMP_WHITELIST``, ``BB_STAMP_POLICY``, ``INHERIT_BLACKLIST`` | ||
44 | and ``TUNEABI_WHITELIST`` have been removed. | ||
45 | |||
46 | Many internal variable names have been also renamed accordingly. | ||
47 | |||
48 | In addition, in the ``cve-check`` output, the CVE issue status ``Whitelisted`` | ||
49 | has been renamed to ``Ignored``. | ||
50 | |||
51 | A :oe_git:`convert-variable-renames.py | ||
52 | </openembedded-core/tree/scripts/contrib/convert-variable-renames.py>` | ||
53 | script is provided to convert your recipes and configuration, | ||
54 | and also warns you about the use of problematic words. The script performs | ||
55 | changes and you need to review them before committing. An example warning | ||
56 | looks like:: | ||
57 | |||
58 | poky/scripts/lib/devtool/upgrade.py needs further work at line 275 since it contains abort | ||
59 | |||
60 | - Because of the uncertainty in future default branch names in git repositories, | ||
61 | it is now required to add a branch name to all URLs described | ||
62 | by ``git://`` and ``gitsm://`` :term:`SRC_URI` entries. For example:: | ||
63 | |||
64 | SRC_URI = "git://git.denx.de/u-boot.git;branch=master" | ||
65 | |||
66 | A :oe_git:`convert-srcuri </openembedded-core/tree/scripts/contrib/convert-srcuri.py>` | ||
67 | script to convert your recipes is available in :term:`OpenEmbedded-Core (OE-Core)` | ||
68 | and in :term:`Poky`. | ||
69 | |||
70 | - Because of `GitHub dropping support for the git: | ||
71 | protocol <https://github.blog/2021-09-01-improving-git-protocol-security-github/>`__, | ||
72 | recipes now need to use ``;protocol=https`` at the end of GitHub | ||
73 | URLs. The same script as above can be used to convert the recipes. | ||
74 | |||
75 | - Network access from tasks is now disabled by default on kernels which support | ||
76 | this feature (on most recent distros such as CentOS 8 and Debian 11 onwards). | ||
77 | This means that tasks accessing the network need to be marked as such with the ``network`` | ||
78 | flag. For example:: | ||
79 | |||
80 | do_mytask[network] = "1" | ||
81 | |||
82 | This is allowed by default from ``do_fetch`` but not from any of our other standard | ||
83 | tasks. Recipes shouldn't be accessing the network outside of ``do_fetch`` as it | ||
84 | usually undermines fetcher source mirroring, image and licence manifests, software | ||
85 | auditing and supply chain security. | ||
86 | |||
87 | - The :term:`TOPDIR` variable and the current working directory are no longer modified | ||
88 | when parsing recipes. Any code depending on that behaviour will no longer work. | ||
89 | |||
90 | - The ``append``, ``prepend`` and ``remove`` operators can now only be combined with | ||
91 | ``=`` and ``:=`` operators. To the exception of the ``append`` plus ``+=`` and | ||
92 | ``prepend`` plus ``=+`` combinations, all combinations could be factored up to the | ||
93 | ``append``, ``prepend`` or ``remove`` in the combination. This brought a lot of | ||
94 | confusion on how the override style syntax operators work and should be used. | ||
95 | Therefore, those combinations can simply be replaced by a single ``append``, | ||
96 | ``prepend`` or ``remove`` operator without any additional change. | ||
97 | For the ``append`` plus ``+=`` (and ``prepend`` plus ``=+``) combinations, | ||
98 | the content should be prefixed (respectively suffixed) by a space to maintain | ||
99 | the same behavior. You can learn more about override style syntax operators | ||
100 | (``append``, ``prepend`` and ``remove``) in the BitBake documentation: | ||
101 | :ref:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata:appending and prepending (override style syntax)` | ||
102 | and :ref:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata:removal (override style syntax)`. | ||
103 | |||
104 | - :ref:`allarch <ref-classes-allarch>` packagegroups can no longer depend on packages | ||
105 | which use :term:`PKG` renaming such as :ref:`ref-classes-debian`. | ||
106 | |||
107 | - :term:`LICENSE` definitions now have to use `SPDX identifiers <https://spdx.org/licenses/>`__. | ||
108 | A :oe_git:`convert-spdx-licenses.py </openembedded-core/tree/scripts/contrib/convert-spdx-licenses.py>` | ||
109 | script can be used to update your recipes. | ||
110 | |||
111 | - :term:`SRC_URI`: a new :ref:`bitbake:bitbake-user-manual/bitbake-user-manual-fetching:crate fetcher (\`\`crate://\`\`)` | ||
112 | is available for Rust packages. | ||
113 | |||
114 | Class changes | ||
115 | ------------- | ||
116 | |||
117 | - The ``distutils*.bbclasses`` have been moved to ``meta-python``. The classes and | ||
118 | `DISTUTILS*` variables have been removed from the documentation. | ||
119 | |||
120 | - ``blacklist.bbclass`` is removed and the functionality moved to the | ||
121 | :ref:`base <ref-classes-base>` class with a more descriptive | ||
122 | ``varflag`` named :term:`SKIP_RECIPE` which will use the `SkipRecipe()` | ||
123 | function. The usage will remain the same:: | ||
124 | |||
125 | SKIP_RECIPE[my-recipe] = "Reason for skipping recipe" | ||
126 | |||
127 | - The Python package build process based on `wheels <https://pythonwheels.com/>`__. | ||
128 | Here are the new Python packaging classes that should be used: | ||
129 | :ref:`python-flit_core <ref-classes-python_flit_core>`, | ||
130 | :ref:`setuptools_python-build_meta <ref-classes-python_setuptools_build_meta>` | ||
131 | and :ref:`python_poetry_core <ref-classes-python_poetry_core>`. | ||
132 | |||
133 | - ``image-prelink.bbclass`` class is removed. | ||
134 | |||
135 | - New :ref:`overlayfs <ref-classes-overlayfs>` and | ||
136 | :ref:`overlayfs-etc <ref-classes-overlayfs-etc>` classes are available | ||
137 | to make it easier to overlay read-only filesystems (for example) | ||
138 | with `OverlayFS <https://en.wikipedia.org/wiki/OverlayFS>`__. | ||
139 | |||
140 | Configuration changes | ||
141 | --------------------- | ||
142 | |||
143 | - The Yocto Project now allows to reuse Shared State from its autobuilder. | ||
144 | If the network connection between our server and your machine is faster | ||
145 | than you would build recipes, you can try to speed up your builds | ||
146 | by using such Share State and Hash Equivalence by setting:: | ||
147 | |||
148 | BB_SIGNATURE_HANDLER = "OEEquivHash" | ||
149 | BB_HASHSERVE = "auto" | ||
150 | BB_HASHSERVE_UPSTREAM = "typhoon.yocto.io:8687" | ||
151 | SSTATE_MIRRORS ?= "file://.* https://sstate.yoctoproject.org/&YOCTO_DOC_VERSION;/PATH;downloadfilename=PATH" | ||
152 | |||
153 | Supported host distribution changes | ||
154 | ----------------------------------- | ||
155 | |||
156 | - New support for `AlmaLinux <https://en.wikipedia.org/wiki/AlmaLinux>`__ | ||
157 | hosts replacing `CentOS <https://en.wikipedia.org/wiki/CentOS>`__. | ||
158 | The following distribution versions were dropped: CentOS 8, Ubuntu 16.04 and Fedora 30, 31 and 32. | ||
159 | |||
160 | Changes for release notes | ||
161 | ------------------------- | ||
162 | |||
163 | - Share State cache: now using `ZStandard (zstd) <https://en.wikipedia.org/wiki/Zstd>`__ | ||
164 | instead of Gzip compression, for better performance. | ||
165 | |||
166 | - BitBake has an improved ``setscene`` task display. | ||
167 | |||
168 | - This release fixes the reproducibility issues with ``rust-llvm`` and ``golang``. | ||
169 | Recipes in OpenEmbedded-Core are now fully reproducible. | ||
170 | |||