6 类

类文件用于抽象公共功能，使多个配方（.bb）文件可以共享它们。 使用类时，只需让配方继承该类。多数情况下，继承就足以启用类的功能； 但有时还需要在配方中设置变量或覆盖默认行为。 也可以通过 INHERIT 全局继承类，使其作用于每个配方。

配方中常见的任何 Metadata 都可以放入类文件。 类文件使用 .bbclass 扩展名，通常位于 layer 的以下子目录之一：

  • classes-recipe/：供配方分别继承的类。

  • classes-global/：供全局继承的类。

  • classes/：使用上下文尚未明确的类。

类文件也可以位于 BUILDDIR （例如 build/）所指向的位置， 方式与 conf 目录中的 .conf 文件相同。 类文件和 .conf 文件一样，沿 BBPATH 搜索。

本章只介绍最实用和重要的类。 OpenEmbedded-Core (OE-Core) 的 meta/classes* 目录中还有其他类， 可直接查阅对应 .bbclass 文件了解详情。

6.1 allarch

allarch 供不产生架构专用输出的配方继承。 它禁用生成可执行二进制文件的配方通常需要的功能， 例如预先构建交叉编译器和 C 库，以及打包时拆分调试符号。

备注

与 Debian 等某些发行版的配方不同，OpenEmbedded 配方如果通过 RDEPENDS 和 TUNE_PKGARCH 使软件包依赖特定调优配置， 就绝不应使用 allarch 将其设为适用于所有架构， 即使它不生成架构专用输出也是如此。

这样配置会使 do_package_write_* 在调优配置不同的机器上具有不同签名。 此外，即使配方从未修改，每次为不同 MACHINE 构建镜像时， 也会产生不必要的重新构建。

默认所有配方继承 base 和 package， 启用生成可执行输出所需的功能。 如果配方只生成包含配置文件、媒体文件或 Python、Perl 等脚本的软件包， 应继承 allarch。

6.2 archiver

archiver 支持随二进制文件发布源码及其他材料。

有关源码归档的详情，请参阅《Yocto Project 开发任务手册》的 “在产品生命周期中维护开源许可证合规” 一节。用于控制归档创建的变量标志（varflags）见 ARCHIVER_MODE。

6.3 autotools*

autotools* 支持使用 GNU Autotools 构建的软件包。

autoconf、automake 和 libtool 提供标准化支持。 该类定义了适用于所有 Autotools 软件包的任务，例如 configure、compile。 通常只需定义几个标准变量，再使用 inherit autotools 即可。 这些类也适用于模拟 Autotools 行为的软件。 更多信息请参阅《Yocto Project 开发任务手册》的 “构建 Autotools 软件包”一节。

默认使用树外构建，即 autotools.bbclass 以 B != S 构建。

如果软件不支持树外构建，应让配方继承 autotools-brokensep。 它与 autotools* 行为相同，但使用 B == S。 当树外构建支持缺失或损坏时，这种方式有用。

备注

只要可能，建议修复并使用树外构建支持。

了解 autotools* 定义的任务及内部行为会有帮助：

6.4 barebox

barebox 管理 barebox 引导加载程序的构建。

如果 SRC_URI 包含名为 defconfig 的文件， 它会被复制为构建目录中的 .config，用作 barebox 配置。 也可以不提供文件，而将 BAREBOX_CONFIG 设为 barebox 源码树提供的 defconfig。 如果两者均未指定，该类会报错。

此类支持配置片段，并在内部包含 cml1， 为 barebox 提供 Kconfig 支持，从而启用 do_menuconfig 和 do_diffconfig 等任务。

生成的 barebox 二进制文件部署到 DEPLOY_DIR_IMAGE， 并安装到 BAREBOX_INSTALL_PATH （默认为 /boot），成为配方基本软件包的一部分。 这样既支持将其作为独立产物使用，也支持安装到根文件系统。 可通过 BAREBOX_BINARY 选择特定二进制文件进行部署和安装。 如果 EFI_PROVIDER 设为 barebox，该类使用 conf/image-uefi.conf 定义默认安装路径和命名约定。

向 BAREBOX_ENV_DIR 添加环境文件可以扩展编译进 barebox 的环境。 BAREBOX_FIRMWARE_DIR 可指定固件二进制文件搜索目录， 以加载 TF-A 或 OP-TEE 等额外固件。

6.5 base

base 很特殊，每个 .bb 文件都会隐式继承它。 它定义获取、解包、配置（默认为空）、编译（运行存在的 Makefile）、 安装（默认为空）和打包（默认为空）等标准基本任务。 这些任务经常被 autotools* 或 package 等其他类覆盖或扩展。

它还包含 oe_runmake 等常用函数。 oe_runmake 运行 make，同时传入 EXTRA_OEMAKE 以及直接传给该函数的参数。

6.6 bash-completion

为包含 bash-completion 数据的软件配方设置适当的打包方式和依赖。

6.7 bin_package

bin_package 是配方辅助类，禁用 do_configure 和 do_compile，并将 S 的内容复制到 D。 通过在 SRC_URI 中提供二进制软件包（例如 RPM）并继承该类， 可以方便地安装这些软件包。

对于 RPM 等不包含顶层子目录的软件包，应将 SRC_URI 的 subdir 选项设为 BP，使内容提取到 S 默认值所预期的目录。例如:

SRC_URI = "https://example.com/downloads/somepackage.rpm;subdir=${BP}"

此类也可用于压缩包，例如:

SRC_URI = "file://somepackage.tar.xz;subdir=${BP}"

该类将解压后的内容从 S 复制到 D。

它假定软件包在 S 中的内容布局与目标安装后的布局一致， 二进制软件包通常符合此要求。 例如，库的 RPM 包通常包含 usr/lib， 应解压为 ${S}/usr/lib/<library>.so.<version>，才能正确安装到 D。

备注

SRC_URI 中软件包的提取不由 bin_package 处理， 而是根据扩展名由适当的 获取器 处理。

6.8 binconfig

binconfig 帮助修正 shell 脚本中的路径。

pkg-config 普及之前，库通常附带名为 LIBNAME-config 的 shell 脚本， 提供构建软件所需的库和包含路径信息。此类辅助使用这类脚本的配方。

暂存阶段，构建系统将这些脚本安装到 sysroots/。 继承此类后，脚本中的全部路径会改为指向 sysroots/， 确保使用脚本的构建采用正确的交叉编译目录布局。 更多信息见 BINCONFIG_GLOB。

6.9 binconfig-disabled

binconfig 的替代版本， 通过让二进制配置脚本返回错误来禁用它们，改用 pkg-config 查询信息。 继承此类的配方应通过 BINCONFIG 指定待禁用脚本。

6.10 buildhistory

buildhistory 记录构建输出元数据的历史， 用于发现可能的回归并分析构建输出。 更多信息请参阅《Yocto Project 开发任务手册》的 使用 buildhistory 维护构建输出质量 一节。

6.11 buildstats

buildstats 记录构建期间每个任务的性能统计， 例如耗时、CPU 使用量和 I/O 使用量。

输出位于 BUILDSTATS_BASE，默认是 ${TMPDIR}/buildstats/。 可以使用 scripts/pybootchartgui/pybootchartgui.py 分析耗时， 它生成整个构建过程的级联图，有助于发现瓶颈。

要启用此类，可将“buildstats”添加到 USER_CLASSES。

6.12 buildstats-summary

全局继承时，在构建结束后输出共享状态复用统计。 此类需要启用 buildstats 才能工作。

6.13 cargo

cargo 允许使用 Cargo 编译 Rust 程序。Cargo 是 Rust 软件包管理器，可以获取依赖并构建程序。

使用此类构建 Rust 程序很简单，只需将 SRC_URI 指向可由 Cargo 构建的源码仓库，通常是通过 cargo new 创建、包含 Cargo.toml、 Cargo.lock 和 src 子目录的仓库。

如需构建并打包程序测试，请继承 ptest-cargo， 而不是 cargo。

示例见 zvariant_3.12.0.bb， 其中还展示如何处理 Git 源码依赖。 另一个只有 crate 依赖的示例是 uutils-coreutils， 由 cargo-bitbake 生成。

此类继承 cargo_common。

6.14 cargo_c

配方可以继承 cargo_c，生成可由 C/C++ 代码调用的 Rust 库。 只需将 inherit cargo 替换为 inherit cargo_c。

示例见 rust-c-lib-example_git.bb。

6.15 cargo_common

cargo_common 是内部类，不应直接使用。

例外是构建 Rust 编译器和运行时库的“rust”配方： 它由 Cargo 构建，但不能使用 cargo， 这也是引入此类的原因。

6.16 cargo-update-recipe-crates

cargo-update-recipe-crates 允许配方开发者读取源码树中的 Cargo.lock，更新 SRC_URI 中的 Cargo crate 列表。

为程序创建配方，例如使用 devtool， 让它继承 cargo 和 cargo-update-recipe-crates， 然后运行:

bitbake -c update_crates recipe

这会生成可在配方中包含的 recipe-crates.inc:

require ${BPN}-crates.inc

也可以通过 cargo-bitbake 实现。

6.17 ccache

ccache 为构建启用 C/C++ 编译器缓存，提供小幅性能提升。

有关编译器缓存的信息见 https://ccache.samba.org/。 如何在配置文件中启用、对特定配方禁用，以及跨构建共享 ccache 文件， 详见 ccache.bbclass。

在 configuration file 中提供以下设置后， 包括 native 在内的配方可通过 HOSTTOOLS 使用主机的 ccache 二进制程序:

ASSUME_PROVIDED += "ccache-native"
HOSTTOOLS += "ccache"

即使已启用此类，配方仍可将 CCACHE_DISABLE 设为“1”， 显式禁用 Ccache 支持。

使用 ccache 可能产生意外副作用，不建议使用。

6.18 chrpath

chrpath 封装“chrpath”工具， 在 nativesdk、cross 和 cross-canadian 配方构建期间修改二进制文件的 RPATH， 使其可重定位。

6.19 cmake

cmake 允许配方使用 CMake 构建软件。 通过 EXTRA_OECMAKE 可指定传给 cmake 的额外配置选项。

默认使用 Ninja 而非 GNU make，以提高构建性能。 如果配方无法通过 Ninja 构建，可以将 OECMAKE_GENERATOR 设为 Unix Makefiles，改用 GNU make。

如果需要安装应用提供的自定义 CMake 工具链文件，应在 do_install 期间将其安装到首选 CMake 模块目录 ${D}${datadir}/cmake/modules/。

6.20 cmake-qemu

cmake-qemu 可替代 cmake。 除后者功能外，它还向 cmake 传入 CMAKE_CROSSCOMPILING_EMULATOR， 允许通过 QEMU 用户模式模拟在主机上执行交叉编译的二进制程序。 更多信息见 CMake 文档相关章节。

