版本 5.3 (whinlatter)

5.3 (whinlatter) 迁移说明

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

Poky 仓库的 master 分支不再更新

Poky 仓库的 master 分支不再更新。这 并不 意味着 Poky 发行版已弃用，而是克隆基础层以及设置 Poky 构建环境的方式 发生了变化。

可以选择以下任一方式：

Whinlatter 之前的版本仍会更新其在 Poky 仓库中的分支，直到支持期结束。

这一变更的更多背景信息见： https://lists.openembedded.org/g/openembedded-architecture/message/2179

WORKDIR 变更

不再支持 S = ${WORKDIR}/something

不再支持将配方的 S 设置为 ${WORKDIR}/something， 这样设置会报错。应将配方改为:

S = "${UNPACKDIR}/something"

应移除 S = ${WORKDIR}/git 和 S = ${UNPACKDIR}/git

Git 获取器现在解包到 BB_GIT_DEFAULT_DESTSUFFIX 目录， 而不是 UNPACKDIR 下的 git/ 目录。 OpenEmbedded-Core (OE-Core) 的 bitbake.conf 将 BB_GIT_DEFAULT_DESTSUFFIX 设置为 BP。

此位置与 bitbake.conf 设置的 S 默认值一致，因此配方中的 S 设置可以且应该移除。

注意，如果 S 设置为 Git 检出目录的子目录，则应根据上一条进行调整:

S = "${UNPACKDIR}/${BP}/something"

配方的其他位置也可能将源码检出位置硬编码为 "git"。如果出现在 SRC_URI 中，应替换为 BB_GIT_DEFAULT_DESTSUFFIX；其他位置则替换为 BP。

避免繁琐手动编辑的调整方法

可以用以下 sed 命令移除整个层中的 S = "${WORKDIR}/git 设置:

sed -i "/^S = \"\${WORKDIR}\/git\"/d" `find . -name '*.bb' -o -name '*.inc' -o -name '*.bbclass'`

随后，以下命令可将剩余的 S 赋值改为引用 UNPACKDIR， 而不是 WORKDIR:

sed -i "s/^S = \"\${WORKDIR}\//S = \"\${UNPACKDIR}\//g" `find . -name '*.bb' -o -name '*.inc' -o -name '*.bbclass'`

第一项修改可能产生许多连续空行，可用以下命令移除:

sed -i -z -E 's/([ \t\f\v\r]*\n){3,}/\n\n/g' `find . -name '*.bb' -o -name '*.inc'`

BitBake Git 获取器的 tag 参数

Git 获取器（git://）的 tag= 参数已更新。标签对应的提交 SHA 将与 SRCREV 变量或 SRC_URI 中 URI 的 rev= 参数提供的值比较。 使用 Git 获取器获取采用标签发布的仓库时，强烈建议将该参数加入 URI。

等号赋值两侧的空格

如果配方中的 = 赋值两侧没有空白字符，现在会显示新的警告:

<filename>:<line number> has a lack of whitespace around the assignment: '<assignment>'

例如，以下赋值会触发警告:

FOO="bar"
FOO= "bar"
FOO ="bar"

应替换为:

FOO = "bar"

应重命名含连字符的 Wic 插件

Python 升级后，文件名包含连字符（-）的 Wic 插件 不再受支持。必须重命名插件文件，将连字符替换为下划线（_）。

也建议更新所有 WKS 文件，将连字符替换为下划线。例如，bootimg-partition.py 插件已重命名为 bootimg_partition.py，因此使用此插件的 WKS 文件应将每处 --source bootimg-partition 改为 --source bootimg_partition。

不过，当前 WIC 代码会自动将所有 --source 调用中的连字符转换为下划线， 因此使用 OpenEmbedded-Core (OE-Core) 上游插件的现有 WKS 文件不会失效。

KERNEL_IMAGETYPE 不再支持 fitImage

KERNEL_IMAGETYPE 不再支持 fitImage 类型。创建 FIT 镜像的逻辑已移出 kernel 类。应改为创建一个新配方来构建此 FIT 镜像，具体方法见 5.3 (whinlatter) 迁移说明的 已移除的类 一节。

systemd 可预测接口命名不再默认使用 MAC 策略

过去，启用 pni-names 发行版功能 时， systemd 配方 会强制将 "mac" 策略设为默认值。

这一行为未跟随上游变更，因此现已取消。现在启用 pni-names 发行版功能 时，会选择 systemd 的默认策略 （来自 https://github.com/systemd/systemd/blob/v257.8/network/99-default.link）。

若要在 systemd 中恢复 "mac" 策略（撰写本说明时为 257.8 版本）， 应按照 systemd.link(5) 设置 NamePolicy 和 AlternativeNamesPolicy。

移除没有许可证的 Linux 内核固件

linux-firmware 配方现在默认排除未提供任何许可证信息的固件。 配方通过名为 REMOVE_UNLICENSED 的变量维护内部排除列表； 如果需要没有许可证的固件，可以覆盖此变量。完整的已移除固件列表见 该配方。

native 和 nativesdk 类中 *FLAGS 变量的行为变更

此前，native 和 nativesdk 类对 CPPFLAGS、CFLAGS、CXXFLAGS 和 LDFLAGS 变量分别使用以下直接赋值:

CPPFLAGS = "${BUILD_CPPFLAGS}"
CFLAGS = "${BUILD_CFLAGS}"
CXXFLAGS = "${BUILD_CXXFLAGS}"
LDFLAGS = "${BUILD_LDFLAGS}"

以及:

