版本 4.0 (kirkstone)

4.0 (kirkstone) 迁移说明

本节介绍如何从上一版本迁移到 Yocto Project 4.0 版本（代号“kirkstone”）。

包容性语言改进

为在代码和文档中使用更具包容性的语言，部分变量已重命名，不再需要的变量则已删除。许多新名称也更容易理解。如果配方或配置中仍存在已重命名或移除的变量，BitBake 会报错并停止。

请注意，此变更也适用于环境变量，因此务必使用全新的环境进行构建。

以下变量已重命名：

BB_ENV_WHITELIST 改为 BB_ENV_PASSTHROUGH
BB_ENV_EXTRAWHITE 改为 BB_ENV_PASSTHROUGH_ADDITIONS
BB_HASHBASE_WHITELIST 改为 BB_BASEHASH_IGNORE_VARS
BB_HASHCONFIG_WHITELIST 改为 BB_HASHCONFIG_IGNORE_VARS
BB_HASHTASK_WHITELIST 改为 BB_TASKHASH_IGNORE_TASKS
BB_SETSCENE_ENFORCE_WHITELIST 改为 BB_SETSCENE_ENFORCE_IGNORE_TASKS
CVE_CHECK_PN_WHITELIST 改为 CVE_CHECK_SKIP_RECIPE
CVE_CHECK_WHITELIST 改为 CVE_CHECK_IGNORE
ICECC_USER_CLASS_BL 改为 ICECC_CLASS_DISABLE
ICECC_SYSTEM_CLASS_BL 改为 ICECC_CLASS_DISABLE
ICECC_USER_PACKAGE_WL 改为 ICECC_RECIPE_ENABLE
ICECC_USER_PACKAGE_BL 改为 ICECC_RECIPE_DISABLE
ICECC_SYSTEM_PACKAGE_BL 改为 ICECC_RECIPE_DISABLE
LICENSE_FLAGS_WHITELIST 改为 LICENSE_FLAGS_ACCEPTED
MULTI_PROVIDER_WHITELIST 改为 BB_MULTI_PROVIDER_ALLOWED
PNBLACKLIST 改为 SKIP_RECIPE
SDK_LOCAL_CONF_BLACKLIST 改为 ESDK_LOCALCONF_REMOVE
SDK_LOCAL_CONF_WHITELIST 改为 ESDK_LOCALCONF_ALLOW
SDK_INHERIT_BLACKLIST 改为 ESDK_CLASS_INHERIT_DISABLE
SSTATE_DUPWHITELIST 改为 SSTATE_ALLOW_OVERLAP_FILES
SYSROOT_DIRS_BLACKLIST 改为 SYSROOT_DIRS_IGNORE
UNKNOWN_CONFIGURE_WHITELIST 改为 UNKNOWN_CONFIGURE_OPT_IGNORE
WHITELIST_<license> 改为 INCOMPATIBLE_LICENSE_EXCEPTIONS

此外，BB_STAMP_WHITELIST、BB_STAMP_POLICY、INHERIT_BLACKLIST、 TUNEABI、TUNEABI_WHITELIST 和 TUNEABI_OVERRIDE 已移除。

许多内部变量也作了相应重命名。

cve-check 输出中的 CVE 问题状态 Whitelisted 改名为 Ignored。

BB_DISKMON_DIRS 的变量值现在使用 HALT 代替 ABORT。

提供了 convert-variable-renames.py 脚本来转换配方和配置，同时也会警告有问题的用词。脚本会直接修改文件，提交前需要审查这些修改。警告示例如下:

poky/scripts/lib/devtool/upgrade.py needs further work at line 275 since it contains abort

获取变更

由于 Git 仓库未来的默认分支名称不确定，现在所有 git:// 和 gitsm:// SRC_URI 条目描述的 URL 都必须添加分支名。例如:
```
SRC_URI = "git://git.denx.de/u-boot.git;branch=master"
```
OpenEmbedded-Core (OE-Core) 和 Poky 中提供了 convert-srcuri 脚本来转换配方。
由于 GitHub 停止支持 git: 协议，配方现在需要在 GitHub URL 末尾使用 ;protocol=https。同样可使用上述 convert-srcuri 脚本转换配方。
在支持该功能的内核上（多数较新发行版，例如 CentOS 8 和 Debian 11 及以后版本），现在默认禁止任务访问网络。需要联网的任务必须通过 network 标志声明，例如:
```
do_mytask[network] = "1"
```
do_fetch 默认允许联网，但其他标准任务均不允许。配方不应在 do_fetch 之外访问网络，因为这通常会破坏获取器源码镜像、镜像与许可证清单、软件审计及供应链安全。

许可证变更

common-licenses 目录中移除了含义模糊的 "BSD" 许可证。获取或构建 BSD 许可代码的配方，应在 LICENSE 中指定正确的 BSD 许可证版本。
LICENSE 现在应使用 SPDX 标识符，否则默认会显示警告。可以使用 convert-spdx-licenses.py 脚本更新配方。
INCOMPATIBLE_LICENSE 现在应使用 SPDX 标识符。此外，通配符仅限于明确支持的值，详情见 INCOMPATIBLE_LICENSE 文档。
移除了 AVAILABLE_LICENSES 变量。该变量影响性能，且高度依赖配置中添加的层，可能给用户带来签名问题。license 类中的 available_licenses() 函数也已移除，因为不再需要。

已移除的配方

本版本移除了以下配方：

