From 5fc8dd16f2981320371804918a8a8f6ab4563090 Mon Sep 17 00:00:00 2001 From: Richard Purdie Date: Mon, 11 Apr 2022 12:16:03 +0100 Subject: migration-guide: Kirkstone is now 4.0 Update the docs to reflect that kirkstone is 4.0, not 3.5. (From yocto-docs rev: a6f571ad5b087385cad8765ed455c4b4eaeebca6) Signed-off-by: Richard Purdie --- documentation/migration-guides/index.rst | 2 +- documentation/migration-guides/migration-3.5.rst | 170 ----------------------- documentation/migration-guides/migration-4.0.rst | 170 +++++++++++++++++++++++ 3 files changed, 171 insertions(+), 171 deletions(-) delete mode 100644 documentation/migration-guides/migration-3.5.rst create mode 100644 documentation/migration-guides/migration-4.0.rst diff --git a/documentation/migration-guides/index.rst b/documentation/migration-guides/index.rst index d45ba31e7e..20c6ab9d4e 100644 --- a/documentation/migration-guides/index.rst +++ b/documentation/migration-guides/index.rst @@ -12,7 +12,7 @@ to move to one release of the Yocto Project from the previous one. .. toctree:: migration-general - migration-3.5 + migration-4.0 migration-3.4 migration-3.3 migration-3.2 diff --git a/documentation/migration-guides/migration-3.5.rst b/documentation/migration-guides/migration-3.5.rst deleted file mode 100644 index 8a4c568743..0000000000 --- a/documentation/migration-guides/migration-3.5.rst +++ /dev/null @@ -1,170 +0,0 @@ -Release 3.5 (kirkstone) -======================= - -This section provides migration information for moving to the Yocto -Project 3.5 Release (codename "kirkstone") from the prior release. - -Recipe changes --------------- - -- To use more `inclusive language `__ - in the code and documentation, some variables have been renamed or even - deleted. BitBake will stop with an error when renamed or removed variables - still exist in your recipes or configuration. - - Please note that the change applies also to environmental variables, so - make sure you use a fresh environment for your build. - - The following variables have changed their names: - - - ``BB_ENV_WHITELIST`` became :term:`BB_ENV_PASSTHROUGH` - - ``BB_ENV_EXTRAWHITE`` became :term:`BB_ENV_PASSTHROUGH_ADDITIONS` - - ``BB_HASHBASE_WHITELIST`` became :term:`BB_BASEHASH_IGNORE_VARS` - - ``BB_HASHCONFIG_WHITELIST`` became :term:`BB_HASHCONFIG_IGNORE_VARS` - - ``BB_HASHTASK_WHITELIST`` became ``BB_TASKHASH_IGNORE_TASKS`` - - ``BB_SETSCENE_ENFORCE_WHITELIST`` became ``BB_SETSCENE_ENFORCE_IGNORE_TASKS`` - - ``CVE_CHECK_PN_WHITELIST`` became :term:`CVE_CHECK_SKIP_RECIPE` - - ``CVE_CHECK_WHITELIST`` became :term:`CVE_CHECK_IGNORE` - - ``ICECC_USER_CLASS_BL`` became :term:`ICECC_CLASS_DISABLE` - - ``ICECC_SYSTEM_CLASS_BL`` became :term:`ICECC_CLASS_DISABLE` - - ``ICECC_USER_PACKAGE_WL`` became :term:`ICECC_RECIPE_ENABLE` - - ``ICECC_USER_PACKAGE_BL`` became :term:`ICECC_RECIPE_DISABLE` - - ``ICECC_SYSTEM_PACKAGE_BL`` became :term:`ICECC_RECIPE_DISABLE` - - ``LICENSE_FLAGS_WHITELIST`` became :term:`LICENSE_FLAGS_ACCEPTED` - - ``MULTI_PROVIDER_WHITELIST`` became :term:`BB_MULTI_PROVIDER_ALLOWED` - - ``PNBLACKLIST`` became :term:`SKIP_RECIPE` - - ``SDK_LOCAL_CONF_BLACKLIST`` became :term:`ESDK_LOCALCONF_REMOVE` - - ``SDK_LOCAL_CONF_WHITELIST`` became :term:`ESDK_LOCALCONF_ALLOW` - - ``SDK_INHERIT_BLACKLIST`` became :term:`ESDK_CLASS_INHERIT_DISABLE` - - ``SSTATE_DUPWHITELIST`` became ``SSTATE_ALLOW_OVERLAP_FILES`` - - ``SYSROOT_DIRS_BLACKLIST`` became :term:`SYSROOT_DIRS_IGNORE` - - ``UNKNOWN_CONFIGURE_WHITELIST`` became :term:`UNKNOWN_CONFIGURE_OPT_IGNORE` - - In addition, ``BB_STAMP_WHITELIST``, ``BB_STAMP_POLICY``, ``INHERIT_BLACKLIST`` - and ``TUNEABI_WHITELIST`` have been removed. - - Many internal variable names have been also renamed accordingly. - - In addition, in the ``cve-check`` output, the CVE issue status ``Whitelisted`` - has been renamed to ``Ignored``. - - A :oe_git:`convert-variable-renames.py - ` - script is provided to convert your recipes and configuration, - and also warns you about the use of problematic words. The script performs - changes and you need to review them before committing. An example warning - looks like:: - - poky/scripts/lib/devtool/upgrade.py needs further work at line 275 since it contains abort - -- Because of the uncertainty in future default branch names in git repositories, - it is now required to add a branch name to all URLs described - by ``git://`` and ``gitsm://`` :term:`SRC_URI` entries. For example:: - - SRC_URI = "git://git.denx.de/u-boot.git;branch=master" - - A :oe_git:`convert-srcuri ` - script to convert your recipes is available in :term:`OpenEmbedded-Core (OE-Core)` - and in :term:`Poky`. - -- Because of `GitHub dropping support for the git: - protocol `__, - recipes now need to use ``;protocol=https`` at the end of GitHub - URLs. The same script as above can be used to convert the recipes. - -- Network access from tasks is now disabled by default on kernels which support - this feature (on most recent distros such as CentOS 8 and Debian 11 onwards). - This means that tasks accessing the network need to be marked as such with the ``network`` - flag. For example:: - - do_mytask[network] = "1" - - This is allowed by default from ``do_fetch`` but not from any of our other standard - tasks. Recipes shouldn't be accessing the network outside of ``do_fetch`` as it - usually undermines fetcher source mirroring, image and licence manifests, software - auditing and supply chain security. - -- The :term:`TOPDIR` variable and the current working directory are no longer modified - when parsing recipes. Any code depending on that behaviour will no longer work. - -- The ``append``, ``prepend`` and ``remove`` operators can now only be combined with - ``=`` and ``:=`` operators. To the exception of the ``append`` plus ``+=`` and - ``prepend`` plus ``=+`` combinations, all combinations could be factored up to the - ``append``, ``prepend`` or ``remove`` in the combination. This brought a lot of - confusion on how the override style syntax operators work and should be used. - Therefore, those combinations can simply be replaced by a single ``append``, - ``prepend`` or ``remove`` operator without any additional change. - For the ``append`` plus ``+=`` (and ``prepend`` plus ``=+``) combinations, - the content should be prefixed (respectively suffixed) by a space to maintain - the same behavior. You can learn more about override style syntax operators - (``append``, ``prepend`` and ``remove``) in the BitBake documentation: - :ref:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata:appending and prepending (override style syntax)` - and :ref:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata:removal (override style syntax)`. - -- :ref:`allarch ` packagegroups can no longer depend on packages - which use :term:`PKG` renaming such as :ref:`ref-classes-debian`. - -- :term:`LICENSE` definitions now have to use `SPDX identifiers `__. - A :oe_git:`convert-spdx-licenses.py ` - script can be used to update your recipes. - -- :term:`SRC_URI`: a new :ref:`bitbake:bitbake-user-manual/bitbake-user-manual-fetching:crate fetcher (\`\`crate://\`\`)` - is available for Rust packages. - -Class changes -------------- - -- The ``distutils*.bbclasses`` have been moved to ``meta-python``. The classes and - `DISTUTILS*` variables have been removed from the documentation. - -- ``blacklist.bbclass`` is removed and the functionality moved to the - :ref:`base ` class with a more descriptive - ``varflag`` named :term:`SKIP_RECIPE` which will use the `SkipRecipe()` - function. The usage will remain the same:: - - SKIP_RECIPE[my-recipe] = "Reason for skipping recipe" - -- The Python package build process based on `wheels `__. - Here are the new Python packaging classes that should be used: - :ref:`python-flit_core `, - :ref:`setuptools_python-build_meta ` - and :ref:`python_poetry_core `. - -- ``image-prelink.bbclass`` class is removed. - -- New :ref:`overlayfs ` and - :ref:`overlayfs-etc ` classes are available - to make it easier to overlay read-only filesystems (for example) - with `OverlayFS `__. - -Configuration changes ---------------------- - -- The Yocto Project now allows to reuse Shared State from its autobuilder. - If the network connection between our server and your machine is faster - than you would build recipes, you can try to speed up your builds - by using such Share State and Hash Equivalence by setting:: - - BB_SIGNATURE_HANDLER = "OEEquivHash" - BB_HASHSERVE = "auto" - BB_HASHSERVE_UPSTREAM = "typhoon.yocto.io:8687" - SSTATE_MIRRORS ?= "file://.* https://sstate.yoctoproject.org/&YOCTO_DOC_VERSION;/PATH;downloadfilename=PATH" - -Supported host distribution changes ------------------------------------ - -- New support for `AlmaLinux `__ - hosts replacing `CentOS `__. - The following distribution versions were dropped: CentOS 8, Ubuntu 16.04 and Fedora 30, 31 and 32. - -Changes for release notes -------------------------- - -- Share State cache: now using `ZStandard (zstd) `__ - instead of Gzip compression, for better performance. - -- BitBake has an improved ``setscene`` task display. - -- This release fixes the reproducibility issues with ``rust-llvm`` and ``golang``. - Recipes in OpenEmbedded-Core are now fully reproducible. - 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 @@ +Release 4.0 (kirkstone) +======================= + +This section provides migration information for moving to the Yocto +Project 4.0 Release (codename "kirkstone") from the prior release. + +Recipe changes +-------------- + +- To use more `inclusive language `__ + in the code and documentation, some variables have been renamed or even + deleted. BitBake will stop with an error when renamed or removed variables + still exist in your recipes or configuration. + + Please note that the change applies also to environmental variables, so + make sure you use a fresh environment for your build. + + The following variables have changed their names: + + - ``BB_ENV_WHITELIST`` became :term:`BB_ENV_PASSTHROUGH` + - ``BB_ENV_EXTRAWHITE`` became :term:`BB_ENV_PASSTHROUGH_ADDITIONS` + - ``BB_HASHBASE_WHITELIST`` became :term:`BB_BASEHASH_IGNORE_VARS` + - ``BB_HASHCONFIG_WHITELIST`` became :term:`BB_HASHCONFIG_IGNORE_VARS` + - ``BB_HASHTASK_WHITELIST`` became ``BB_TASKHASH_IGNORE_TASKS`` + - ``BB_SETSCENE_ENFORCE_WHITELIST`` became ``BB_SETSCENE_ENFORCE_IGNORE_TASKS`` + - ``CVE_CHECK_PN_WHITELIST`` became :term:`CVE_CHECK_SKIP_RECIPE` + - ``CVE_CHECK_WHITELIST`` became :term:`CVE_CHECK_IGNORE` + - ``ICECC_USER_CLASS_BL`` became :term:`ICECC_CLASS_DISABLE` + - ``ICECC_SYSTEM_CLASS_BL`` became :term:`ICECC_CLASS_DISABLE` + - ``ICECC_USER_PACKAGE_WL`` became :term:`ICECC_RECIPE_ENABLE` + - ``ICECC_USER_PACKAGE_BL`` became :term:`ICECC_RECIPE_DISABLE` + - ``ICECC_SYSTEM_PACKAGE_BL`` became :term:`ICECC_RECIPE_DISABLE` + - ``LICENSE_FLAGS_WHITELIST`` became :term:`LICENSE_FLAGS_ACCEPTED` + - ``MULTI_PROVIDER_WHITELIST`` became :term:`BB_MULTI_PROVIDER_ALLOWED` + - ``PNBLACKLIST`` became :term:`SKIP_RECIPE` + - ``SDK_LOCAL_CONF_BLACKLIST`` became :term:`ESDK_LOCALCONF_REMOVE` + - ``SDK_LOCAL_CONF_WHITELIST`` became :term:`ESDK_LOCALCONF_ALLOW` + - ``SDK_INHERIT_BLACKLIST`` became :term:`ESDK_CLASS_INHERIT_DISABLE` + - ``SSTATE_DUPWHITELIST`` became ``SSTATE_ALLOW_OVERLAP_FILES`` + - ``SYSROOT_DIRS_BLACKLIST`` became :term:`SYSROOT_DIRS_IGNORE` + - ``UNKNOWN_CONFIGURE_WHITELIST`` became :term:`UNKNOWN_CONFIGURE_OPT_IGNORE` + + In addition, ``BB_STAMP_WHITELIST``, ``BB_STAMP_POLICY``, ``INHERIT_BLACKLIST`` + and ``TUNEABI_WHITELIST`` have been removed. + + Many internal variable names have been also renamed accordingly. + + In addition, in the ``cve-check`` output, the CVE issue status ``Whitelisted`` + has been renamed to ``Ignored``. + + A :oe_git:`convert-variable-renames.py + ` + script is provided to convert your recipes and configuration, + and also warns you about the use of problematic words. The script performs + changes and you need to review them before committing. An example warning + looks like:: + + poky/scripts/lib/devtool/upgrade.py needs further work at line 275 since it contains abort + +- Because of the uncertainty in future default branch names in git repositories, + it is now required to add a branch name to all URLs described + by ``git://`` and ``gitsm://`` :term:`SRC_URI` entries. For example:: + + SRC_URI = "git://git.denx.de/u-boot.git;branch=master" + + A :oe_git:`convert-srcuri ` + script to convert your recipes is available in :term:`OpenEmbedded-Core (OE-Core)` + and in :term:`Poky`. + +- Because of `GitHub dropping support for the git: + protocol `__, + recipes now need to use ``;protocol=https`` at the end of GitHub + URLs. The same script as above can be used to convert the recipes. + +- Network access from tasks is now disabled by default on kernels which support + this feature (on most recent distros such as CentOS 8 and Debian 11 onwards). + This means that tasks accessing the network need to be marked as such with the ``network`` + flag. For example:: + + do_mytask[network] = "1" + + This is allowed by default from ``do_fetch`` but not from any of our other standard + tasks. Recipes shouldn't be accessing the network outside of ``do_fetch`` as it + usually undermines fetcher source mirroring, image and licence manifests, software + auditing and supply chain security. + +- The :term:`TOPDIR` variable and the current working directory are no longer modified + when parsing recipes. Any code depending on that behaviour will no longer work. + +- The ``append``, ``prepend`` and ``remove`` operators can now only be combined with + ``=`` and ``:=`` operators. To the exception of the ``append`` plus ``+=`` and + ``prepend`` plus ``=+`` combinations, all combinations could be factored up to the + ``append``, ``prepend`` or ``remove`` in the combination. This brought a lot of + confusion on how the override style syntax operators work and should be used. + Therefore, those combinations can simply be replaced by a single ``append``, + ``prepend`` or ``remove`` operator without any additional change. + For the ``append`` plus ``+=`` (and ``prepend`` plus ``=+``) combinations, + the content should be prefixed (respectively suffixed) by a space to maintain + the same behavior. You can learn more about override style syntax operators + (``append``, ``prepend`` and ``remove``) in the BitBake documentation: + :ref:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata:appending and prepending (override style syntax)` + and :ref:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata:removal (override style syntax)`. + +- :ref:`allarch ` packagegroups can no longer depend on packages + which use :term:`PKG` renaming such as :ref:`ref-classes-debian`. + +- :term:`LICENSE` definitions now have to use `SPDX identifiers `__. + A :oe_git:`convert-spdx-licenses.py ` + script can be used to update your recipes. + +- :term:`SRC_URI`: a new :ref:`bitbake:bitbake-user-manual/bitbake-user-manual-fetching:crate fetcher (\`\`crate://\`\`)` + is available for Rust packages. + +Class changes +------------- + +- The ``distutils*.bbclasses`` have been moved to ``meta-python``. The classes and + `DISTUTILS*` variables have been removed from the documentation. + +- ``blacklist.bbclass`` is removed and the functionality moved to the + :ref:`base ` class with a more descriptive + ``varflag`` named :term:`SKIP_RECIPE` which will use the `SkipRecipe()` + function. The usage will remain the same:: + + SKIP_RECIPE[my-recipe] = "Reason for skipping recipe" + +- The Python package build process based on `wheels `__. + Here are the new Python packaging classes that should be used: + :ref:`python-flit_core `, + :ref:`setuptools_python-build_meta ` + and :ref:`python_poetry_core `. + +- ``image-prelink.bbclass`` class is removed. + +- New :ref:`overlayfs ` and + :ref:`overlayfs-etc ` classes are available + to make it easier to overlay read-only filesystems (for example) + with `OverlayFS `__. + +Configuration changes +--------------------- + +- The Yocto Project now allows to reuse Shared State from its autobuilder. + If the network connection between our server and your machine is faster + than you would build recipes, you can try to speed up your builds + by using such Share State and Hash Equivalence by setting:: + + BB_SIGNATURE_HANDLER = "OEEquivHash" + BB_HASHSERVE = "auto" + BB_HASHSERVE_UPSTREAM = "typhoon.yocto.io:8687" + SSTATE_MIRRORS ?= "file://.* https://sstate.yoctoproject.org/&YOCTO_DOC_VERSION;/PATH;downloadfilename=PATH" + +Supported host distribution changes +----------------------------------- + +- New support for `AlmaLinux `__ + hosts replacing `CentOS `__. + The following distribution versions were dropped: CentOS 8, Ubuntu 16.04 and Fedora 30, 31 and 32. + +Changes for release notes +------------------------- + +- Share State cache: now using `ZStandard (zstd) `__ + instead of Gzip compression, for better performance. + +- BitBake has an improved ``setscene`` task display. + +- This release fixes the reproducibility issues with ``rust-llvm`` and ``golang``. + Recipes in OpenEmbedded-Core are now fully reproducible. + -- cgit v1.2.3-54-g00ecf