QEMU 并不支持所有平台，此类仅适用于 机器功能 包含 qemu-usermode 的机器。 用户模式模拟存在一定风险，因此默认没有纳入主要的 cmake。

一种用法是在构建机器上通过 CTest 执行交叉编译的单元测试。 配置 CMAKE_CROSSCOMPILING_EMULATOR 后:

cmake --build --target test

即可透明地通过 QEMU 用户模式运行。

如果 CMake 项目在开发时考虑了这一场景，效果会很好。 这也适用于配置为使用 cmake-native 交叉编译的 IDE。

6.21 cml1

cml1 为 Linux 内核风格的构建配置系统提供基本支持。 “cml”表示“配置菜单语言”，源于 Linux 内核，也用于 U-Boot、BusyBox 等项目。 它也可以称为“kconfig”。

CML 配置文件 .config 默认应位于构建目录（B）， 可通过 KCONFIG_CONFIG_ROOTDIR 覆盖。

6.22 compress_doc

启用手册页和 info 页的压缩，旨在全局继承。 默认压缩机制为 gz（gzip），可通过 DOC_COMPRESS 选择其他机制。

6.23 copyleft_compliance

copyleft_compliance 为许可证合规保留源码。 它是 archiver 的替代类， 虽然已弃用并推荐改用后者，但仍有部分用户使用。

6.24 copyleft_filter

供 archiver 和 copyleft_compliance 过滤许可证的内部类，不应直接使用。

6.25 core-image

core-image 为 core-image-* 镜像配方提供公共定义， 例如额外的 IMAGE_FEATURES 支持。

6.26 cpan*

cpan* 支持 Perl 模块。

Perl 模块配方通常很简单，只需指向源码归档，再继承适当的类。 根据模块作者所用的构建方式，分为两种：

  • 使用旧 Makefile.PL 构建系统的模块，配方需要 cpan.bbclass。

  • 使用 Build.PL 构建系统的模块，配方需要 cpan_build.bbclass。

两种方式都继承 cpan-base，提供基本 Perl 支持。

6.27 create-spdx

create-spdx 支持根据镜像和 SDK 内容自动创建 SPDX SBOM 文档。

应从配置文件全局继承此类:

INHERIT += "create-spdx"

顶层 SPDX 输出以 JSON 格式生成，文件名为 IMAGE-MACHINE.spdx.json， 位于 Build Directory 的 tmp/deploy/images/MACHINE/。 该目录及 tmp/deploy/spdx 中还有其他相关文件。

具体行为和输出量可通过 SPDX_PRETTY、SPDX_INCLUDE_SOURCES 以及其他 SPDX_ 开头的变量控制。

详情见这些变量的说明，以及《Yocto Project 开发任务手册》的 “创建软件物料清单”一节。

6.28 cross

cross 为构建交叉编译工具的配方提供支持。

6.29 cross-canadian

cross-canadian 为构建 SDK 的 Canadian Cross 交叉编译工具的配方提供支持。更多信息见《Yocto Project 概览与概念手册》的 “交叉开发工具链生成”一节。

6.30 crosssdk

crosssdk 为构建 SDK 所用交叉编译工具的配方提供支持。 更多信息见《Yocto Project 概览与概念手册》的 “交叉开发工具链生成”一节。

6.31 cython

cython 可供需要将 Cython 纳入构建依赖（DEPENDS）的 Python 配方使用。

6.32 debian

debian 重命名输出软件包，使其遵循 Debian 命名政策， 例如 glibc 变为 libc6，glibc-devel 变为 libc6-dev。 重命名后的软件包名包含库名称和版本。

如果配方为多个库（.so 共享对象文件）创建软件包， 使用 LEAD_SONAME 指定应用该命名方案的库。

6.33 deploy

deploy 处理文件到 DEPLOY_DIR_IMAGE 的部署， 主要作用是使部署步骤能够通过共享状态加速。 继承此类的配方应定义自己的 do_deploy 函数， 将待部署文件复制到 DEPLOYDIR，并通过 addtask 将任务插入适当位置，通常在 do_compile 或 do_install 之后。 随后该类负责将文件从 DEPLOYDIR 暂存到 DEPLOY_DIR_IMAGE。

6.34 devicetree

devicetree 支持通过配方编译内核树之外的设备树源码。

树外设备树与内核树内设备树的编译过程相同， 支持包含内核中的 SoC dtsi 文件，以及 gpio.h 等 C 头文件。

do_compile 编译两类文件：

  • 扩展名为 .dts 的普通设备树源码。

  • 文件内容包含 /plugin/; 字符串的设备树覆盖文件。

生成的设备树二进制文件部署到 ${DEPLOY_DIR_IMAGE}/devicetree/。 这类似于 kernel-devicetree， 但额外使用 devicetree 子目录以避免命名冲突。 设备树还会填充到系统根目录，供其他配方访问。

默认编译 DT_FILES_PATH 中的全部设备树源码。 若只需特定文件，将 DT_FILES 设为以空格分隔、 相对于 DT_FILES_PATH 的文件列表。 为方便使用，.dts 和 .dtb 扩展名均可接受。

非覆盖类型的设备树二进制文件末尾会附加填充空间， 通常用于在启动时添加额外属性。 可将 DT_PADDING_SIZE 设为所需字节数，调整其大小。

控制此类的其他变量见 devicetree.bbclass 源码。

以下摘录自继承该类的 recipes-kernel/linux/devicetree-acme.bb 示例配方:

inherit devicetree
COMPATIBLE_MACHINE = "^mymachine$"
SRC_URI:mymachine = "file://mymachine.dts"

6.35 devshell

devshell 添加 do_devshell 任务。 是否包含此类由发行版策略决定。 更多使用说明见《Yocto Project 开发任务手册》的 “使用开发 Shell”一节。

6.36 devupstream

devupstream 通过 BBCLASSEXTEND 添加配方变体， 改从其他 URI（例如 Git）获取源码，而非使用压缩包。例如:

BBCLASSEXTEND = "devupstream:target"
SRC_URI:class-devupstream = "git://git.example.com/example;branch=main"
SRCREV:class-devupstream = "abcd1234"

添加这些语句后，将创建 DEFAULT_PREFERENCE 为“-1”的变体， 因此需要显式选择该变体才能使用。 针对开发的调整可通过 class-devupstream 覆盖完成。例如:

DEPENDS:append:class-devupstream = " gperf-native"
do_configure:prepend:class-devupstream() {
    touch ${S}/README
}

目前只支持创建目标配方的开发变体，不支持 native 或 nativesdk 变体。

BBCLASSEXTEND 的语法 devupstream:target 为 native 和 nativesdk 变体预留了支持，因此未来版本可以添加此功能。

由于 BitBake 自动获取依赖（例如 subversion-native）的机制， 对 Subversion 等其他版本控制系统的支持有限。

6.37 externalsrc

externalsrc 支持从 OpenEmbedded 构建系统之外的源码构建软件， 这意味着不使用通常的获取、解包和补丁流程。

默认情况下，构建系统分别通过 S 和 B 定位解包后的配方源码和构建目录。 继承此类后，使用 EXTERNALSRC 和 EXTERNALSRC_BUILD 最终定义 S 和 B。

此类默认要求源码支持将生成的对象放入 B 指定的独立目录。 B 默认设置如下，与源码目录 S 分离:

${WORKDIR}/${BPN}-{PV}/

更多信息见 WORKDIR、BPN 和 PV。

此类的更多说明见 OpenEmbedded-Core (OE-Core) 中 meta/classes/externalsrc.bbclass 的注释。 使用方式见《Yocto Project 开发任务手册》的 “从外部源码构建软件”一节。

6.38 extrausers

extrausers 允许在镜像层面应用额外用户和组配置。 全局继承或在镜像配方中继承后，可以通过 EXTRA_USERS_PARAMS 执行额外用户和组操作。

备注

此类添加的操作除镜像配方外，不绑定其他特定配方， 因而可作用于整个镜像。 要为特定配方添加用户和组配置，请使用 useradd*。

以下是在镜像配方中使用该类的示例:

inherit extrausers
EXTRA_USERS_PARAMS = "\
    useradd -p '' tester; \
    groupadd developers; \
    userdel nobody; \
    groupdel -g video; \
    groupmod -g 1020 developers; \
    usermod -s /bin/sh tester; \
    "

以下示例添加“tester-jim”和“tester-sue”两个用户并设置密码。 先在主机上生成已转义的密码哈希:

printf "%q" $(mkpasswd -m sha256crypt tester01)

将哈希保存到变量，再用于 useradd 参数:

inherit extrausers
PASSWD = "\$X\$ABC123\$A-Long-Hash"
EXTRA_USERS_PARAMS = "\
    useradd -p '${PASSWD}' tester-jim; \
    useradd -p '${PASSWD}' tester-sue; \
    "

最后，以下示例设置 root 密码:

inherit extrausers
EXTRA_USERS_PARAMS = "\
    usermod -p '${PASSWD}' root; \
    "

备注

从安全角度看，硬编码默认密码通常并不可取， 在某些司法辖区甚至不合法。构建生产镜像时不建议这样做。

6.39 features_check

features_check 允许各配方检查必需和冲突的 DISTRO_FEATURES、MACHINE_FEATURES 或 COMBINED_FEATURES。

支持以下变量：

如果配方通过这些变量指定的任一条件不满足，则跳过配方； 构建系统若尝试构建该配方，就会报错。

6.40 fontcache

fontcache 为字体包生成适当的安装后和删除后脚本 （postinst/postrm）。脚本调用 Fontconfig 的 fc-cache， 将字体添加到字体信息缓存。 缓存文件与架构相关，因此镜像创建期间若需在构建主机运行 postinst， 则通过 QEMU 执行 fc-cache。

如果字体位于主软件包之外的包中，使用 FONT_PACKAGES 指定这些包。

6.41 fs-uuid

fs-uuid 从 ${ROOTFS} 提取 UUID， 调用时根文件系统必须已构建完成。此类仅适用于 ext 文件系统，依赖 tune2fs。

6.42 gconf

gconf 为需要安装 GConf schema 的配方提供公共功能。 继承后自动创建独立包 ${PN}-gconf，存放这些 schema。 该包通过适当的安装后和删除后脚本，在目标镜像中注册和注销 schema。

6.43 gettext

gettext 支持构建使用 GNU gettext 国际化和本地化系统的软件。 所有构建此类软件的配方都应继承该类。

此类会配置配方构建翻译，除非：

6.44 github-releases

对于从 GitHub 获取发布压缩包的配方，github-releases 提供统一的上游版本检查方式，支持 devtool upgrade 和自动升级助手（AUH）。