dbus-test：合并到主 dbus 配方
libid3tag：移至 meta-oe，OE-Core 中已无使用者
libportal：移至 meta-gnome，OE-Core 中已无使用者
linux-yocto：移除 5.14 版本配方（仍提供 5.15 和 5.10）
python3-nose：上游自 2016 年后未再变更，且 OE-Core 中已无使用者
rustfmt：作为独立配方的用途有限

Python 变更

Python 3.10 上游已弃用 distutils，因此 distutils* 类已移至 meta-python。继承这些类的配方应更新为继承相应的 setuptools* 类。
Python 软件包构建过程现在基于 wheel。应使用新的 Python 打包类 python_flit_core、 python_setuptools_build_meta 和 python_poetry_core。
setuptools3 类的 do_install 任务现在安装 wheel 二进制归档。当前 setuptools 已弃用旧的 setup.py install 方法。如果 setup.py 不能配合 wheel 使用，例如它会在 Python 模块或标准入口点之外创建文件，则应改用 setuptools3_legacy。

移除预链接

glibc 上游在 2.36 中移除了 Prelink。它已造成二进制文件损坏问题，仍有多个未解决错误，而且若不禁用加载地址随机化和 PIE 可执行文件，其收益存疑。

honister（3.4）已默认禁用预链接，但仍允许按需启用。然而，没有 glibc 支持就无法继续维护，因此本版本移除了全部预链接功能。如果在配置的 INHERIT、 IMAGE_CLASSES、USER_CLASSES 等位置启用了 image-prelink 类，需要移除相应引用。

可复现性成为标准功能

可复现性现在被视为标准功能，因此移除了 reproducible 类，并将其原有内容合并到 base 类。如果配置中的 INHERIT、USER_CLASSES 等位置引用了 reproducible，应移除这些引用。

此外，不再使用 BUILD_REPRODUCIBLE_BINARIES。对于内核，如果希望启用通常因可复现性而禁用的构建时间戳功能，可以将新的 KERNEL_DEBUG_TIMESTAMPS 变量设置为 "1"。

支持的主机发行版变更

支持 AlmaLinux 主机，取代 CentOS。不再支持 CentOS 8、Ubuntu 16.04 和 Fedora 30、31、32。
构建主机最低要求 gcc 7.5。对于无法提供该版本的旧主机发行版，可以使用 buildtools-extended 压缩包（可通过 scripts/install-buildtools 轻松安装）。

:append/:prepend 与其他运算符组合

append、prepend 和 remove 现在只能与 = 和 := 运算符组合。除 append 加 += 和 prepend 加 =+ 外，其他所有组合都可简化为其中的 append、prepend 或 remove。这些组合曾使覆盖样式语法运算符的工作方式和用法变得混乱。因此，应将这些组合直接替换为单个 append、prepend 或 remove，无需其他修改。对于 append 加 += 的组合，需要在内容前加一个空格；对于 prepend 加 =+ 的组合，需要在内容后加一个空格，以保持相同行为。覆盖样式语法运算符（append、prepend 和 remove）的更多信息见 BitBake 文档： Appending and Prepending (Override Style Syntax) 和 Removal (Override Style Syntax)。

其他变更

blacklist.bbclass 已移除，其功能移至 base 类，使用更明确的 varflag 变量 SKIP_RECIPE，通过 bb.parse.SkipRecipe() 函数实现。用法保持不变，例如:
```
SKIP_RECIPE[my-recipe] = "Reason for skipping recipe"
```
allarch 软件包组不能再依赖通过 PKG 重命名的软件包，例如使用 debian 的软件包。这类软件包组配方应避免继承 allarch。
移除了 lnr 脚本。它实现的行为与 ln --relative --symbolic 相同。创建该脚本时，--relative 仅在 coreutils 8.16 及以后版本可用，对当时支持的旧发行版而言太新。当前支持的主机发行版均有足够新的 coreutils，因此不再需要该脚本。配方或类中的 lnr 调用应改为 ln --relative --symbolic，或使用简写 ln -rs。
原位于 insane 类中的 package_qa_handle_error() 函数已移动并重命名。自定义类中的引用应改为 oe.qa.handle_error()。
构建 perl 时不再默认启用 Berkeley db 支持，因为 Berkeley db 基本已过时。若要重新启用，可在 perl bbappend 的 PACKAGECONFIG 中追加 bdb，或在配置层面设置 PACKAGECONFIG:pn-perl。
xserver-xorg 配方移除了 PACKAGECONFIG 中的 xshmfence、xmlto 和 systemd 选项，因为本版本由 autotools 改为 meson 构建后已不再支持它们。
libsdl2 配方现在通过 EXTRA_OECMAKE 默认禁用多项 X11 功能，主要是为确保 native 构建的可复现性。必要时可在 bbappend 中修改这些选项。详情见 libsdl2 配方。
cortexa72-crc 和 cortexa72-crc-crypto 调优配置已移除，因为 cortexa72 现在默认启用 crc 扩展。相应引用应分别替换为 cortexa72 和 cortexa72-crypto。
Python 开发 shell（原名 devpyshell）重命名为 pydevshell。现在通过以下命令启动:
```
bitbake <target> -c pydevshell
```
不再生成 packagegroups-core-full-cmdline-libs 软件包组，因为库通常应由依赖关系引入。请移除所有相关引用。
解析配方时不再修改 TOPDIR 和当前工作目录。依赖旧行为的代码将无法工作，应改为显式使用适当的路径变量。
若要从镜像根文件系统中排除内核镜像，应设置 RRECOMMENDS:${KERNEL_PACKAGE_NAME}-base，而不是 RDEPENDS:${KERNEL_PACKAGE_NAME}-base。