CPPFLAGS = "${BUILDSDK_CPPFLAGS}"
CFLAGS = "${BUILDSDK_CFLAGS}"
CXXFLAGS = "${BUILDSDK_CXXFLAGS}"
LDFLAGS = "${BUILDSDK_LDFLAGS}"

当配方试图用 += 运算符追加这些变量时，会产生赋值顺序竞争。 因此，若希望修改同时适用于目标、native 和 nativesdk 上下文，配方可以改用 :append。

现在，配方可以安全地使用 += 运算符实现同样的目的。

这一变更也意味着，过去用 += 运算符所作的赋值原来仅作用于目标上下文， 现在则 同时作用于三者：目标、native 和 nativesdk 上下文。

无意中依赖旧行为的配方，应将这些赋值改为使用 TARGET_ 变量，例如将:

CFLAGS += "something"

改为:

TARGET_CFLAGS += "something"

参见 https://git.openembedded.org/openembedded-core/commit/?id=a157b2f9d93428ca21265cc860a3b58b3698b3aa。

支持的内核版本

本版本将 OLDEST_KERNEL 设置为 5.15，因此默认不支持更旧的内核。 详情见 4.3 迁移说明。

支持的发行版

与此前版本相比，新增支持在以下 GNU/Linux 发行版上运行 BitBake：

  • Debian 13 (Trixie)

  • Fedora 42

  • Ubuntu 25.04

  • Ubuntu 25.10

参见 所有受支持的发行版。

已移除的变量

以下变量已移除：

已移除的配方

本版本移除了以下配方：

  • libsoup-2.4：OpenEmbedded-Core (OE-Core) 中最后一个使用者 gst-examples 已升级，并移除了对 libsoup-2.4 的依赖。 该配方已移至 meta-oe。

  • glibc-y2038-tests：此配方仅提供测试，而这些测试现在由 glibc-testsuite 提供，因此移除。

  • python3-ndg-httpsclient：核心中对此配方的最后一项依赖已于 2024 年 5 月 通过 dfa482f1998 ("python3-requests: cleanup RDEPENDS") 移除，且没有其他使用者。

  • xf86-input-mouse：该项目已停止支持 Linux。

  • xf86-input-vmmouse：它在运行时依赖已停止支持 Linux 的 xf86-input-mouse。

  • babeltrace：移除，改用 babeltrace2。

  • cwautomacros：一组早已过时的自定义 autotools* 宏， 没有任何其他配方使用它。

  • rust-llvm：Rust 和 LLVM 配方已调整为依赖 llvm 配方，因此移除。

已移除的 PACKAGECONFIG 条目

  • dropbear：enable-x11-forwarding （重命名为 x11）

  • libxml2: ipv6

  • squashfs-tools: reproducible

  • mesa: kmsro, osmesa, xa

  • systemd: dbus

已移除的类

本版本移除了以下类：

  • kernel-fitimage.bbclass：由 kernel-fit-image 类取代。 新实现解决了长期存在的 问题 12912。

    如果使用内核 FIT 镜像支持，需要：

    1. 确保 KERNEL_CLASSES 变量包含 kernel-fit-extra-artifacts， 使所需文件可在 DEPLOY_DIR_IMAGE 目录中获取:

      KERNEL_CLASSES += "kernel-fit-extra-artifacts"

    2. 使用专门的 FIT 镜像配方，而不是基础内核配方。例如，不再使用:

      bitbake linux-yocto

      现在改用以下命令构建 FIT 镜像:

      bitbake linux-yocto-fitimage

      对于自定义内核配方，通常应创建相应的自定义 FIT 镜像配方。

    3. 如果在根文件系统中使用 FIT 镜像替代内核镜像，请在机器配置文件中 添加以下配置:

      # Create and deploy the vmlinux artifact which gets included into the FIT image
KERNEL_CLASSES += "kernel-fit-extra-artifacts"

# Do not install the kernel image package
RRECOMMENDS:${KERNEL_PACKAGE_NAME}-base = ""
# Install the FIT image package
MACHINE_ESSENTIAL_EXTRA_RDEPENDS += "linux-yocto-fitimage"

# Configure the image.bbclass to depend on the FIT image instead of only
# the kernel to ensure the FIT image is built and deployed with the image
KERNEL_DEPLOY_DEPEND = "linux-yocto-fitimage:do_deploy"

    更多信息见 kernel-fit-image 一节。

  • icecc.bbclass：报告显示该类自 Yocto Mickledore 起就已无法正常工作， 说明使用者可能很少。它没有自动化测试，而且难以建立和维护测试环境。 原来的用户和维护者现在也已不再使用它。

其他变更

  • xserver-xorg：移除 ${PN}-xwayland 子包，因为 xwayland 现在已有独立配方。

  • gdk-pixbuf：移除作为配方 PACKAGECONFIG 一部分的 GDK_PIXBUF_LOADERS 变量。现在可直接修改 PACKAGECONFIG 达到相同效果。

  • 移除 meta/conf/distro/include/distro_alias.inc 包含文件。 该文件将配方名称关联到一个或多个发行版软件包名，但已不再使用和维护。

  • 从 nghttp2 配方中移除 nghttp2-proxy 软件包。一次升级后，该配方仅构建库 （因为配方的 EXTRA_OEMAKE 默认包含 -DENABLE_APP=OFF）， 导致 nghttp2-proxy 软件包变为空包。

  • 移除 util-linux 配方中的 util-linux-fcntl-lock 软件包， 因为 util-linux 的 flock 命令现在支持 --fcntl 标志。

    目前使用 fcntl-lock 命令的配方应改用 flock --fcntl。

  • barebox 已从 v2025.02.0 更新到 v2025.09.0。迁移建议见 上游迁移指南。