使用时将此类添加到配方的 inherit 行。 如果 GITHUB_BASE_URI 默认值不合适，在配方中设置自己的值， 并在 SRC_URI 中使用 ${GITHUB_BASE_URI}。

6.45 gnomebase

gnomebase 是构建 GNOME 软件栈的配方基类。 它设置 SRC_URI 以从 GNOME 镜像站下载源码， 并向 FILES 添加典型 GNOME 安装路径。

6.46 go

go 支持构建 Go 程序。 由必需的 GO_IMPORT，以及可选的 GO_INSTALL 和 GO_INSTALL_FILTEROUT 控制行为。

使用 Yocto Project 构建 Go 程序时，可参考 go-helloworld_0.1.bb。

6.47 go-mod

go-mod 支持 Go modules，并继承 go。

另请参阅相关变量 GO_WORKDIR。

6.48 go-mod-update-modules

go-mod-update-modules 可用于 Go 配方， 定义可手动运行的 do_update_modules 任务，更新两个文件： 以下“BPN”对应 BPN。

  • BPN-go-mods.inc：配方依赖的 Go 模块列表。

  • BPN-licenses.inc：各依赖 Go 模块的许可证列表。

随后可通过 do_update_modules 自动更新这些文件。

6.49 go-vendor

go-vendor 支持离线构建，也称 Go vendoring。 模块依赖在 do_fetch 中下载，而不是在导入模块时下载， 符合 Yocto 预先获取全部源码的理念。

依赖解包到模块的 vendor 目录，并在其中生成清单文件。

6.50 gobject-introspection

支持构建提供 GObject introspection 功能的软件。 只有 DISTRO_FEATURES 包含“gobject-introspection-data”， 且 MACHINE_FEATURES 包含“qemu-usermode”时才启用。

备注

此功能 默认启用。 如果不适用，应分别通过 DISTRO_FEATURES_OPTED_OUT 或 MACHINE_FEATURES_OPTED_OUT 禁用。

6.51 grub-efi

grub-efi 提供用于构建可启动镜像的 grub-efi 专用函数。

支持以下变量：

  • INITRD：要连接并用作初始 RAM 磁盘的文件系统镜像列表，可选。 可为每个 LABEL 分别指定。

  • ROOTFS：要纳入作为根文件系统的镜像，可选。

  • GRUB_GFXSERIAL：设为“1”时，在启动菜单中同时支持图形和串口。

  • LABELS：自动配置的目标列表。

  • APPEND：每个 LABEL 的追加字符串覆盖列表。

  • GRUB_TITLE：每个 LABEL 的自定义标题。 未提供时，使用标签本身作为 GRUB 菜单项标题。

  • GRUB_OPTS：添加到配置中的额外选项，可选，以分号（;）分隔。

  • GRUB_TIMEOUT：执行默认 LABEL 前的等待时间，可选。

LABELS 中的每个 LABEL 都创建一个 GRUB 启动项， 部分变量可按标签分别定义，覆盖名称形式为 grub_LABEL。

例如，factory 标签的覆盖名称是 grub_factory。 要创建标题为“Factory Install”且附加 factory=yes 参数的菜单项，可使用:

LABELS:append = " factory"
APPEND:grub_factory = "factory=yes"
GRUB_TITLE:grub_factory = "Factory Install"

6.52 gsettings

gsettings 为安装 GSettings（glib）schema 的配方提供公共功能。 假定 schema 属于主软件包，添加适当的安装后和删除后脚本， 在目标镜像中注册和注销 schema。

6.53 gtk-doc

gtk-doc 是辅助类，引入适当的 gtk-doc 依赖并禁用 gtk-doc。

6.54 gtk-icon-cache

gtk-icon-cache 为使用 GTK+ 并安装图标的软件包生成 安装后和删除后脚本。脚本调用 gtk-update-icon-cache， 将字体添加到 GTK+ 图标缓存。 缓存文件与架构相关，因此镜像创建时若需在构建主机运行 postinst， 会通过 QEMU 执行该工具。

6.55 gtk-immodules-cache

gtk-immodules-cache 为安装虚拟键盘 GTK+ 输入法模块的软件包 生成安装后和删除后脚本。 脚本调用 gtk-update-icon-cache，将输入法模块添加到缓存。 缓存文件与架构相关，因此镜像创建时若需在构建主机运行 postinst， 会通过 QEMU 执行该工具。

如果模块不在主软件包中，使用 GTKIMMODULES_PACKAGES 指定包含模块的包。

6.56 gzipnative

gzipnative 允许使用不同的 native 版本 gzip 和 pigz， 而不是构建主机上的版本。

6.57 image

image 支持创建不同格式的镜像。 先根据软件包格式使用相应 rootfs*.bbclass 从软件包创建根文件系统， 再创建一个或多个镜像文件。

镜像定制见《Yocto Project 开发任务手册》的 “定制镜像”一节。 镜像创建过程见《Yocto Project 概览与概念手册》的 “镜像”一节。

6.58 image-buildinfo

image-buildinfo 将构建信息写入目标文件系统的纯文本文件， 默认位于 ${sysconfdir}/buildinfo，由 IMAGE_BUILDINFO_FILE 指定。 这有助于手动确定任意镜像的来源。文件包含两节：

  1. Build Configuration：变量及其值的列表，由 IMAGE_BUILDINFO_VARS 指定，默认包含 DISTRO 和 DISTRO_VERSION。

  2. Layer Revisions：构建所用全部层的修订版本。

构建 SDK 时，也会将相同内容写入文件，默认位置为 /buildinfo， 由 SDK_BUILDINFO_FILE 指定。

6.59 image_types

image_types 定义可通过 IMAGE_FSTYPES 启用的全部标准镜像输出类型。添加自定义类型时可参考此类。

image 默认自动启用该类， 通过 IMGCLASSES 变量使用它，方式如下:

IMGCLASSES = "rootfs_${IMAGE_PKGTYPE} image_types ${IMAGE_CLASSES}"
# Only Linux SDKs support populate_sdk_ext, fall back to populate_sdk_base
# in the non-Linux SDK_OS case, such as mingw32
inherit populate_sdk_base
IMGCLASSES += "${@['', 'populate_sdk_ext']['linux' in d.getVar("SDK_OS")]}"
IMGCLASSES += "${@bb.utils.contains_any('IMAGE_FSTYPES', 'live iso hddimg', 'image-live', '', d)}"
IMGCLASSES += "${@bb.utils.contains('IMAGE_FSTYPES', 'container', 'image-container', '', d)}"
IMGCLASSES += "image_types_wic"
IMGCLASSES += "rootfs-postcommands"
IMGCLASSES += "image-postinst-intercepts"
IMGCLASSES += "overlayfs-etc"
inherit_defer ${IMGCLASSES}

此类还处理镜像的转换和压缩。

备注

构建 VMware VMDK 镜像时，需要向 IMAGE_FSTYPES 添加“wic.vmdk”。 Virtual Box 虚拟磁盘镜像（“vdi”）和 QEMU 写时复制第 2 版 （“qcow2”）镜像的处理方式类似。

6.60 image-container

IMAGE_FSTYPES 包含 container 的 镜像 配方自动继承 image-container。 它提供相应设置，生成可供符合 OCI 标准的容器管理工具使用的镜像，例如 Podman 或 Docker。

备注

此类不会为目标构建或安装容器管理工具。 这些工具由 meta-virtualization 层提供。

应在 configuration file 中将 Linux 内核的 PREFERRED_PROVIDER 设为 linux-dummy:

PREFERRED_PROVIDER_virtual/kernel = "linux-dummy"

否则会报错。如有需要，可将 IMAGE_CONTAINER_NO_DUMMY 设为“1” 以避免此错误。

linux-dummy 扮演内核配方的角色，但不构建任何内容。 容器镜像无需包含 Linux 内核，因此适合将其作为首选内核提供者， 也能缩短构建时间。

使用此类只会向 DEPLOY_DIR_IMAGE 额外部署一个 tar.bz2 归档。 可在通常名为 Dockerfile 或 Containerfile 的容器文件中使用它。 例如，对于 Podman 或 Docker， 容器文件 可包含：

FROM scratch
ADD ./image-container-qemux86-64.rootfs.tar.bz2 /
ENTRYPOINT /bin/sh

这样即可使用生成的根文件系统镜像构建容器。

6.61 image-live

此类控制 live 镜像（HDDIMG 和 ISO）的构建。 镜像包含用于传统启动的 syslinux；如果 MACHINE_FEATURES 包含“efi”，还会包含 EFI_PROVIDER 指定的引导加载程序。

通常不直接使用此类，而是向 IMAGE_FSTYPES 添加“live”。

6.62 insane

insane 在软件包生成过程中增加质量保证检查， 对构建输出进行一系列检查，发现可能在运行时出现的常见问题。 是否包含此类通常由发行版策略决定。

可配置特定检查失败时产生警告或错误。 新引入的检查通常先产生警告；当元数据已达到已知良好状态后， 同一检查再失败则改为报错。 默认配置下可能遇到的消息见“质量检查错误和警告消息”章。

通过 WARN_QA 和 ERROR_QA 可全局控制检查行为， 例如在自定义发行版配置中设置。 若要在配方中跳过检查，应使用 INSANE_SKIP。 例如，要跳过主软件包中 .so 符号链接检查，可添加以下设置。 必须使用软件包名覆盖，本例为 ${PN}:

INSANE_SKIP:${PN} += "dev-so"

质量检查用于发现打包输出中真实或潜在的问题，禁用时应谨慎。

可列入 WARN_QA 和 ERROR_QA 的检查， 见《Yocto Project 参考手册》的 质量检查错误和警告消息。

6.63 kernel

kernel 处理 Linux 内核构建，包含构建各类内核树的代码。 所需头文件会暂存到 STAGING_KERNEL_DIR， 使树外模块可以使用 module 构建。

如果 SRC_URI 列出名为 defconfig 的文件， do_configure 默认将它复制为构建目录中的 .config， 自动作为本次内核配置。如果 .config 已存在，则不复制， 以允许配方通过 do_configure:prepend 等其他方式生成配置。

每个构建出的内核模块单独打包，通过解析 modinfo 输出创建模块间依赖。 如果需要全部模块，安装 kernel-modules 会安装所有模块包， 以及 kernel-vmlinux 等其他内核包。

此类还支持在构建内核镜像时嵌入初始 RAM 文件系统（Initramfs）。 构建方法见《Yocto Project 开发任务手册》的 “构建初始 RAM 文件系统（Initramfs）镜像”一节。

kernel 和 module 内部还使用 kernel-arch、module-base 等类。

6.64 kernel-arch

kernel-arch 为 Linux 内核及模块编译设置 ARCH 环境变量。

6.65 kernel-devicetree

kernel-devicetree 由 kernel 继承， 支持生成设备树。

主要由以下变量控制：

6.66 kernel-fit-image

kernel-fit-image 支持将内核镜像、设备树、U-Boot 脚本、 Initramfs 和额外可加载对象打包成单个 FIT 镜像。 理论上，FIT 可包含任意数量的内核、U-Boot 脚本、Initramfs 和设备树。 但此类目前只支持有限场景：一个内核镜像、可选的单个 U-Boot 脚本、 可选的单个 Initramfs，以及任意数量的设备树和可加载对象。

FIT 镜像由继承此类的配方创建，例如 linux-yocto-fitimage 为 Linux Yocto 内核创建 FIT 镜像。 此外，KERNEL_CLASSES 必须包含 kernel-fit-extra-artifacts， 将所需内核产物导出到 DEPLOY_DIR_IMAGE，供 FIT 镜像创建使用。

最简单的构建方式是在机器 configuration file 中添加:

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

然后执行:

bitbake linux-yocto-fitimage

结果是部署到 DEPLOY_DIR_IMAGE 的 fitImage 文件， 以及可安装的 linux-yocto-fitimage 软件包。

同样的方法适用于全部 linux-yocto 变体。 例如使用 linux-yocto-rt 时，在机器配置中添加:

KERNEL_CLASSES += "kernel-fit-extra-artifacts"
PREFERRED_PROVIDER_virtual/kernel = "linux-yocto-rt"

再运行以下命令，构建包含 RT 内核的 FIT 镜像:

bitbake linux-yocto-fitimage

其他层提供的内核也可使用同样方法。 不过，在自定义内核配方旁添加自定义 FIT 镜像配方通常更直观。 例如，提供 linux-vanilla 的层可以增加 linux-vanilla-fitimage， 以 linux-yocto-fitimage 的副本为基础定制。

内核通常作为镜像的依赖构建。 如果希望以 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"

此类处理以下配置变量：

6.67 kernel-fit-extra-artifacts

kernel-fit-extra-artifacts 将所需内核产物导出到 DEPLOY_DIR_IMAGE。 kernel-fit-image 使用这些产物创建 FIT 镜像， 其中可包含内核、设备树、可选的 U-Boot 脚本和 Initramfs。

构建 FIT 时，通常在内核配方或机器配置的 KERNEL_CLASSES 中添加此类。 它确保打包 FIT 所需的内核二进制文件、DTB 等相关文件均可用。

例如，启用方式为:

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

使用 kernel-fit-image 为内核生成 FIT 时，此设置必需。

6.68 kernel-grub

kernel-grub 在已部署目标上安装 RPM 更新内核时， 更新启动区域和启动菜单，将该内核设为优先启动项。

6.69 kernel-module-split

kernel-module-split 提供将 Linux 内核模块拆分为独立软件包的公共功能。

6.70 kernel-uboot

kernel-uboot 支持从 vmlinux 风格的内核源码构建。

6.71 kernel-uimage

kernel-uimage 支持打包 uImage。

6.72 kernel-yocto

kernel-yocto 提供从 linux-yocto 风格内核仓库构建的公共功能。

6.73 kernel-yocto-rust

kernel-yocto-rust 创建 Linux 内核所需的 Rust 依赖， 并在内核源码树中运行 make rustavailable，确保这些依赖可用。

6.74 kernelsrc

kernelsrc 设置 Linux 内核源码及版本。

6.75 lib_package

lib_package 适用于同时构建库和可执行程序， 但不希望程序默认随库安装的配方。 程序被放入独立的 ${PN}-bin 包，使安装可选。

6.76 libc*

libc* 支持构建使用 libc 的软件包：

6.77 license

license 提供许可证清单生成和许可证排除功能。 通过 INHERIT_DISTRO 的默认值自动启用。

6.78 linuxloader

提供 linuxloader()，返回平台动态加载器／链接器的值，供其他多个类使用。

6.79 logging

logging 提供按 BitBake 严重级别记录消息的标准 shell 函数， 包括 bbplain、bbnote、bbwarn、bberror、bbfatal 和 bbdebug。

由于 base 继承此类，默认已启用。

6.80 meson

meson 支持使用 Meson 构建软件。 可通过 MESON_BUILDTYPE、MESON_TARGET 和 EXTRA_OEMESON 指定传给 meson 命令行的额外配置选项。

6.81 metadata_scm

metadata_scm 提供查询源码管理系统（SCM）仓库分支和修订版本的功能。

base 在每次构建开始前用它输出各层修订版本。 由于被 base 继承，此类默认启用。

6.82 mime

mime 为安装 MIME 类型文件的软件包生成安装后和删除后脚本。 脚本调用 update-mime-database，将 MIME 类型添加到共享数据库。

6.83 mime-xdg

mime-xdg 为安装含 MimeType 条目的 .desktop 文件的 软件包生成安装后和删除后脚本。 脚本调用 update-desktop-database，将类型添加到桌面文件处理的 MIME 数据库。

因此，在新创建的镜像中通过文件浏览器打开文件时， 用户无需从所有已知应用中选择，避免列出无法打开该文件的应用。

如果配方将 .desktop 安装为绝对符号链接，当前实现无法检测到这些文件。 此时需将对应软件包名称加入 MIME_XDG_PACKAGES。

6.84 mirrors

mirrors 设置标准源码镜像站的 MIRRORS 条目。 当配方 SRC_URI 指定的上游源码不可用时，提供回退来源。

由于 base 继承此类，默认已启用。

6.85 module

module 支持构建树外 Linux 内核模块。 它继承 module-base 和 kernel-module-split， 实现 do_compile 与 do_install， 提供构建和打包内核模块所需的全部功能。

有关树外模块的一般信息，请参阅《Yocto Project Linux 内核开发手册》的 “集成树外模块”一节。

6.86 module-base

module-base 提供构建 Linux 内核模块的基础功能。 如果软件包含一个或多个模块，且有自己的模块构建方式， 配方通常继承此类而不是 module。

6.87 module-rust

module-rust 支持构建 Rust 编写的树外 Linux 内核模块， 并继承 module。

有关树外模块的一般信息，请参阅《Yocto Project Linux 内核开发手册》的 “集成树外模块”一节。

6.88 multilib*

multilib* 支持为不同目标优化配置或架构构建库， 并将它们并存安装到同一镜像中。

更多信息请参阅《Yocto Project 开发任务手册》的 “将多个版本的库文件组合到同一镜像”一节。

6.89 native

native 为构建在 Build Host 上运行的工具提供公共功能， 即使用构建主机编译器或其他主机工具构建的工具。

可以通过两种方式创建此类配方：

  • 创建继承 native 的 myrecipe-native.bb。 必须将该 inherit 语句放在所有其他 inherit 之后，确保最后继承此类。

    备注

    使用这种方式时，配方名称必须遵循:

    myrecipe-native.bb

    现有代码依赖此命名约定，不遵守可能导致隐蔽问题。

  • 或者，在任意目标配方（例如 myrecipe.bb）中添加以下设置， 创建 native 变体:

    BBCLASSEXTEND = "native"

    在配方中使用 :class-native 和 :class-target 覆盖， 分别指定主机和目标特有的功能。

两种方式都使用 native，只是应用方法不同。 第二种方式的优势是，如果同时需要主机和目标版本， 无需维护两个独立配方，公共部分自动共享。

6.90 nativesdk

nativesdk 为构建 SDK 中运行的工具提供公共功能， 即在 SDKMACHINE 上运行的工具。

可以通过两种方式创建配方：

  • 创建继承 nativesdk 的 nativesdk-myrecipe.bb。 必须将该 inherit 语句放在所有其他 inherit 之后，确保最后继承此类。

    备注

    配方名称必须遵循:

    nativesdk-myrecipe.bb

    现有代码依赖此命名约定，不遵守可能导致隐蔽问题。

  • 或者，在任意目标配方（例如 myrecipe.bb）中添加以下设置， 创建 nativesdk 变体:

    BBCLASSEXTEND = "nativesdk"

    在配方中使用 :class-nativesdk 和 :class-target 覆盖， 分别指定 SDK 机器和目标特有的功能。

两种方式都使用 nativesdk，只是应用方法不同。 第二种方式的优势是，如果同时需要 SDK 机器和目标版本， 无需维护两个独立配方，公共部分自动共享。

6.91 nopackages

为不需要打包的配方和类禁用打包任务。

6.92 nospdx

nospdx 允许配方退出 create-spdx 提供的 SPDX 生成。

6.93 npm

警告

NPM 获取器目前因安全问题而禁用。 更多信息见 355cd22。

支持构建通过 Node 软件包管理器（NPM） 获取的 Node.js 软件。

备注

当前继承此类的配方必须使用 npm:// 获取器，才能自动获取并打包依赖。

创建 NPM 包的方法见《Yocto Project 开发任务手册》的 “创建 Node Package Manager（NPM）软件包”一节。

6.94 overlayfs

嵌入式系统通常希望根文件系统只读，但很多应用又需要读写部分目录。 尤其当更新机制覆盖整个根文件系统，而应用数据需要跨更新保留时， 这种需求很常见。overlayfs 通过 overlayfs 实现它， 同时保持底层根文件系统只读。

使用时，在机器配置中为 overlayfs 上层使用的分区设置挂载点。 底层文件系统可以是 overlayfs 支持的任何类型。 以下设置必须放在机器配置中:

OVERLAYFS_MOUNT_POINT[data] = "/data"

备注

  • 如果在配方中重新定义此变量，质量检查将无法正确检查文件是否存在。

  • 只检查 systemd 挂载单元文件是否存在，不检查其内容。

  • overlayfs 内部机制及支持操作的详情见 Linux 内核官方文档。

此类假定 BSP 的其他位置（例如 systemd-machine-units 配方） 已定义 data.mount systemd 单元，并将其安装到镜像。

随后可按配方指定可写目录，例如在 my-application.bb 中:

OVERLAYFS_WRITABLE_PATHS[data] = "/usr/share/my-custom-application"

使用不同变量标志可支持多个挂载点。 假设需要可写位置，但数据无需在重启后保留， 则可为 tmpfs 文件系统定义 mnt-overlay.mount 单元。

机器配置中设置:

OVERLAYFS_MOUNT_POINT[mnt-overlay] = "/mnt/overlay"

配方中设置:

OVERLAYFS_WRITABLE_PATHS[mnt-overlay] = "/usr/share/another-application"

实际使用中，应用运行前可能需要挂载多个覆盖层，避免写入底层文件系统， 尤其底层只读时更是如此。此类提供名为 ${PN}-overlays.service 的 systemd 辅助服务来挂载覆盖层。 应用配方（下例名为 application）的 systemd 单元可添加以下依赖:

[Unit]
After=application-overlays.service
Requires=application-overlays.service

备注

此类不支持 /etc 目录本身，因为 systemd 依赖它。 要将 /etc 放入 overlayfs，请参阅 overlayfs-etc。

6.95 overlayfs-etc

将 /etc 放入 overlayfs，需要在启动早期特殊处理。 方法是提供自定义 init 脚本，在真正的 init 程序启动前先挂载 /etc， 因为后者启动时已需要该目录。

镜像配方中的用法示例:

IMAGE_FEATURES += "overlayfs-etc"

备注

不得直接继承此类，应使用 IMAGE_FEATURES 或 EXTRA_IMAGE_FEATURES。

机器配置至少应定义 overlayfs 所用设备、挂载点和文件系统类型:

OVERLAYFS_ETC_MOUNT_POINT = "/data"
OVERLAYFS_ETC_DEVICE = "/dev/mmcblk0p2"
OVERLAYFS_ETC_FSTYPE ?= "ext4"

如需更细致地控制挂载行为，可设置挂载选项，默认使用 defaults:

OVERLAYFS_ETC_MOUNT_OPTIONS = "wsync"

此类为 /sbin/init 生成提供两种选择：

  • 默认将原 /sbin/init 重命名为 /sbin/init.orig， 生成的 init 使用原名称 /sbin/init。 优点是无需修改内核参数；限制是不能使用软件包管理， 因为更新初始化管理器会移除生成的脚本。

  • 如果希望原 init 保持不变，可设置:

    OVERLAYFS_ETC_USE_ORIG_INIT_NAME = "0"

    生成的 init 将命名为 /sbin/preinit， 需要在引导加载程序配置中手动扩展内核参数。

6.96 own-mirrors

own-mirrors 便于设置自己的 PREMIRRORS， 使构建系统先从这些镜像获取源码，再尝试配方 SRC_URI 中指定的上游。

全局继承并设置 SOURCE_MIRROR_URL 即可使用。例如:

INHERIT += "own-mirrors"
SOURCE_MIRROR_URL = "http://example.com/my-source-mirror"

SOURCE_MIRROR_URL 只能指定一个 URL。

6.97 package

package 支持从构建输出生成软件包。 通用核心功能位于 package.bbclass，特定包格式的代码位于 package_deb、package_rpm 和 package_ipk。

在 build/conf/local.conf 或发行版 configuration file 中设置 PACKAGE_CLASSES，可控制输出格式列表，支持一种或多种格式。 镜像从软件包生成，因此必须使用打包类才能生成镜像。 变量中列出的第一个类用于镜像生成。

可选地在开发主机建立 DNF 可访问的软件包仓库（软件包源）， 即可在目标运行镜像时从该源安装软件包，即运行时安装。 更多信息见《Yocto Project 开发任务手册》的 “使用运行时软件包管理”一节。

所选打包类会影响构建性能和空间占用。 在依赖均已构建、完整构建同一或类似软件包的情况下， IPK 通常比 RPM 少耗时约百分之三十。 原因是 RPM 管理器创建和处理的 Metadata 更多。 因此，构建小型系统时可考虑将 PACKAGE_CLASSES 设为“package_ipk”。

但作出选择前，还应考虑 RPM 的以下特性：

  • 更多元数据带来更多能力，例如逐文件类型记录、文件校验和生成和安装时校验、 稀疏文件支持、Multilib 冲突检测与解决、ACID 风格升级，以及重新打包以支持回滚。

  • 对小型系统，Berkeley Database 和元数据的额外空间占用， 可能影响设备端升级能力。

关于打包类影响的更多讨论见 Yocto Project 邮件列表： https://lists.yoctoproject.org/g/poky/topic/61292484#msg6286。

6.98 package_deb

package_deb 支持创建 Debian（.deb）格式软件包， 并输出到 ${DEPLOY_DIR_DEB}。

此类继承 package，通过 PACKAGE_CLASSES 启用。

6.99 package_ipk

package_ipk 支持创建 IPK（.ipk）格式软件包， 并输出到 ${DEPLOY_DIR_IPK}。

此类继承 package，通过 PACKAGE_CLASSES 启用。

6.100 package_rpm

package_rpm 支持创建 RPM（.rpm）格式软件包， 并输出到 ${DEPLOY_DIR_RPM}。

此类继承 package，通过 PACKAGE_CLASSES 启用。

6.101 packagedata

packagedata 提供读取 PKGDATA_DIR 中 pkgdata 文件的公共功能。这些文件包含构建系统生成的各输出软件包的信息。

由于 package 继承此类，默认已启用。

6.102 packagegroup

packagegroup 为软件包组配方设置适当默认值， 例如 PACKAGES、PACKAGE_ARCH、ALLOW_EMPTY 等。 强烈建议所有软件包组配方继承此类。

用法见《Yocto Project 开发任务手册》的 “使用自定义软件包组定制镜像”一节。

此类以前称为 task。

备注

如果定义软件包组时需要设置:

PACKAGE_ARCH = "${MACHINE_ARCH}"

必须在配方的 inherit packagegroup 之前设置。 如果放在其后，可能破坏 BitBake 解析、产生“allarch”架构不匹配错误， 或使架构无关的默认值覆盖你的设置。

6.103 patch

patch 提供 do_patch 期间应用补丁的全部功能。

由于 base 继承此类，默认已启用。

6.104 perlnative

配方继承 perlnative 后，使用构建系统构建的 native Perl， 而非构建主机提供的版本。

6.105 pypi

pypi 为从 Python 软件包索引 PyPI 构建模块的配方设置适当变量。 默认根据 BPN 推导 PyPI 包名，移除存在的“python-”或“python3-”前缀。 部分情况下需要手动设置 PYPI_PACKAGE。

设置的变量包括 SRC_URI、SECTION、HOMEPAGE、 UPSTREAM_CHECK_URI、UPSTREAM_CHECK_REGEX 和 CVE_PRODUCT。

6.106 python_flit_core

python_flit_core 支持构建在 pyproject.toml 的 [build-system] 中将 build-backend 声明为 flit_core.buildapi 的 Python 模块。该后端符合 PEP-517， 另见 PEP-518。

此后端构建的模块是纯 Python，不含 C 或 Rust 扩展。

内部使用 python_pep517。

6.107 python_maturin

python_maturin 支持 python-maturin， 它替代 setuptools_rust，是构建 Python Wheel 的另一种后端。

6.108 python_mesonpy

python_mesonpy 支持使用 meson-python 构建系统的 Python 模块。

内部使用 python_pep517。

6.109 python_pbr

python_pbr 支持使用 Python Build Reasonableness 后端的 Python 项目。

它向构建时依赖添加 python3-pbr-native，内部使用 python_pep517。

6.110 python_pdm

python_pdm 支持通过 PDM 软件包和依赖管理器构建 Python 包。

它向构建时依赖添加 python3-pdm-backend-native， 内部使用 python_pep517。

6.111 python_pep517

python_pep517 构建并安装 Python wheel 二进制归档， 见 PEP-517。

配方通常不直接继承它，而是通过另一个类继承并添加相应 native 依赖。

例如 python_flit_core、python_setuptools_build_meta 和 python_poetry_core。

6.112 python_poetry_core

python_poetry_core 支持使用 Poetry Core 构建系统的 Python 模块。

内部使用 python_pep517。

6.113 python_pyo3

python_pyo3 确保 Rust 编写、使用 PyO3 构建的 Python 扩展正确设置交叉编译环境。

这是 python-setuptools3_rust 的内部类，配方不应直接使用。

6.114 python_uv_build

python_uv_build 可用于通过 uv_build 构建、 符合 PEP-517 的 Python 配方。

6.115 python-setuptools3_rust

python-setuptools3_rust 支持通过 PyO3 构建 Rust 实现的 Python 扩展，使编译和分发过程像 C 扩展一样方便。

此类继承 setuptools3 和 python_pyo3。

6.116 pixbufcache

pixbufcache 为安装 gdk-pixbuf 所用 pixbuf 加载器的软件包 生成安装后和删除后脚本。脚本调用 update_pixbuf_cache 将加载器加入缓存。 缓存与架构相关，因此镜像创建时若需在构建主机运行 postinst， 会通过 QEMU 执行该工具。

如果加载器不在配方的主软件包中，使用 PIXBUF_PACKAGES 指定包含它们的包。

6.117 pkgconfig

pkgconfig 提供通过 pkg-config 获取头文件和库信息的标准方式， 便于将 pkg-config 集成到使用它的库中。

暂存期间，BitBake 将 pkg-config 数据安装到 sysroots/。 利用 pkg-config 自身的系统根目录功能，此类无需再修改这些文件。

6.118 populate_sdk

populate_sdk 支持仅生成 SDK 的配方。 通过 do_populate_sdk 构建交叉开发工具链的优势， 见《Yocto Project 应用开发与可扩展软件开发工具包（eSDK）手册》的 “构建 SDK 安装程序”一节。

6 populate_sdk_*

populate_sdk_* 支持 SDK 创建，包括：

基类根据 IMAGE_PKGTYPE 继承相应的 populate_sdk_deb、 populate_sdk_rpm 或 populate_sdk_ipk。

基类确保创建全部源目录和目标目录，然后填充 SDK。 之后建立两个系统根目录：${SDK_ARCH}-nativesdk 包含交叉编译器和相关工具；目标系统根目录包含为 SDK 用途配置的目标根文件系统。 两者位于 SDK_OUTPUT，布局如下:

${SDK_OUTPUT}/${SDK_ARCH}-nativesdk-pkgs
${SDK_OUTPUT}/${SDKTARGETSYSROOT}/target-pkgs

最后，基类创建工具链环境设置脚本、SDK 压缩包和安装程序。

各格式专用类由基类继承和使用，分别支持相应类型的 SDK。

交叉开发工具链生成的更多信息见《Yocto Project 概览与概念手册》的 “交叉开发工具链生成”一节。 使用 do_populate_sdk 的优势，见《Yocto Project 应用开发与 可扩展软件开发工具包（eSDK）手册》的 “构建 SDK 安装程序”一节。

6.120 prexport

prexport 提供导出 PR 值的功能。

备注

不应直接使用此类；运行 bitbake-prserv-tool export 时会启用它。

6.121 primport

primport 提供导入 PR 值的功能。

备注

不应直接使用此类；运行 bitbake-prserv-tool import 时会启用它。

6.122 prserv

prserv 支持使用 PR 服务， 自动管理各配方 PR 的递增。

由于 package 继承此类，它默认启用。 不过，只有设置 PRSERV_HOST 后，构建系统才实际启用其功能。

6.123 ptest

ptest 为提供运行时测试的软件配方提供测试打包和安装功能。

此类应由各配方分别继承，但除非 DISTRO_FEATURES 包含“ptest”， 否则大部分功能都被禁用。 更多信息见《Yocto Project 测试环境手册》的 “使用 ptest 测试软件包”一节。

6.124 ptest-cargo

ptest-cargo 扩展 cargo， 添加 compile_ptest_cargo 和 install_ptest_cargo， 分别构建并安装 Cargo.toml 定义的测试套件，放入专用 -ptest 包。

6.125 ptest-gnome

为 GNOME 软件包启用专用 ptest，其测试通过 gnome-desktop-testing 执行。

配置和运行方法见《Yocto Project 测试环境手册》的 “使用 ptest 测试软件包”一节。

6.126 ptest-python-pytest

Python 配方可继承 ptest-python-pytest， 为使用 pytest 单元测试框架的包自动配置 ptest。

配方中的 PTEST_PYTEST_DIR 指定测试目录， do_install_ptest_base 将其与专用 run-ptest 脚本安装到 D。

6.127 python3-dir

python3-dir 提供 Python 3 的基本版本、位置和 site-packages 位置。

6.128 python3native

python3native 支持使用构建系统构建的 native Python 3， 而不是构建主机提供的版本。

6.129 python3targetconfig

python3targetconfig 同样使用构建系统构建的 native Python 3， 但允许访问目标机器的配置，例如正确的安装目录。 它还会增加对目标 python3 的依赖，因此只应在确有需要时使用， 避免不必要地延长构建时间。

6.130 qemu

qemu 为需要 QEMU 或检查 QEMU 是否存在的配方提供功能。 通常用于通过 QEMU 应用模拟模式，在构建主机上运行目标程序。

6.131 recipe_sanity

recipe_sanity 检查主机上是否存在可能影响构建的配方前置条件， 例如已设置的变量或已安装的软件。

6.133 relocatable

relocatable 使二进制文件安装到系统根目录后可重定位。

它使用 chrpath，并由 cross 和 native 使用。

6.134 remove-libtool

remove-libtool 向 do_install 添加后置函数， 删除 libtool 安装的全部 .la 文件，使系统根目录和目标软件包都不包含它们。

如果配方需要这些文件，可通过以下设置禁用删除:

REMOVE_LIBTOOL_LA = "0"

备注

此类默认不启用。

6.135 report-error

report-error 支持启用 错误报告工具， 将构建错误信息提交到中央数据库。

它收集配方、版本、任务、机器、发行版、构建系统、目标系统、主机发行版、 分支、提交和日志等调试信息，生成 JSON 报告， 保存到 ${LOG_DIR}/error-report。

6.136 retain

retain 在配方任务失败时，将工作目录或其他指定目录打成压缩包。 当构建环境是临时环境，或调试时无法直接访问检查时，这很有用。

在配置中添加以下内容以启用:

INHERIT += "retain"

可通过 RETAIN_ENABLED 对特定配方禁用。

6.137 rm_work

rm_work 支持删除临时工作区，降低构建对磁盘空间的需求。

OpenEmbedded 构建可能占用大量空间，其中一部分是各配方在 ${TMPDIR}/work 下的工作文件。 软件包生成后，这些文件不再必需，但默认保留以便检查和调试。 若希望构建过程中删除它们以节省空间，可在 Build Directory 的 build/conf/local.conf 中添加:

INHERIT += "rm_work"

如果正在配方工作目录内修改和构建源码，启用此类可能导致修改丢失。 可将正在开发的配方名称加入 RM_WORK_EXCLUDE，排除删除其工作目录。 该变量也可在 build/conf/local.conf 中设置，例如:

RM_WORK_EXCLUDE += "busybox glibc"

若配方仍使用此类，但希望 BitBake 保留 WORKDIR 中 除 temp 外的特定文件或目录，可设置 RM_WORK_EXCLUDE_ITEMS:

RM_WORK_EXCLUDE_ITEMS += "items_to_keep"

6.138 rootfs*

rootfs* 支持创建镜像根文件系统，包括：

  • rootfs-postcommands：定义镜像配方的文件系统后处理函数。

  • rootfs_deb：从 .deb 软件包创建根文件系统。

  • rootfs_rpm：从 .rpm 软件包创建根文件系统。

  • rootfs_ipk：从 .ipk 软件包创建根文件系统。

  • rootfsdebugfiles： 将构建主机上的额外文件直接安装到根文件系统。

根据 PACKAGE_CLASSES 选择其中一个类，从软件包创建根文件系统。

更多信息见《Yocto Project 概览与概念手册》的 “生成镜像”一节。

6.139 rust

rust 是仅供“rust”配方构建 Rust 编译器和运行时库的内部类。 除该配方外，不应直接使用。

6.140 rust-common

rust-common 是 cargo_common 和 rust 使用的内部类，不应直接使用。

6.141 rust-target-config

rust-target-config 是 cargo_common 和 rust 使用的内部类，不应直接使用。

它通过 do_rust_gen_targets，根据 TUNE_FEATURES 生成用于交叉编译的 JSON 规格文件。

6.142 sanity

sanity 检查主机是否安装前置软件， 提醒用户可能影响构建的问题。 它还对 build/conf/local.conf 进行基本用户配置检查， 防止常见错误导致构建失败。是否包含此类通常由发行版策略决定。

6.143 sbom-cve-check

sbom-cve-check 使用 sbom-cve-check 命令行工具进行构建后 CVE 分析。 由于输入为 SPDX 文件，它依赖 create-spdx。

应通过 core/yocto/sbom-cve-check 片段启用：

$ bitbake-config-build enable-fragment core/yocto/sbom-cve-check

镜像构建后，根据 SBOM_CVE_CHECK_EXPORT_VARS 当前值， 在 DEPLOY_DIR_IMAGE 生成一份或多份报告。

配置行为的更多信息见 Yocto Project 参考手册变量表 中以 SBOM_CVE_CHECK_ 开头的变量。

6.144 sbom-cve-check-recipe

sbom-cve-check-recipe 使用 sbom-cve-check 对配方进行构建后 CVE 分析，输入为 SPDX，因而依赖 create-spdx。

任意配方均可继承它。与 ref-classes-sbom-cve-check 不同， 它只使用 create_recipe_sbom 之后生成的配方 SBOM， 识别底层软件并分析，因此无需构建配方本身。

在配方中继承后，运行：

$ bitbake <recipe> -c sbom_cve_check_recipe

随后根据 SBOM_CVE_CHECK_EXPORT_VARS 当前值， 在 DEPLOY_DIR_IMAGE 生成一份或多份报告。

配置行为的更多信息见 Yocto Project 参考手册变量表 中以 SBOM_CVE_CHECK_ 开头的变量。

6.145 scons

scons 支持使用 SCons 构建系统的软件配方。 可通过 EXTRA_OESCONS 指定传给 SCons 命令行的额外配置选项。

6.146 sdl

sdl 支持构建使用 Simple DirectMedia Layer（SDL）库的软件。

6.147 python_setuptools_build_meta

python_setuptools_build_meta 支持在 pyproject.toml 的 [build-system] 中将 build-backend 声明为 setuptools.build_meta 的 Python 模块，符合 PEP-517。 另见 PEP-518。

这些模块可以是纯 Python，也可以包含 C 或 Rust 扩展。

内部使用 python_pep517。

6.148 setuptools3

setuptools3 支持使用基于 setuptools 的构建系统的 Python 3.x 扩展， 例如只有 setup.py，尚未迁移到正式 pyproject.toml 格式的项目。 使用这类构建系统的配方应继承此类。

备注

do_compile 现在调用 setup.py bdist_wheel 构建 wheel 二进制归档，见 PEP-427。

因此，仍使用 Python 标准库中已弃用 distutils 的旧软件不能打包为 wheel。 常见解决方式是将 from distutils.core import setup 替换为 from setuptools import setup。

备注

do_install 现在安装 wheel 二进制归档。 当前 setuptools 已弃用旧的 setup.py install。 如果 setup.py 不兼容 wheel，例如创建 Python 模块或标准入口点之外的文件， 应使用 setuptools3_legacy。

6.149 setuptools3_legacy

setuptools3_legacy 支持使用 setuptools 的 Python 3.x 扩展， 例如只有 setup.py 而未迁移到 pyproject.toml 的项目。 与 setuptools3 不同，它使用传统 setup.py 的 build 和 install 命令，不使用 wheel。 这种用法已经 弃用， 但仍较常见。

6.150 setuptools3-base

setuptools3-base 为其他构建 Python 3.x 扩展的类提供可复用基础。 若需要 setuptools3 未提供的功能， 可使用 inherit setuptools3-base。 部分配方不需要 setuptools3 的任务，因此改为继承此类。

6.151 sign_rpm

sign_rpm 支持生成已签名的 RPM 软件包。

6.152 siteinfo

siteinfo 提供其他类或配方可能需要的目标信息。

例如，Autotools 的某些测试必须在目标硬件运行，交叉编译时通常不可行。 site 信息提供缓存结果，使测试可以跳过，同时仍获得正确值。 meta/site 目录按架构、字节序和所用 libc 等类别保存测试结果。 此类通过 CONFIG_SITE 提供与当前构建相关的数据文件列表， 由 Autotools 自动读取。

它还提供 SITEINFO_ENDIANNESS、SITEINFO_BITS 等变量，供元数据其他位置使用。

6.153 sstate

sstate 提供共享状态支持， 通过 INHERIT_DISTRO 的默认值启用。

更多信息见《Yocto Project 概览与概念手册》的 “共享状态缓存”一节。

6.154 staging

staging 将系统根目录文件安装到各配方工作目录，包含两个关键任务：

此类代码较复杂，基本分为两个阶段：

  • 第一阶段： 处理需要向依赖自己的其他配方共享文件的配方。 这些文件通常由 do_install 安装到 ${D}。 do_populate_sysroot 将其中一部分复制到 ${SYSROOT_DESTDIR}， 由 SYSROOT_DIRS、SYSROOT_DIRS_NATIVE 和 SYSROOT_DIRS_IGNORE 控制范围。

    备注

    配方还可通过 SYSROOT_PREPROCESS_FUNCS 声明处理函数，进一步定制文件。

    随后根据这些文件构建共享状态对象， 并将文件放入 build/tmp/sysroots-components/ 的子目录。 扫描文件中指向原安装位置的硬编码路径。 如果在文本文件中发现，将路径替换为标记，并生成需要替换的文件列表。 这些调整称为“FIXMEs”。扫描范围由 SSTATE_SCAN_FILES 控制。

  • 第二阶段： 处理通过 DEPENDS 声明依赖、需要使用其他配方内容的配方。 do_prepare_recipe_sysroot 执行时， 在 WORKDIR 创建 recipe-sysroot 和 recipe-sysroot-native， 将 sysroots-components 中对应文件硬链接到配方工作目录。

    备注

    无法建立硬链接时，构建系统使用实际复制。

    然后根据第一阶段生成的列表修复路径中的“FIXMEs”。 最后执行系统根目录 ${bindir} 中以 postinst- 开头的所有文件。

    备注

    不建议普遍使用这类系统根目录安装后脚本， 但它们可解决用户创建、模块索引等问题。

    配方还可能存在 DEPENDS 之外的依赖， 例如 do_unpack[depends] += "tar-native:do_populate_sysroot"。 因此，系统根目录创建函数 extend_recipe_sysroot 也会作为这些任务的前置函数，执行类似处理。

    安装依赖时会遍历依赖图，按与共享状态安装完全相同的规则处理。 例如，native 工具会加入其 native 依赖， 但目标库的依赖不会继续遍历或安装。 两者使用相同的共享状态依赖代码，确保无论是否使用共享状态，构建结果都一致。 详情见 sstate 的 setscene_depvalid()。

    构建系统维护已安装文件的清单，以便按需安装任意依赖。 还会保存已安装内容的共享状态哈希，变化时可以重新安装。

6.155 syslinux

syslinux 提供用于构建可启动镜像的 syslinux 专用功能。

支持以下变量：

  • INITRD：要连接并用作初始 RAM 磁盘的文件系统镜像列表，可选。

  • ROOTFS：要作为根文件系统纳入的镜像，可选。

  • AUTO_SYSLINUXMENU：设为“1”时自动创建菜单。

  • LABELS：自动配置的目标列表。

  • APPEND：各标签的追加字符串覆盖列表。

  • SYSLINUX_OPTS：添加到 syslinux 文件的额外选项，以分号分隔。

  • SYSLINUX_SPLASH：使用启动菜单时，指定 VGA 菜单背景。

  • SYSLINUX_DEFAULT_CONSOLE：设为“console=ttyX”，改变内核默认启动控制台。

  • SYSLINUX_SERIAL：设置另一个串口；空字符串表示关闭串口。

  • SYSLINUX_SERIAL_TTY：设置另一个“console=tty...”内核启动参数。

6.156 systemd

systemd 支持安装 systemd 单元文件的配方。 只有 DISTRO_FEATURES 包含“systemd”时，其功能才启用。

配方或 Makefile，即 do_install 调用的安装过程， 应将单元文件放入 ${D}${systemd_unitdir}/system。 如果单元文件不在主软件包中，应通过 SYSTEMD_PACKAGES 指定所属软件包。

将 SYSTEMD_SERVICE 设为服务文件名称， 并使用软件包名称覆盖指定作用对象。 主软件包使用 ${PN}，例如 connman 配方中:

SYSTEMD_SERVICE:${PN} = "connman.service"

服务默认配置为开机自动启动，除非 SYSTEMD_AUTO_ENABLE 设为“disable”。

更多信息见《Yocto Project 开发任务手册》的 “选择初始化管理器”一节。

6.157 systemd-boot

systemd-boot 提供 systemd-boot 引导加载程序专用的可启动镜像功能。 这是内部类，不应直接使用。

备注

此类源于旧版 Yocto Project 的 gummiboot 类与 systemd 项目的合并。

将 EFI_PROVIDER 设为“systemd-boot”即可使用。 这样会创建不依赖 systemd 的独立 EFI 引导加载程序。

相关配置变量见 SYSTEMD_BOOT_CFG、SYSTEMD_BOOT_ENTRIES 和 SYSTEMD_BOOT_TIMEOUT。

另请参阅 Systemd-boot 文档。

6.158 terminal

terminal 支持启动终端会话， 由 OE_TERMINAL 控制使用哪个终端模拟器。

其他类在需要独立终端时使用它。 例如 PATCHRESOLVE 为“user”时的 patch， 以及 cml1 和 devshell。

6.159 testexport

testexport 基于 testimage， 将测试环境导出到 OpenEmbedded Build System 之外。 它生成所需目录结构，以便通过 Python 脚本 runexported.py 执行运行时测试。

详情见《Yocto Project 测试环境手册》的 导出测试 一节。

6.160 testimage

testimage 支持通过 QEMU 或真实硬件对镜像运行自动化测试， 负责加载测试和启动镜像。使用之前需要配置环境。

在配置中添加以下内容以启用:

IMAGE_CLASSES += "testimage"

测试通过 ssh 在目标上运行命令，使用 Python 编写并使用 unittest 模块。

可以按如下方式对镜像运行测试:

$ bitbake -c testimage image

若希望每个镜像构建后自动测试，可设置 TESTIMAGE_AUTO:

TESTIMAGE_AUTO = "1"

启用、运行和创建测试的方法见《Yocto Project 测试环境手册》的 “执行自动化运行时测试”一节。

6.161 testsdk

此类支持对 SDK 运行自动化测试，调用方式为:

$ bitbake -c testsdk image

运行的测试模块列表由 TESTSDK_SUITES 控制。

备注

建议通过 IMAGE_CLASSES 而非 INHERIT 继承 testsdk，进行 SDK 自动化测试。

6.162 texinfo

上游软件在构建时调用 texinfo 工具的配方应继承此类。 为提高性能，native 和 cross 配方使用 texinfo-dummy-native 的替代脚本； 目标架构配方使用真正的 Texinfo 工具，默认采用主机系统提供的版本。

备注

若希望使用构建系统附带的 Texinfo 配方，可从 ASSUME_PROVIDED 移除“texinfo-native”，并从 SANITY_REQUIRED_UTILITIES 移除 makeinfo。

6.163 toaster

toaster 收集软件包和镜像信息， 将其作为 BitBake 用户界面可接收的事件发送。 Toaster 界面运行时启用此类，不应直接使用。

6.164 toolchain-scripts

toolchain-scripts 提供设置已安装 SDK 环境的脚本。

6.165 toolchain/clang

toolchain/clang 定义使用 Clang/LLVM 编译器和工具构建配方的命令。

不应直接继承，而应选择以下方式之一：

6.166 toolchain/clang-native

toolchain/clang-native 定义通过 Clang/LLVM 编译器和工具 构建 native 配方的命令，不受构建上下文影响。

toolchain/gcc-native 定义 BUILD_CC、BUILD_CXX 等配方很少直接使用的变量。 例外是构建过程中某个阶段需要使用主机编译器的目标配方。

不应直接继承。TOOLCHAIN_NATIVE 为“clang”时， 由 base 继承。

6.167 toolchain/gcc

toolchain/gcc 定义使用 GCC/Binutils 编译器和工具构建配方的命令。

不应直接继承，而应选择以下方式之一：

6.168 toolchain/gcc-native

toolchain/gcc-native 定义通过 GCC/Binutils 编译器和工具 构建 native 配方的命令，不受构建上下文影响。

它定义 BUILD_CC、BUILD_CXX 等配方很少直接使用的变量。 例外是构建过程中某个阶段需要使用主机编译器的目标配方。

不应直接继承。TOOLCHAIN_NATIVE 为“gcc”时， 由 base 继承。

6.169 typecheck

typecheck 根据定义的类型，验证配置层面设置的变量值。 构建系统允许通过“type”变量标志定义类型，例如:

IMAGE_FEATURES[type] = "list"

6.170 uboot-config

uboot-config 支持配置一个或多个 U-Boot 构建配置。

有三种方式为机器配置配方：

  • 使用 UBOOT_MACHINE 及配套的 UBOOT_BINARY，例如:

    UBOOT_MACHINE = "config"
UBOOT_BINARY = "u-boot.bin"

  • 使用 UBOOT_CONFIG 相关变量，例如:

    UBOOT_CONFIG ??= "foo bar"
UBOOT_CONFIG[foo] = "config"
UBOOT_CONFIG[bar] = "config2"

UBOOT_CONFIG_IMAGE_FSTYPES[bar] = "fstype"

UBOOT_CONFIG_BINARY[foo] = "binary"

UBOOT_CONFIG_MAKE_OPTS[foo] = "FOO=1"
UBOOT_CONFIG_MAKE_OPTS[bar] = "BAR=1"

UBOOT_CONFIG_FRAGMENTS[foo] = "foo.fragment"

    上例选择所有可能配置（foo 和 bar）。 也可以修改 UBOOT_CONFIG，仅包含其中一个， 从而只构建 foo 或 bar。例如:

    UBOOT_CONFIG = "foo"
UBOOT_CONFIG[foo] = "config"
UBOOT_CONFIG[bar] = "config2"

    每个构建配置对应 UBOOT_CONFIG 的一个变量标志定义， 各配置的相关调整由不同的 UBOOT_CONFIG_* 变量定义。

    • UBOOT_CONFIG[config]：此构建配置选用的 defconfig 文件， 位于 U-Boot 源码树的 configs 文件夹。

      此选项必需。

      更多信息见 UBOOT_CONFIG。

    • UBOOT_CONFIG_IMAGE_FSTYPES[config]：为该构建配置生成镜像时， 追加到 IMAGE_FSTYPES 的镜像类型。

      这允许构建使用该配置生成的二进制文件的额外镜像格式。

      此项可选，不需要时可以不指定。

      更多信息见 UBOOT_CONFIG_IMAGE_FSTYPES。

    • UBOOT_CONFIG_BINARY[config]：选择要部署到 DEPLOY_DIR_IMAGE 的二进制文件。 U-Boot 构建可能生成多个文件，例如:

      u-boot.bin
u-boot-with-spl.bin

      将 binary 设为 u-boot-with-spl.bin 后，会部署该文件， 并在过程中重命名以包含构建配置名称，即上例中的 foo 或 bar。

      未指定时默认使用 UBOOT_BINARY。

      更多信息见 UBOOT_CONFIG_BINARY。

    • UBOOT_CONFIG_MAKE_OPTS[config]：配置和编译此 U-Boot 配置时， 传给 make 的额外选项，添加在 UBOOT_MAKE_OPTS 的选项之前。

      此项可选，未指定时不添加任何内容。 如果某配置不需要 make 选项，可不设置该配置的标志。

      更多信息见 UBOOT_CONFIG_MAKE_OPTS。

    • UBOOT_CONFIG_FRAGMENTS[config]：源码树中的额外配置片段， 在 do_configure() 期间用于设置构建， 添加在 UBOOT_FRAGMENTS 的片段之前。

      此项可选，未指定时不添加任何内容。 如果某配置没有额外片段，可不设置该配置的标志。

      更多信息见 UBOOT_CONFIG_FRAGMENTS。

  • 仅使用 UBOOT_CONFIG 的旧方式。 此方法正在弃用，见下文说明。 例如:

    UBOOT_CONFIG ??= "foo bar"
UBOOT_CONFIG[foo] = "config,images,binary"
UBOOT_CONFIG[bar] = "config2,images2,binary2"

    上例选择所有配置（foo 和 bar）。 修改 UBOOT_CONFIG，只包含其中一个，也可仅构建该配置。

    每个构建配置对应 UBOOT_CONFIG 的一个变量标志， 最多包含三个逗号分隔选项（config,images,binary）：

    • config：选择的 defconfig 文件，位于 U-Boot 源码树的 configs 目录。 此选项必需。

    • images：追加到 IMAGE_FSTYPES 的镜像类型，供当前配置生成镜像。 这允许构建使用该配置生成的二进制文件的额外镜像格式。 此项可选，可以留空。

    • binary：选择要部署到 DEPLOY_DIR_IMAGE 的二进制文件。 U-Boot 构建可能输出多个文件，例如:

      u-boot.bin
u-boot-with-spl.bin

      设为 u-boot-with-spl.bin 后，将部署该文件， 同时重命名以包含配置名称，即上例中的 foo 或 bar。 未设置时默认使用 UBOOT_BINARY。

备注

旧流程已经弃用，不建议继续使用。 未来控制选项的扩展不会加入该方式， 此功能将在 wrynose LTS 版本之后移除。

不能同时使用 UBOOT_MACHINE 和 UBOOT_CONFIG。

更多信息见这两个变量的说明。

6.171 uboot-extlinux-config

uboot-extlinux-config 支持生成 extlinux.conf， 它属于 U-Boot 的 通用发行版配置方案。

可在 U-Boot 配方中继承:

inherit uboot-extlinux-config

默认禁用实际功能。要启用，在 U-Boot 配方或 bbappend 中 将 UBOOT_EXTLINUX 设为“1”:

UBOOT_EXTLINUX = "1"

此外，还必须将 UBOOT_EXTLINUX_ROOT 设为 Linux 内核命令行 的 root= 参数。例如，以下设置指向 MMC 块设备 0 的第二分区:

UBOOT_EXTLINUX_ROOT = "root=/dev/mmcblk0p2"

构建 U-Boot 配方后，生成的 extlinux.conf 放入 DEPLOY_DIR_IMAGE：

tmp/deploy/images/<MACHINE>/extlinux.conf

可使用《Yocto Project 参考手册》的 变量表 中以 UBOOT_EXTLINUX_ 开头的变量定制该文件。

备注

UBOOT_EXTLINUX_LABELS 可以指定多个标签，即多个启动项。 此时应使用覆盖式赋值指定各标签属性。更多信息见该变量定义。

小技巧

在 WIC 中使用 bootloader 时， 应在 .wks.in 显式设置 --configfile="${DEPLOY_DIR_IMAGE}/extlinux.conf"， 使用此类生成的配置。否则会生成默认 extlinux.conf，不考虑此类的设置。

6.172 uboot-sign

uboot-sign 支持 U-Boot 验证启动，应由 U-Boot 配方继承。

使用以下变量：

更多详情见 U-Boot 的 验证启动 和 签名过程 文档。

另请参阅此类所仿照的 kernel-fit-image。

6.173 uki

uki 支持 统一内核镜像（UKI）。 UKI 将内核、Initramfs、签名、元数据等组合为单个兼容 UEFI 固件的二进制文件。 此类应由根文件系统镜像配方继承。 构建配置还应使用 Initramfs，以 systemd-boot 提供启动菜单， 目标硬件必须支持 UEFI，建议以 systemd 作为初始化系统。 镜像构建应创建 UEFI 的 ESP 分区，并将 systemd-boot 和 UKI 复制到该分区。 Wic 示例配置见 meta/files/wic/efi-uki-bootdisk.wks.in。 UKI 使用 systemd 的参考实现 ukify 生成。 此类使用多个变量，并尽量提供合理默认值。

变量包括：

用法示例见 oeqa 自测试 meta/lib/oeqa/selftest/cases/uki.py。 另有运行时测试 meta/lib/oeqa/runtime/cases/uki.py， 验证目标启动的 UKI 是否与构建时 UKI_FILENAME 指定的文件相同。

6.174 uninative

uninative 允许二进制程序在较旧或较新的 Glibc 系统上运行。 因此，native 配方的 共享状态缓存 可以跨不同主机发行版及版本共享，成为“通用”缓存。

为实现这一点，编译时通过 --dynamic-linker 将动态加载器改为我们自己的 ld.so。 程序执行时会找到它，再由其修改后的搜索路径找到较新版本的 Glibc。

链接时不改变二进制程序的链接对象，因为系统头文件与较新 Glibc 不匹配， 会导致难以理解的故障。替换加载器相当于程序编译后系统升级了 Glibc， 因此是上游支持的机制。

一个限制是，uninative Glibc 必须不旧于所有共享该缓存的系统上的版本。 因此，开发分支和稳定分支会定期更新 uninative。

另一个潜在问题是静态链接：在较新 Glibc 系统上创建的静态库， 可能使用旧版没有的符号，导致旧系统链接失败。 这也是 native 二进制程序不使用静态链接的原因之一。

启用后，构建开始时会下载包含预构建 C 库的压缩包。 OpenEmbedded-Core (OE-Core) 默认通过 meta/conf/distro/include/yocto-uninative.inc 启用。不是从 Poky 派生的发行版也可使用 require conf/distro/include/yocto-uninative.inc。 也可以自行构建 uninative-tarball 配方，发布压缩包，例如通过 HTTP， 再相应设置 UNINATIVE_URL 和 UNINATIVE_CHECKSUM。 示例同样见 meta/conf/distro/include/yocto-uninative.inc。

可扩展 SDK 无条件使用此类。 构建可扩展 SDK 时，会构建 uninative-tarball 并将生成的压缩包包含在 SDK 中。

6.175 update-alternatives

多个来源提供同名命令时，update-alternatives 辅助 alternatives 系统。 例如 busybox、binutils 和 elfutils 都可提供 ar。 此类重命名各包中的冲突二进制文件，使多个软件包可以同时安装而不冲突， 并在安装或卸载时将符号链接指向优先级最高的程序。 无论安装或移除了哪些包，ar 命令都能继续使用。

需要定义以下变量：

这些变量列出软件包需要的替代命令，提供链接路径、目标的默认链接等。 详情见 update-alternatives.bbclass 中的注释。

备注

也可以在配方中直接使用 update-alternatives 命令， 不过此类在多数情况下更简单。

6.176 update-rc.d

update-rc.d 使用 update-rc.d 为软件包安全安装初始化脚本。 构建系统处理卸载前停止服务、安装时启动服务等细节。

由 INITSCRIPT_PACKAGES、INITSCRIPT_NAME 和 INITSCRIPT_PARAMS 三个变量控制，详情见各变量说明。

6.177 upstream-stable-release-point

upstream-stable-release-point 为使用点分隔版本号的配方 自动生成 UPSTREAM_STABLE_RELEASE_REGEX， 支持限制在同一稳定系列内的点版本升级， 例如从 1.4.2 到 1.4.3，但不能到 1.5.0。

通过 STABLE_VERSION_PARTS （默认为 "2"）确定 PV 开头多少个点分隔部分构成稳定前缀。例如：

  • PV = "1.4.2" 且 STABLE_VERSION_PARTS = "2" 时， 生成 ^1\.4(\.\d+)*$。

  • PV = "259.5" 且 STABLE_VERSION_PARTS = "1" 时， 例如 systemd，生成 ^259(\.\d+)*$。

如果稳定版本部分不以点分隔，例如 openssh 的 10.2p1， 应直接设置 UPSTREAM_STABLE_RELEASE_REGEX，而不继承此类。

6.178 useradd*

useradd* 支持为目标上的软件包添加用户或组。 例如，系统服务应以专用用户或组运行时，可用这些类创建相应账户。 OpenEmbedded-Core (OE-Core) 中的 meta-skeleton/recipes-skeleton/useradd/useradd-example.bb 展示如何向两个软件包添加三个用户和组。

useradd_base 提供用户和组设置的基础功能。

这些类支持 USERADD_PACKAGES、USERADD_PARAM、 GROUPADD_PARAM 和 USERMOD_PARAM。

useradd-staticids 支持使用静态 uid 和 gid 添加用户或组。

默认情况下，软件包安装时动态分配 uid 和 gid。 如果程序不关心具体值，这种方式正常工作，最终值取决于安装顺序。 若不确定的 uid/gid 会造成问题，可改用静态值覆盖默认动态行为。 设置静态值后，构建系统沿 BBPATH 查找 files/passwd 和 files/group 获取对应值。

使用静态值时需要设置相关变量，见 USERADDEXTENSION、 USERADD_UID_TABLES、USERADD_GID_TABLES 和 USERADD_ERROR_DYNAMIC。 另请参阅 useradd*。

备注

不直接继承 useradd-staticids，而是通过 USERADDEXTENSION 启用或禁用。 在已经配置好的系统中切换后，TMPDIR 可能残留错误 uid/gid。 删除 TMPDIR 可纠正这种情况。

6.179 utility-tasks

utility-tasks 支持适用于所有配方的各类辅助任务， 例如 do_clean 和 do_listtasks。

由于 base 继承此类，默认已启用。

6.180 utils

utils 提供实用 Python 函数，通常用于 ${@...} 等内联表达式，例如 bb.utils.contains()。

由于 base 继承此类，默认已启用。

6.181 vala

vala 支持构建 Vala 语言编写的软件。

6.182 vex

vex 生成外部工具检查 CVE 等漏洞所需的元数据。

在 build/conf/local.conf 或发行版 configuration file 中继承后，会为每个配方添加 generate_vex 任务:

INHERIT += "vex"

构建镜像时，它在 DEPLOY_DIR_IMAGE 为全部所用软件包生成报告， 也为构建所用的全部配方生成文件。

用法示例:

bitbake -c generate_vex openssl

6.183 waf

waf 支持使用 Waf 构建系统的软件配方。 可通过 EXTRA_OECONF 或 PACKAGECONFIG_CONFARGS 指定传给 Waf 命令行的额外配置选项。

6.184 yocto-check-layer

yocto-check-layer 由 yocto-check-layer 脚本使用，确保 Yocto Project Compatible 层的软件包不会跳过 insane 在 CHECKLAYER_REQUIRED_TESTS 中列出的必需检查。

它向全部配方添加一个执行额外处理的匿名 Python 函数， 不建议通过 INHERIT 全局继承。 应使用 yocto-check-layer 脚本，由脚本管理此类。

有关兼容层的更多信息，请参阅《Yocto Project 开发手册》的 确保层与 Yocto Project 兼容 一节。