14 变量表

本章列出 OpenEmbedded 构建系统中的常用变量，概述其作用和内容。

A B C D E F G H I K L M N O P Q R S T U V W X Z

GNU 规范架构名称中应用二进制接口（ABI）字段的扩展，例如“eabi”。

ABI 扩展在机器包含文件中设置。例如 meta/conf/machine/include/arm/arch-arm.inc 设置以下扩展:

ABIEXTENSION = "eabi"

ALLOW_EMPTY 

指定软件包即使为空是否也要输出。BitBake 默认不生成空包。当 RDEPENDS 或其他强制运行时要求依赖该包的存在时，此默认行为可能造成问题。

与所有控制软件包的变量一样，必须始终结合软件包名称覆盖使用，例如:

ALLOW_EMPTY:${PN} = "1"
ALLOW_EMPTY:${PN}-dev = "1"
ALLOW_EMPTY:${PN}-staticdev = "1"

ALTERNATIVE 

列出软件包中需要替代二进制命名方案的命令。有时多个软件包提供相同命令，构建系统需要通过 alternatives 系统使用不同的二进制命名方式，使这些命令可以共存。

使用时列出本软件包中也由其他包提供的命令。例如 busybox 包有四个这样的命令，可按如下方式指定:

ALTERNATIVE:busybox = "sh sed test bracket"

更多信息见“update-alternatives”一节。

ALTERNATIVE_LINK_NAME 

alternatives 系统使用此变量将重名命令映射到实际位置。例如 busybox 提供的 bracket 命令也由其他软件包提供时，必须通过此变量指定实际位置:

ALTERNATIVE_LINK_NAME[bracket] = "/usr/bin/["

上例中，busybox 的 bracket 命令二进制文件，即 [，位于 /usr/bin/。

备注

未定义时，默认使用 ${bindir}/name。

更多信息见“update-alternatives”一节。

ALTERNATIVE_PRIORITY 

alternatives 系统使用此变量为重名命令设置默认优先级。可以设置不区分命令或软件包的统一默认值，也可针对特定命令设置与软件包无关的默认值，或为特定软件包中的特定命令设置默认值。可用语法为:

ALTERNATIVE_PRIORITY = "priority"
ALTERNATIVE_PRIORITY[name] = "priority"
ALTERNATIVE_PRIORITY_pkg[name] = "priority"

更多信息见“update-alternatives”一节。

ALTERNATIVE_TARGET 

alternatives 系统使用此变量为重名命令创建默认链接目标位置。可以为全部命令设置不区分命令名和软件包的统一位置，也可为特定命令设置与软件包无关的位置，或为特定软件包中的特定命令设置位置。可用语法为:

ALTERNATIVE_TARGET = "target"
ALTERNATIVE_TARGET[name] = "target"
ALTERNATIVE_TARGET_pkg[name] = "target"

备注

未定义时，继承 ALTERNATIVE_LINK_NAME 的值。

如果两者相同，会在 ALTERNATIVE_TARGET 的目标末尾追加 .{BPN}。

如果引用的文件尚未重命名，alternatives 系统会为其重命名，避免必须在 do_install 中重命名替代文件，同时仍在需要时保留对该命令的支持。

更多信息见“update-alternatives”一节。

ANY_OF_DISTRO_FEATURES 

继承 features_check 时，指定一组发行版功能，当前配置必须至少启用其中一项，构建系统才会构建该配方。如果所列功能均未出现在当前 DISTRO_FEATURES 中，配方会被跳过；如果构建系统尝试构建它，则会报错。

APPEND 

为 LABELS 指定的各目标提供追加字符串的覆盖列表。

用法见 grub-efi。

AR 

运行 ar 所需的最小命令及参数。

ARCHIVER_MODE 

与 archiver 一起使用时，决定创建发布归档所用的信息类型。通过以下变量标志（varflags），可归档打补丁后、原始、配置后的源码等:

ARCHIVER_MODE[src] = "original"                   # Uses original (unpacked) source files.
ARCHIVER_MODE[src] = "patched"                    # Uses patched source files. This is the default.
ARCHIVER_MODE[src] = "configured"                 # Uses configured source files.
ARCHIVER_MODE[diff] = "1"                         # Uses patches between do_unpack and do_patch.
ARCHIVER_MODE[diff-exclude] ?= "file file ..."    # Lists files and directories to exclude from diff.
ARCHIVER_MODE[dumpdata] = "1"                     # Uses environment data.
ARCHIVER_MODE[recipe] = "1"                       # Uses recipe and include files.

工作方式见 OpenEmbedded-Core (OE-Core) 中的 meta/classes/archiver.bbclass。

AS 

运行 汇编器 所需的最小命令及参数。

ASSUME_PROVIDED 

列出 BitBake 不尝试构建的配方名称，即 PN 值。 BitBake 假定这些配方已经构建完成。

在 OpenEmbedded-Core 中，主要用于指定不应构建的 native 工具。例如指定 git-native 后，会使用主机 Git 二进制程序，而不构建该配方。

ASSUME_SHLIBS 

提供额外的 shlibs 提供者映射，补充或覆盖系统自动提供的信息。多个条目用空格分隔。

例如，按以下形式声明 packagename 提供 shlibname，并可指定版本:

shlibname:packagename[_version]

以下示例声明 libegl-implementation 提供 libEGL.so.1:

ASSUME_SHLIBS = "libEGL.so.1:libegl-implementation"

AUTO_LIBNAME_PKGS 

继承 debian 时，指定应检查库并按 Debian 库包规则重命名的软件包。默认即继承该类。

默认值为“${PACKAGES}”，因此作用于配方显式生成的全部软件包。

AUTO_SYSLINUXMENU 

启用 syslinux 引导加载程序的自动菜单生成。必须在配方中设置，由 syslinux 检查。

AUTOREV 

将 SRCREV 设为此变量值时，使用仓库最新源码修订版本。例如:

SRCREV = "${AUTOREV}"

使用上述方式获取最新版本时，必须确保 PV 包含 +，使 bitbake 打包时将版本控制信息加入 PKGV。例如:

PV = "6.10.y+git"

更多信息见《Yocto Project 开发任务手册》的 “自动递增软件包版本号”一节。

AUTOTOOLS_SCRIPT_PATH 

使用 autotools* 时，保存 Autotools 构建系统使用的各脚本位置，默认值为 S。

AVAILTUNES 

构建系统可使用的、已定义 CPU 和 ABI 调优配置（tune）列表。

此列表只表示可用项，并非所有项都与特定机器配置兼容，在 Multilib 配置中，各项之间也不一定兼容。

添加调优配置时，必须使用 BitBake 的“+=”操作符追加并保留空格，不要使用“=”直接替换整个列表。更多信息见《BitBake 用户手册》的 “Basic Syntax”一节。

AZ_SAS 

使用 Azure Storage 获取器（az://）时的 Azure Storage 共享访问签名。获取器可用它进行认证并访问非公开产物:

AZ_SAS = ""se=2021-01-01&sp=r&sv=2018-11-09&sr=c&skoid=<skoid>&sig=<signature>""

更多信息见 Microsoft Azure Storage 文档： https://docs.microsoft.com/en-us/azure/storage/common/storage-sas-overview

B 

Build Directory 中用于存放配方构建生成对象的目录。默认与 S 相同，其定义为:

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

可以将 S 与 B 指向的目录分离。大多数基于 Autotools 的配方支持此方式。构建系统默认对 gcc 和部分内核配方使用独立目录。

BAD_RECOMMENDATIONS 

列出不应安装的“仅推荐”软件包，即仅通过 RRECOMMENDS 引入的包。将其列入此变量即可阻止安装:

BAD_RECOMMENDATIONS = "package_name package_name package_name ..."

可在 configuration file 全局设置，也可直接在镜像配方中指定:

BAD_RECOMMENDATIONS = "package_name"

如果其他软件包强制依赖这些包，即列入配方的 RDEPENDS，构建系统会忽略排除请求，仍安装它们以避免依赖错误。

RPM 和 IPK 后端支持此变量，DEB 不支持。

相关信息见 NO_RECOMMENDATIONS 和 PACKAGE_EXCLUDE。

BAREBOX_BINARY 

使用 barebox 时，指定需要部署和安装的某个二进制文件。

barebox 构建系统可一次生成多个二进制文件，默认全部以原名称部署并安装。

用法示例:

BAREBOX_BINARY = "barebox-boundarydevices-imx6dl-nitrogen6x-1g.img"

BAREBOX_CONFIG 

使用 barebox 时，指定要构建的 barebox defconfig 名称。该名称必须是 barebox 构建环境已知的 defconfig 文件。主要用于无需专用配置的通用场景。此类已经为部分 QEMU 机器设置它:

BAREBOX_CONFIG:qemuarm = "multi_v7_defconfig"
BAREBOX_CONFIG:qemuarm64 = "multi_v8_defconfig"
BAREBOX_CONFIG:qemux86-64 = "efi_defconfig"

除这些情况外，默认值为空。有关如何提供 barebox 配置的信息，见 barebox。

BASE_LIB 

CPU 或 ABI 调优配置的库目录名，仅适用于 Multilib 上下文。有关 Multilib，见《Yocto Project 开发任务手册》的 “将多个版本的库文件组合到同一镜像”一节。

在 OpenEmbedded-Core (OE-Core) 的机器包含文件中定义。未使用 Multilib 时，默认值为“lib”。

BASE_WORKDIR 

指向全部配方工作目录的基础目录，默认值为“${TMPDIR}/work”。

BB_ALLOWED_NETWORKS 

以空格分隔的主机列表，指定获取器可从哪些主机获取所需源码。使用时需注意：

只有 BB_NO_NETWORK 未设置或设为“0”时才使用此列表。
支持有限的主机名前缀通配匹配。例如以下设置匹配 git.gnu.org、ftp.gnu.org 和 foo.git.gnu.org:
```
BB_ALLOWED_NETWORKS = "*.gnu.org"
```
备注

* 只能位于主机名开头，且必须与其余名称部分分隔。不得在其他位置使用，也不能与名称开头的其他字符组合。例如支持 *.foo.bar，但不支持 *aa.foo.bar。
不在列表中的镜像站会被跳过，并记录调试日志。
尝试访问列表以外的网络会导致失败。

与 PREMIRRORS 配合使用很有用。将允许的主机加入 PREMIRRORS 后，可从该位置获取源码，即使 SRC_URI 指向不允许的主机也不会报错。原因是成功从 PREMIRRORS 获取后，获取器不会再尝试 SRC_URI 中的主机。

BB_BASEHASH_IGNORE_VARS 

见《BitBake 手册》的 BB_BASEHASH_IGNORE_VARS。

BB_CACHEDIR 

见《BitBake 手册》的 BB_CACHEDIR。

BB_CHECK_SSL_CERTS 

见《BitBake 手册》的 BB_CHECK_SSL_CERTS。

BB_CONF_FRAGMENT_DESCRIPTION 

定义 Configuration Fragment 的文字说明。使用方法见《Yocto Project 参考手册》的使用配置片段一节。

BB_CONF_FRAGMENT_SUMMARY 

定义 Configuration Fragment 的单行文字摘要。使用方法见《Yocto Project 参考手册》的使用配置片段一节。

BB_CONSOLELOG 

见《BitBake 手册》的 BB_CONSOLELOG。

BB_CURRENT_MC 

见《BitBake 手册》的 BB_CURRENT_MC。

BB_CURRENTTASK 

见《BitBake 手册》的 BB_CURRENTTASK。

BB_DEFAULT_TASK 

见《BitBake 手册》的 BB_DEFAULT_TASK。

BB_DEFAULT_UMASK 

见《BitBake 手册》的 BB_DEFAULT_UMASK。

BB_DEFER_BBCLASSES 

见《BitBake 手册》的 BB_DEFER_BBCLASSES。

BB_DISKMON_DIRS 

在构建期间监控磁盘空间和可用 inode，并据此控制构建。

默认禁用监控。要启用，在 Build Directory 的 build/conf/local.conf 中添加此变量，格式如下：

BB_DISKMON_DIRS = "action,dir,threshold [...]"

where:

   action is:
      ABORT:     Immediately stop the build when
                 a threshold is broken.
      STOPTASKS: Stop the build after the currently
                 executing tasks have finished when
                 a threshold is broken.
      WARN:      Issue a warning but continue the
                 build when a threshold is broken.
                 Subsequent warnings are issued as
                 defined by the BB_DISKMON_WARNINTERVAL
                 variable, which must be defined in
                 the conf/local.conf file.

   dir is:
      Any directory you choose. You can specify one or
      more directories to monitor by separating the
      groupings with a space.  If two directories are
      on the same device, only the first directory
      is monitored.

   threshold is:
      Either the minimum available disk space,
      the minimum number of free inodes, or
      both.  You must specify at least one.  To
      omit one or the other, simply omit the value.
      Specify the threshold using G, M, K for Gbytes,
      Mbytes, and Kbytes, respectively. If you do
      not specify G, M, or K, Kbytes is assumed by
      default.  Do not use GB, MB, or KB.

示例:

BB_DISKMON_DIRS = "ABORT,${TMPDIR},1G,100K WARN,${SSTATE_DIR},1G,100K"
BB_DISKMON_DIRS = "STOPTASKS,${TMPDIR},1G"
BB_DISKMON_DIRS = "ABORT,${TMPDIR},,100K"

第一个示例还要求在 local.conf 中设置 BB_DISKMON_WARNINTERVAL。当 ${TMPDIR} 可用空间低于 1 Gbyte 或空闲 inode 低于 100 Kbytes 时，构建系统立即停止。由于指定了两个目录，当 ${SSTATE_DIR} 空间低于 1 Gbyte，或空闲 inode 低于 100 Kbytes 时，还会发出警告。后续警告间隔由 BB_DISKMON_WARNINTERVAL 定义。

第二个示例在 TMPDIR 可用空间低于 1 Gbyte 时，等待当前任务全部完成后停止构建，不监控空闲 inode。

最后一个示例在 TMPDIR 空闲 inode 低于 100 Kbytes 时立即停止，不监控该目录的磁盘空间。

BB_DISKMON_WARNINTERVAL 

定义磁盘空间和空闲 inode 的警告间隔。在 Build Directory 的 build/conf/local.conf 中设置。

使用此变量时，必须同时设置 BB_DISKMON_DIRS，并将动作为“WARN”。构建期间，每当空间或空闲 inode 在上一次警告后进一步减少相应间隔，就会再次警告。

使用 WARN 但未设置此变量时，默认间隔如下:

BB_DISKMON_WARNINTERVAL = "50M,5K"

配置文件中的语法如下：

BB_DISKMON_WARNINTERVAL = "disk_space_interval,disk_inode_interval"

where:

   disk_space_interval is:
      An interval of memory expressed in either
      G, M, or K for Gbytes, Mbytes, or Kbytes,
      respectively. You cannot use GB, MB, or KB.

   disk_inode_interval is:
      An interval of free inodes expressed in either
      G, M, or K for Gbytes, Mbytes, or Kbytes,
      respectively. You cannot use GB, MB, or KB.

示例:

BB_DISKMON_DIRS = "WARN,${SSTATE_DIR},1G,100K"
BB_DISKMON_WARNINTERVAL = "50M,5K"

这些设置使 ${SSTATE_DIR} 的可用空间每进一步减少 50 Mbytes，或空闲 inode 每进一步减少 5 Kbytes，就发出后续警告。首次警告阈值为 1 Gbytes 和 100 Kbytes，此后每达到相应间隔再警告。

BB_ENV_PASSTHROUGH 

见《BitBake 手册》的 BB_ENV_PASSTHROUGH。

BB_ENV_PASSTHROUGH_ADDITIONS 

见《BitBake 手册》的 BB_ENV_PASSTHROUGH_ADDITIONS。

BB_FETCH_PREMIRRORONLY 

见《BitBake 手册》的 BB_FETCH_PREMIRRORONLY。

BB_FILENAME 

见《BitBake 手册》的 BB_FILENAME。

BB_GENERATE_MIRROR_TARBALLS 

使版本控制仓库（例如 Git）连同元数据一起生成压缩包，保存到 DL_DIR。

出于性能考虑，默认不创建这些仓库压缩包，设置方式如下:

BB_GENERATE_MIRROR_TARBALLS = "1"

在 configuration file 中设置此变量。

获得包含源码的压缩包后，可删除 DL_DIR 中的 Git 或其他版本控制工作目录以清理空间。

BB_GENERATE_SHALLOW_TARBALLS 

见《BitBake 手册》的 BB_GENERATE_SHALLOW_TARBALLS。

BB_GIT_DEFAULT_DESTSUFFIX 

见《BitBake 手册》的 BB_GIT_DEFAULT_DESTSUFFIX。

在 OpenEmbedded-Core (OE-Core) 中， bitbake.conf 默认将其设为 BP。

BB_GIT_SHALLOW 

见《BitBake 手册》的 BB_GIT_SHALLOW。

BB_GIT_SHALLOW_DEPTH 

见《BitBake 手册》的 BB_GIT_SHALLOW_DEPTH。

BB_HASHCHECK_FUNCTION 

见《BitBake 手册》的 BB_HASHCHECK_FUNCTION。

BB_HASHCONFIG_IGNORE_VARS 

见《BitBake 手册》的 BB_HASHCONFIG_IGNORE_VARS。

BB_HASHSERVE 

见《BitBake 手册》的 BB_HASHSERVE。

BB_HASHSERVE_UPSTREAM 

见《BitBake 手册》的 BB_HASHSERVE_UPSTREAM。

BB_INVALIDCONF 

见《BitBake 手册》的 BB_INVALIDCONF。

BB_LOADFACTOR_MAX 

系统负载阈值，超过后 BitBake 不再启动额外任务。

限制构建资源的方法见《Yocto Project 开发任务手册》的限制主机资源使用量一节。

BB_LOGCONFIG 

见《BitBake 手册》的 BB_LOGCONFIG。

BB_LOGFMT 

见《BitBake 手册》的 BB_LOGFMT。

BB_MULTI_PROVIDER_ALLOWED 

见《BitBake 手册》的 BB_MULTI_PROVIDER_ALLOWED。

BB_NICE_LEVEL 

见《BitBake 手册》的 BB_NICE_LEVEL。

BB_NO_NETWORK 

见《BitBake 手册》的 BB_NO_NETWORK。

BB_NUMBER_PARSE_THREADS 

见《BitBake 手册》的 BB_NUMBER_PARSE_THREADS。

BB_NUMBER_THREADS 

BitBake 同时并行运行任务的最大数量。构建系统自动将其设为主机核心数。例如，支持超线程的双核处理器会使默认值为“4”。

单插槽系统（一个 CPU）通常无需覆盖此变量，即可获得最佳并行度。对于具有多个物理 CPU 的大型系统，可能需要确保该值不超过“20”。

加速构建的更多信息见《Yocto Project 开发任务手册》的 “加快构建”一节。

如果目的是限制 BitBake 任务消耗的资源，仅将此值设得低于 CPU 线程数还不够。每个软件包仍会按照 PARALLEL_MAKE 指定的并行作业数构建和安装。后者默认等于 CPU 线程数，不受 BB_NUMBER_THREADS 影响。

因此，即使设为“1”，若未设置 PARALLEL_MAKE，仍会消耗大部分系统资源。

要通过降低此变量来减轻构建负载，应同时将 PARALLEL_MAKE 设为类似的较低值。

也可以使用更智能的 BB_PRESSURE_MAX_CPU、BB_PRESSURE_MAX_IO 或 BB_PRESSURE_MAX_MEMORY 控制资源。见《Yocto Project 开发任务手册》的限制主机资源使用量。

BB_ORIGENV 

见《BitBake 手册》的 BB_ORIGENV。

BB_PRESERVE_ENV 

见《BitBake 手册》的 BB_PRESERVE_ENV。

BB_PRESSURE_MAX_CPU 

见《BitBake 手册》的 BB_PRESSURE_MAX_CPU。

限制构建资源的方法见《Yocto Project 开发任务手册》的限制主机资源使用量一节。

BB_PRESSURE_MAX_IO 

见《BitBake 手册》的 BB_PRESSURE_MAX_IO。

限制构建资源的方法见《Yocto Project 开发任务手册》的限制主机资源使用量一节。

BB_PRESSURE_MAX_MEMORY 

见《BitBake 手册》的 BB_PRESSURE_MAX_MEMORY。

限制构建资源的方法见《Yocto Project 开发任务手册》的限制主机资源使用量一节。

BB_RUNFMT 

见《BitBake 手册》的 BB_RUNFMT。

BB_RUNTASK 

见《BitBake 手册》的 BB_RUNTASK。

BB_SCHEDULER 

见《BitBake 手册》的 BB_SCHEDULER。

BB_SCHEDULERS 

见《BitBake 手册》的 BB_SCHEDULERS。

BB_SERVER_TIMEOUT 

指定 BitBake 服务器因闲置而卸载前等待的秒数，决定连续调用之间服务器保持驻留的时间。

例如，local.conf 中以下设置要求闲置 20 秒后卸载:

BB_SERVER_TIMEOUT = "20"

若希望服务器永不卸载，将此值设为“-1”。

BB_SETSCENE_DEPVALID 

见《BitBake 手册》的 BB_SETSCENE_DEPVALID。

BB_SIGNATURE_EXCLUDE_FLAGS 

见《BitBake 手册》的 BB_SIGNATURE_EXCLUDE_FLAGS。

BB_SIGNATURE_HANDLER 

见《BitBake 手册》的 BB_SIGNATURE_HANDLER。

BB_SRCREV_POLICY 

见《BitBake 手册》的 BB_SRCREV_POLICY。

BB_STRICT_CHECKSUM 

见《BitBake 手册》的 BB_STRICT_CHECKSUM。

BB_TASK_IONICE_LEVEL 

见《BitBake 手册》的 BB_TASK_IONICE_LEVEL。

BB_TASK_NICE_LEVEL 

见《BitBake 手册》的 BB_TASK_NICE_LEVEL。

BB_TASKHASH 

见《BitBake 手册》的 BB_TASKHASH。

BB_USE_HOME_NPMRC 

见《BitBake 手册》的 BB_USE_HOME_NPMRC。

BB_VERBOSE_LOGS 

见《BitBake 手册》的 BB_VERBOSE_LOGS。

BB_WORKERCONTEXT 

见《BitBake 手册》的 BB_WORKERCONTEXT。

BBCLASSEXTEND 

扩展配方以构建软件变体。常见变体包括 native，例如在构建系统上运行的 quilt-native； cross，例如在构建机器运行、生成目标 MACHINE 二进制文件的 gcc-cross； nativesdk，面向 SDK 机器而非目标机器；以及形式为 multilib:multilib_name 的 multilib 变体。

通常只需添加以下内容，就可用最少代码生成不同变体:

BBCLASSEXTEND =+ "native nativesdk"
BBCLASSEXTEND =+ "multilib:multilib_name"

备注

内部通过重写变量并应用 :class-native 等覆盖生成变体。例如生成 native 版本时，对“foo”的 DEPENDS 会被重写为对“foo-native”的依赖。

即使使用此机制，配方也只解析一次，因此存在一些限制。例如，include 语句在解析时处理，无法根据不同变体包含不同文件。

BBDEBUG 

见《BitBake 手册》的 BBDEBUG。

BBFILE_COLLECTIONS 

列出已配置层的名称，用于查找其他 BBFILE_* 变量。通常各层在自己的 conf/layer.conf 中向此变量追加名称。

BBFILE_PATTERN 

展开后匹配特定层 BBFILES 中的文件。用于 conf/layer.conf，必须追加具体层名作为后缀，例如 BBFILE_PATTERN_emenlow。

BBFILE_PRIORITY 

为各层的配方文件设置优先级。

同一配方出现在多个层时，可以通过此变量控制哪一层优先。它确定的优先关系不受配方版本 PV 影响。例如，某层的配方版本较高，但层优先级较低时，仍然不会优先选用它。

值越大优先级越高，例如 6 高于 5。未指定时，根据层依赖确定，见 LAYERDEPENDS。无依赖且未指定的层，默认优先级为已定义的最低优先级加 1；若尚未定义任何优先级，则为 1。

小技巧

使用 bitbake-layers show-layers 可以列出所有已配置层及其优先级。

BBFILES 

BitBake 构建软件所使用的配方文件列表，以空格分隔。

可使用 Python 的 glob 语法匹配文件，具体语法见该链接。

BBFILES_DYNAMIC 

指定层存在时才启用相关内容，通常称为“动态层”。通过层定义的集合名称标识各层。

一个层希望通过 bbappend 修改其他层，但不想对这些层建立强制依赖时，可用此变量避免在对应 bb 文件不存在时仍启用追加文件。

格式为 collection_name:filename_pattern。

以下示例包含两个集合名称和两个文件模式:

BBFILES_DYNAMIC += " \
   clang-layer:${LAYERDIR}/dynamic-layers/meta-clang/*/*/*.bbappend \
   core:${LAYERDIR}/dynamic-layers/openembedded-core/meta/*/*/*.bbappend \
   "

以下示例展示无效条目导致解析失败时的错误消息：

ERROR: BBFILES_DYNAMIC entries must be of the form <collection name>:<filename pattern>, not:
    /work/my-layer/dynamic-layers/meta-security-isafw/*/*/*.bbappend
    /work/my-layer/dynamic-layers/openembedded-core/meta/*/*/*.bbappend

BBINCLUDED 

见《BitBake 手册》的 BBINCLUDED。

BBINCLUDELOGS 

控制 BitBake 在构建失败时如何显示日志。

BBINCLUDELOGS_LINES 

设置 BBINCLUDELOGS 后，此变量指定报告任务失败时最多输出多少行任务日志。未设置时输出完整日志。

BBLAYERS 

列出构建时启用的层。定义在 Build Directory 的 build/conf/bblayers.conf 中。例如:

BBLAYERS = " \
    /home/scottrif/bitbake-builds/layers/meta \
    /home/scottrif/bitbake-builds/layers/meta-poky \
    /home/scottrif/bitbake-builds/layers/meta-yocto-bsp \
    /home/scottrif/bitbake-builds/layers/meta-mykernel \
    "

此示例启用四个层，其中 meta-mykernel 是用户自定义层。

BBLAYERS_FETCH_DIR 

见《BitBake 手册》的 BBLAYERS_FETCH_DIR。

BBMASK 

阻止 BitBake 处理配方及配方追加文件。

此变量可以“隐藏”bb 和 bbappend 文件。 BitBake 忽略匹配任一表达式的文件，如同完全看不到它们，既不解析也不使用。

提供的值传给 Python 正则表达式编译器，因此遵循 Python re 语法，并与文件完整路径比较。完整语法见 https://docs.python.org/3/library/re.html#regular-expression-syntax。

以下示例通过完整正则表达式，忽略 meta-ti/recipes-misc/ 中的全部配方和追加文件:

BBMASK = "meta-ti/recipes-misc/"

若需屏蔽多个目录或配方，可指定多个正则表达式片段。以下示例同时屏蔽多个目录和单独配方:

BBMASK += "/meta-ti/recipes-misc/ meta-ti/recipes-ti/packagegroup/"
BBMASK += "/meta-oe/recipes-support/"
BBMASK += "/meta-foo/.*/openldap"
BBMASK += "opencv.*\.bbappend"
BBMASK += "lzma"

备注

指定目录名时，应保留末尾斜杠，确保只匹配该目录名称。

BBMULTICONFIG 

使用多配置构建目标时，指定每个额外的独立配置。本地测试可在 build/conf/local.conf 中设置，也可在机器 configuration file 中设置。为每个所用配置文件指定一个 multiconfig 名称，例如以下指定三个配置:

BBMULTICONFIG = "configA configB configC"

配置文件必须位于层配置目录或 Build Directory 的 multiconfig 子目录，例如 build_directory/conf/multiconfig/configA.conf 或 mylayer/conf/multiconfig/configB.conf。

使用方法见《Yocto Project 开发任务手册》的 “通过多配置为多个目标构建镜像”一节。

BBPATH 

见《BitBake 手册》的 BBPATH。

BBSERVER 

在 BitBake 环境中定义时，指向远程 BitBake 服务器。

按以下形式导出到环境:

export BBSERVER=localhost:$port

此变量默认也列于 BB_BASEHASH_IGNORE_VARS，因此不计入校验和和依赖数据。

BBTARGETS 

见《BitBake 手册》的 BBTARGETS。

BINCONFIG 

继承 binconfig-disabled 时，指定要禁用的二进制配置脚本，改用 pkg-config 查询信息。该类会修改脚本使其返回错误，便于查找并替换调用。

多个脚本以空格分隔。以下来自 libpng 配方:

BINCONFIG = "${bindir}/libpng-config ${bindir}/libpng16-config"

BINCONFIG_GLOB 

继承 binconfig 时，指定需编辑的配置脚本通配模式。编辑会修正编译时设置的路径，使脚本安装到系统根目录后，被其他配方构建过程调用时仍使用正确路径。

备注

使用 shell 通配展开，即模式匹配过程中识别并展开通配符，与 fnmatch 和 glob 很相似。

详细机制见 OpenEmbedded-Core (OE-Core) 的 meta/classes-recipe/binconfig.bbclass。类的一般说明见“binconfig”一节。

BITBAKE_UI 

见《BitBake 手册》的 BITBAKE_UI。

BP 

基本配方名称和版本，不含 -native、lib64- 等特殊名称前后缀。组成如下:

${BPN}-${PV}

BPN 

从 PN 移除常见前后缀后的名称，例如 nativesdk-、-cross、 -native，以及 multilib 的 lib64-、lib32-。具体移除的前缀和后缀分别由 MLPREFIX 与 SPECIAL_PKGSUFFIX 指定。

BUGTRACKER 

指定配方所对应上游软件的缺陷跟踪网站 URL。构建系统不使用此变量，它为需要手动报告软件缺陷时提供有用的指引。

BUILD_AR 

指定构建主机使用的架构专用的 归档器 <ar(1)>`命令。默认定义部分取自 :term:`BUILD_PREFIX:

BUILD_AR = "${BUILD_PREFIX}ar"

构建 native 配方时，AR 默认设为此变量值。

不应手动设置此变量，配方也很少直接使用，因为 AR 会根据 native 或目标配方上下文包含适当值。例外是目标配方在构建过程某个阶段需要调用上述构建主机工具。

BUILD_ARCH 

指定构建主机架构，例如 i686。构建系统根据 uname 命令报告的机器名称设置。

BUILD_AS 

指定构建主机使用的架构专用的 汇编器 <as(1)>`命令。默认定义部分取自 :term:`BUILD_PREFIX:

BUILD_AS = "${BUILD_PREFIX}as ${BUILD_AS_ARCH}"

构建 native 配方时，AS 默认设为此变量值。

不应手动设置此变量，配方也很少直接使用，因为 AS 会根据 native 或目标配方上下文包含适当值。例外是目标配方在构建过程某个阶段需要调用上述构建主机工具。

BUILD_AS_ARCH 

指定构建主机的架构专用汇编器标志，默认为空。

BUILD_CC 

指定构建主机使用的架构专用的 C 编译器命令。默认定义部分取自 BUILD_PREFIX 和 BUILD_CC_ARCH:

BUILD_CC = "${CCACHE}${BUILD_PREFIX}gcc ${BUILD_CC_ARCH}"

构建 native 配方时，CC 默认设为此变量值。

不应手动设置此变量，配方也很少直接使用，因为 CC 会根据 native 或目标配方上下文包含适当值。例外是目标配方在构建过程某个阶段需要调用上述构建主机工具。

BUILD_CC_ARCH 

指定构建主机的架构专用 C 编译器标志，默认为空。

BUILD_CCLD 

指定构建主机使用的以 C 编译器作为链接器时使用的 链接器 <ld(1)>`命令。默认定义部分取自 :term:`BUILD_PREFIX 和 BUILD_CC_ARCH:

BUILD_CCLD = "${BUILD_PREFIX}gcc ${BUILD_CC_ARCH}"

构建 native 配方时，CCLD 默认设为此变量值。

不应手动设置此变量，配方也很少直接使用，因为 CCLD 会根据 native 或目标配方上下文包含适当值。例外是目标配方在构建过程某个阶段需要调用上述构建主机工具。

BUILD_CFLAGS 

为构建主机构建时传给C 编译器的标志。在native 上下文中，CFLAGS 默认设为此变量值。

BUILD_CPP 

指定构建主机使用的C 预处理器（用于 C 和 C++ 编译器）命令。默认定义部分取自 BUILD_PREFIX 和 BUILD_CC_ARCH:

BUILD_CPP = "${BUILD_PREFIX}gcc ${BUILD_CC_ARCH} -E"

构建 native 配方时，CPP 默认设为此变量值。

不应手动设置此变量，配方也很少直接使用，因为 CPP 会根据 native 或目标配方上下文包含适当值。例外是目标配方在构建过程某个阶段需要调用上述构建主机工具。

BUILD_CPPFLAGS 

为构建主机构建时传给C 预处理器，即 C 和 C++ 编译器的标志。在native 上下文中，CPPFLAGS 默认设为此变量值。

BUILD_CXX 

指定构建主机使用的架构专用的 C++ 编译器命令。默认定义部分取自 BUILD_PREFIX 和 BUILD_CC_ARCH:

BUILD_CXX = "${CCACHE}${BUILD_PREFIX}g++ ${BUILD_CC_ARCH}"

构建 native 配方时，CXX 默认设为此变量值。

不应手动设置此变量，配方也很少直接使用，因为 CXX 会根据 native 或目标配方上下文包含适当值。例外是目标配方在构建过程某个阶段需要调用上述构建主机工具。

BUILD_CXXFLAGS 

为构建主机构建时传给C++ 编译器的标志。在native 上下文中，CXXFLAGS 默认设为此变量值。

BUILD_FC 

指定构建主机使用的Fortran 编译器命令。默认定义部分取自 BUILD_PREFIX 和 BUILD_CC_ARCH:

BUILD_FC = "${BUILD_PREFIX}gfortran ${BUILD_CC_ARCH}"

构建 native 配方时，FC 默认设为此变量值。

不应手动设置此变量，配方也很少直接使用，因为 FC 会根据 native 或目标配方上下文包含适当值。例外是目标配方在构建过程某个阶段需要调用上述构建主机工具。

BUILD_LD 

指定构建主机使用的链接器命令。默认定义部分取自 BUILD_PREFIX 和 BUILD_LD_ARCH:

BUILD_LD = "${BUILD_PREFIX}ld ${BUILD_LD_ARCH}"

构建 native 配方时，LD 默认设为此变量值。

不应手动设置此变量，配方也很少直接使用，因为 LD 会根据 native 或目标配方上下文包含适当值。例外是目标配方在构建过程某个阶段需要调用上述构建主机工具。

BUILD_LD_ARCH 

指定构建主机的架构专用链接器标志，默认为空。

BUILD_LDFLAGS 

为构建主机构建时传给链接器的标志。在native 上下文中，LDFLAGS 默认设为此变量值。

BUILD_NM 

指定构建主机使用的架构专用的对象文件符号列表工具命令。默认定义部分取自 BUILD_PREFIX:

BUILD_NM = "${BUILD_PREFIX}nm"

构建 native 配方时，NM 默认设为此变量值。

不应手动设置此变量，配方也很少直接使用，因为 NM 会根据 native 或目标配方上下文包含适当值。例外是目标配方在构建过程某个阶段需要调用上述构建主机工具。

BUILD_OBJCOPY 

指定构建主机使用的架构专用的对象文件复制工具命令。默认定义部分取自 BUILD_PREFIX:

BUILD_OBJCOPY = "${BUILD_PREFIX}objcopy"

构建 native 配方时，OBJCOPY 默认设为此变量值。

不应手动设置此变量，配方也很少直接使用，因为 OBJCOPY 会根据 native 或目标配方上下文包含适当值。例外是目标配方在构建过程某个阶段需要调用上述构建主机工具。

BUILD_OBJDUMP 

指定构建主机使用的架构专用的对象文件信息显示工具命令。默认定义部分取自 BUILD_PREFIX:

BUILD_OBJDUMP = "${BUILD_PREFIX}objdump"

构建 native 配方时，OBJDUMP 默认设为此变量值。

不应手动设置此变量，配方也很少直接使用，因为 OBJDUMP 会根据 native 或目标配方上下文包含适当值。例外是目标配方在构建过程某个阶段需要调用上述构建主机工具。

BUILD_OPTIMIZATION 

为构建主机或 SDK 构建时传给 C 编译器的优化标志，通过 BUILD_CFLAGS 和 BUILDSDK_CFLAGS 的默认值传递。

默认值为“-O2 -pipe”。

BUILD_OS 

指定构建主机使用的操作系统，例如“linux”。构建系统取 uname 报告的操作系统名称的第一个词，并转换为小写。

BUILD_PREFIX 

native 配方使用的工具链二进制文件前缀。构建 native 配方时，用此值设置 TARGET_PREFIX。

BUILD_RANLIB 

指定构建主机使用的架构专用的归档索引生成工具命令。默认定义部分取自 BUILD_PREFIX:

BUILD_RANLIB = "${BUILD_PREFIX}ranlib -D"

构建 native 配方时，RANLIB 默认设为此变量值。

不应手动设置此变量，配方也很少直接使用，因为 RANLIB 会根据 native 或目标配方上下文包含适当值。例外是目标配方在构建过程某个阶段需要调用上述构建主机工具。

BUILD_READELF 

指定构建主机使用的架构专用的 ELF 文件信息显示工具命令。默认定义部分取自 BUILD_PREFIX:

BUILD_READELF = "${BUILD_PREFIX}readelf"

构建 native 配方时，READELF 默认设为此变量值。

不应手动设置此变量，配方也很少直接使用，因为 READELF 会根据 native 或目标配方上下文包含适当值。例外是目标配方在构建过程某个阶段需要调用上述构建主机工具。

BUILD_STRIP 

指定构建主机使用的用于剥离构建主机二进制程序调试符号的工具命令。默认定义部分取自 BUILD_PREFIX:

BUILD_STRIP = "${BUILD_PREFIX}strip"

构建 native 配方时，STRIP 默认设为此变量值。

不应手动设置此变量，配方也很少直接使用，因为 STRIP 会根据 native 或目标配方上下文包含适当值。例外是目标配方在构建过程某个阶段需要调用上述构建主机工具。

BUILD_SYS 

为构建主机构建，即构建 native 配方时，指定所用系统，包括架构和操作系统。

构建系统根据 BUILD_ARCH、BUILD_VENDOR 与 BUILD_OS 自动设置，无需手动指定。

BUILD_VENDOR 

为构建主机构建时使用的厂商名，默认是空字符串（""）。

BUILDDIR 

指向 Build Directory。运行 oe-init-build-env 时传入构建目录路径，可间接定义它。未提供路径时，默认为当前目录下的 build。

BUILDHISTORY_COMMIT 

继承 buildhistory 时，指定是否将构建历史输出提交到本地 Git 仓库。设为“1”后，该类自动维护仓库，每次构建为历史输出的各顶层子目录（images、packages、sdk）的变更创建提交。若要跟踪历史变化，应设为“1”。

默认已启用本地 Git 提交:

BUILDHISTORY_COMMIT ?= "1"

BUILDHISTORY_COMMIT_AUTHOR 

继承 buildhistory 时，指定各 Git 提交的作者。需要 BUILDHISTORY_COMMIT 为“1”才生效。

Git 要求值采用“name email@host”形式。邮箱或主机名无效不会产生错误。

默认设置如下:

BUILDHISTORY_COMMIT_AUTHOR ?= "buildhistory <buildhistory@${DISTRO}>"

BUILDHISTORY_DIR 

继承 buildhistory 时，指定保存构建历史信息的目录。工作方式见该类说明。

默认设置如下:

BUILDHISTORY_DIR ?= "${TOPDIR}/buildhistory"

BUILDHISTORY_FEATURES 

继承 buildhistory 时，指定启用的构建历史功能。更多信息见《Yocto Project 开发任务手册》的使用 buildhistory 维护构建输出质量一节。

可用功能以空格分隔：

image: 分析镜像内容，包括已安装软件包列表等。
package: 分析各软件包内容。
sdk: 分析 SDK 内容。
task: 保存共享状态任务的输出文件签名。每个任务保存一个文件，列出各已暂存文件（即任务输出）的 SHA-256 校验和。

默认启用以下功能:

BUILDHISTORY_FEATURES ?= "image package sdk"

BUILDHISTORY_IMAGE_FILES 

继承 buildhistory 时，指定从镜像复制到构建历史目录的文件路径列表，保存于该镜像目录下的 image-files 中，以跟踪各文件内容。默认复制 /etc/passwd 和 /etc/group，便于监控用户和组条目变化。列表可以包含任意文件，无效路径不会报错，因此可指定不一定始终存在的文件。

默认文件路径如下:

BUILDHISTORY_IMAGE_FILES ?= "/etc/passwd /etc/group"

BUILDHISTORY_PATH_PREFIX_STRIP 

继承 buildhistory，且 BUILDHISTORY_FEATURES 启用 task 时，指定从任务签名列表路径开头剥离的公共前缀。历史信息来自多个顶层目录不一致的来源时，这很有用。

默认设置如下:

BUILDHISTORY_PATH_PREFIX_STRIP ?= ""

此时不剥离任何前缀。

BUILDHISTORY_PUSH_REPO 

继承 buildhistory 时，可选指定推送 Git 历史变更的远程仓库。需要 BUILDHISTORY_COMMIT 为“1”才生效。

值可以是 Git 理解的远程仓库地址，也可以是已在本地仓库中通过 git remote 手动配置的远程名称。

默认设置如下:

BUILDHISTORY_PUSH_REPO ?= ""

BUILDNAME 

见《BitBake 手册》的 BUILDNAME。

BUILDSDK_CFLAGS 

为SDK构建时传给C 编译器的标志。在nativesdk- 上下文中，CFLAGS 默认设为此变量值。

BUILDSDK_CPPFLAGS 

为SDK构建时传给C 预处理器，即 C 和 C++ 编译器的标志。在nativesdk- 上下文中，CPPFLAGS 默认设为此变量值。

BUILDSDK_CXXFLAGS 

为SDK构建时传给C++ 编译器的标志。在nativesdk- 上下文中，CXXFLAGS 默认设为此变量值。

BUILDSDK_LDFLAGS 

为SDK构建时传给链接器的标志。在nativesdk- 上下文中，LDFLAGS 默认设为此变量值。

BUILDSTATS_BASE 

使用并启用 buildstats 时，指向保存构建统计的目录。默认是 ${TMPDIR}/buildstats/。

BUSYBOX_SPLIT_SUID 

针对 BusyBox 配方，指定是否将输出可执行文件分为两部分：一部分提供需要 setuid root 的功能，另一部分提供不需要该权限的其他功能。

默认为“1”，即拆分输出。设为“0”可得到单个可执行文件。

CACHE 

指定 BitBake 保存 Metadata 缓存的目录，避免每次启动都重新解析。

CARGO_INSTALL_LIBRARIES 

继承 cargo 时，配方可将此变量设为非空值，启用安装 ${B}/target/${CARGO_TARGET_SUBDIR} 中构建的库，即以 .so 或 .rlib 结尾的文件。默认未定义，不安装库，以保持与 cargo install 命令相同的行为。

CARGO_PROFILE 

继承 cargo 时，选择构建所用 profile，即 --profile 选项。默认根据 DEBUG_BUILD 自动设置。

CC 

运行 C 编译器所需的最小命令及参数。

CCACHE_DISABLE 

继承 ccache 时，配方可将其设为“1”以禁用 Ccache。已知配方不支持 Ccache 时可使用。

CCACHE_NATIVE_RECIPES_ALLOWED 

在 configuration file 中列出允许通过 ccache 优化的 native 配方。

CCACHE_TOP_DIR 

继承 ccache 时，指定 Ccache 保存缓存文件的位置。此目录可以跨构建共享。

CCLD 

使用 C 编译器作为链接器时，运行链接器所需的最小命令及参数。

CFLAGS 

指定传给C 编译器的标志。导出为环境变量，因此编译期间对所构建的软件可见。

根据构建对象，默认初始化为：

为目标构建时使用 TARGET_CFLAGS。
为构建主机构建，即 -native 时使用 BUILD_CFLAGS。
为 SDK 构建，即 nativesdk- 时使用 BUILDSDK_CFLAGS。

CHECKLAYER_REQUIRED_TESTS 

列出层获得 Yocto Project Compatible 状态所必须启用的质量检查。此变量应视为只读，任何修改都应获得技术指导委员会（TSC）批准。

更多信息见《Yocto Project 开发手册》的确保层与 Yocto Project 兼容一节。

CLASSOVERRIDE 

内部变量，指定当前应应用的特殊类覆盖，例如 class-target、class-native。使用它的 native、nativesdk 等类会将其设为适当值。

备注

默认值 class-target 来自 bitbake.conf。

例如，以下覆盖仅在为目标构建时安装额外文件:

do_install:append:class-target() {
    install my-extra-file ${D}${sysconfdir}
}

以下示例使 FOO 在为构建主机构建时为 native，其他情况为 other:

FOO:class-native = "native"
FOO = "other"

其底层机制只是将此变量纳入 OVERRIDES 的默认值。

CLEANBROKEN 

配方中设为“1”表示软件的 make clean 无法正常工作。构建系统因此不会在 do_configure 中执行默认的 make clean 操作。

COMBINED_FEATURES 

列出同时在 MACHINE_FEATURES 和 DISTRO_FEATURES 启用的硬件功能。这些功能适合由机器配置与发行版配置共同控制。例如 bluetooth 需要硬件支持，但发行版也应能选择不启用，因为硬件即使支持蓝牙，实际系统也可能从不使用。

COMMERCIAL_AUDIO_PLUGINS 

专用于 GStreamer 配方，允许构建 ugly 和 bad 音频插件。

用法详情见其他商业许可相关变量。

COMMERCIAL_VIDEO_PLUGINS 

专用于 GStreamer 配方，允许构建 ugly 和 bad 视频插件。

用法详情见其他商业许可相关变量。

COMMON_LICENSE_DIR 

指向 OpenEmbedded-Core (OE-Core) 的 meta/files/common-licenses，即通用许可证文件所在位置。

COMPATIBLE_HOST 

匹配配方兼容系统的正则表达式：native 配方对应主机，其他配方对应目标。表达式与 HOST_SYS 匹配，可阻止在不兼容系统类别上构建配方，这对内核尤其有用。构建系统跳过不兼容配方的解析，也能加快解析速度。

COMPATIBLE_MACHINE 

匹配配方兼容的一个或多个目标机器的正则表达式，与 MACHINEOVERRIDES 匹配。可阻止在不兼容机器上构建配方，尤其适合内核。跳过不兼容配方的解析也能加快解析速度。

例如，要使配方只适用于 aarch64 和 mips64，可设置:

COMPATIBLE_MACHINE = "^$"
COMPATIBLE_MACHINE:arch64 = "^(aarch64)$"
COMPATIBLE_MACHINE:mips64 = "^(mips64)$"

第一行匹配 MACHINEOVERRIDES 含空字符串的机器，因此不会匹配任何机器。第二行匹配含有精确等于 aarch64 的覆盖项的机器。第三行匹配含有精确等于 mips64 的覆盖项的机器。

以下设置可达到相同效果:

COMPATIBLE_MACHINE = "^(aarch64|mips64)$"

备注

native 配方设置此变量后总会被跳过。所有 native 配方都必须完全独立于目标，不应依赖 MACHINE。

COMPLEMENTARY_GLOB 

定义安装配套软件包时使用的通配模式，为镜像中显式或隐式安装的全部软件包选择相应配套包。

使用 Unix 文件名模式匹配（fnmatch），与 Unix 风格的路径模式展开（glob）相似。

结果列表关联一个可添加到 IMAGE_FEATURES 的功能项。例如加入 dev-pkgs 后，会为镜像中的每个包安装对应 -dev 包，其中包含头文件和其他开发文件。

添加新功能项时，用变量标志指定功能名，以变量值指定通配模式。例如:

COMPLEMENTARY_GLOB[dev-pkgs] = '*-dev'

备注

安装配套软件包时，始终忽略 RRECOMMENDS 设置的推荐关系。

COMPONENTS_DIR 

保存各配方提供的系统根目录组件。构建系统为其他配方创建专用系统根目录时使用此位置。

默认是 ${STAGING_DIR}-components，即 ${TMPDIR}/sysroots-components。

CONF_VERSION 

跟踪本地配置文件 build/conf/local.conf 的版本。每次 build/conf/ 兼容性变化时递增。

CONFFILES 

标识软件包中可编辑或可配置的文件。通过软件包管理系统（PMS）更新目标软件时，安装后用户修改、希望保留的配置文件可能被覆盖。可用此变量列出更新时不希望 PMS 覆盖的文件。

使用软件包名称覆盖标识输出包，再提供空格分隔的文件列表。例如:

CONFFILES:${PN} += "${sysconfdir}/file1 \
    ${sysconfdir}/file2 ${sysconfdir}/file3"

此变量中的文件必须是 FILES 的子集。因为它只是将已打包文件标记为不应覆盖，所以这些文件必须已通过 FILES 纳入软件包。

备注

指定路径时，建议使用适当的路径变量，例如用 ${sysconfdir} 代替 /etc，用 ${bindir} 代替 /usr/bin。变量列表见 OpenEmbedded-Core (OE-Core) 的 meta/conf/bitbake.conf 文件开头。

CONFIG_INITRAMFS_SOURCE 

标识初始 RAM 文件系统（Initramfs）的源文件。构建系统将这个内核 Kconfig 变量作为环境变量接收和使用，默认值为空字符串。

可以指定单个以 .cpio 结尾的归档，或用于构建 Initramfs 的空格分隔目录和文件列表。 cpio 归档应包含用作 Initramfs 的文件系统；目录应包含要纳入镜像的文件系统布局；文件应按内核树 usr/gen_init_cpio 程序所述格式包含条目。

指定多个目录和文件时，镜像包含它们的汇总内容。

创建方法见《Yocto Project 开发任务手册》的 “构建初始 RAM 文件系统（Initramfs）镜像”一节。

CONFIG_SITE 

包含与当前构建相关的 autoconf 测试结果的文件列表。 Autotools 工具运行 configure 时使用此变量。

CONFIGURE_FLAGS 

GNU configure 的最小参数集合。

CONFIGURE_SCRIPT 

使用 autotools* 时，保存 Autotools 的 configure 脚本位置。默认定义为:

CONFIGURE_SCRIPT ?= "${AUTOTOOLS_SCRIPT_PATH}/configure"

其中 AUTOTOOLS_SCRIPT_PATH 为 Autotools 脚本位置，默认是 S。

CONFLICT_COMBINED_FEATURES 

继承 features_check 时，指定构建此配方会产生冲突的组合功能，相关含义见 COMBINED_FEATURES。如果列表中的任一功能也出现在当前配置的 COMBINED_FEATURES 中，配方会被跳过；构建系统若尝试构建它，则会报错。

CONFLICT_DISTRO_FEATURES 

继承 features_check 时，指定构建此配方会产生冲突的发行版功能，相关含义见 DISTRO_FEATURES。如果列表中的任一功能也出现在当前配置的 DISTRO_FEATURES 中，配方会被跳过；构建系统若尝试构建它，则会报错。

CONFLICT_IMAGE_FEATURES 

继承 features_check 时，指定构建此配方会产生冲突的镜像功能，相关含义见 IMAGE_FEATURES。如果列表中的任一功能也出现在当前配置的 IMAGE_FEATURES 中，配方会被跳过；构建系统若尝试构建它，则会报错。

CONFLICT_MACHINE_FEATURES 

继承 features_check 时，指定构建此配方会产生冲突的机器功能，相关含义见 MACHINE_FEATURES。如果列表中的任一功能也出现在当前配置的 MACHINE_FEATURES 中，配方会被跳过；构建系统若尝试构建它，则会报错。

CONFLICT_TUNE_FEATURES 

继承 features_check 时，指定构建此配方会产生冲突的调优功能，相关含义见 TUNE_FEATURES。如果列表中的任一功能也出现在当前配置的 TUNE_FEATURES 中，配方会被跳过；构建系统若尝试构建它，则会报错。

CONVERSION_CMD 

保存镜像转换命令，可将镜像转换为不同对象，例如：

镜像的压缩版本。
镜像的校验和。

image_types 中的示例为:

CONVERSION_CMD:lzo = "lzop -9 ${IMAGE_NAME}${IMAGE_NAME_SUFFIX}.${type}"

COPY_LIC_DIRS 

与 COPY_LIC_MANIFEST 一同设为“1”时，构建系统在构建期间将各软件包许可证文件复制到镜像的 /usr/share/common-licenses 目录中。

备注

此机制无法为镜像中新安装的软件包添加许可证，因而可能更适合无法升级的只读文件系统。更多信息见 LICENSE_CREATE_PACKAGE，以及《Yocto Project 开发任务手册》的 “提供许可证文本”一节。

COPY_LIC_MANIFEST 

设为“1”时，在构建期间将镜像许可证清单复制到镜像内的 /usr/share/common-licenses/license.manifest。

备注

此机制无法为镜像中新安装的软件包添加许可证，因而可能更适合无法升级的只读文件系统。更多信息见 LICENSE_CREATE_PACKAGE，以及《Yocto Project 开发任务手册》的 “提供许可证文本”一节。

COPYLEFT_LICENSE_EXCLUDE 

以空格分隔的许可证排除列表，用于 archiver 的源码归档。如果配方 LICENSE 中的许可证列于此处，则不归档其源码。

备注

此变量优先于 COPYLEFT_LICENSE_INCLUDE。

默认值为“CLOSED Proprietary”，由 archiver 继承的 copyleft_filter 设置。

COPYLEFT_LICENSE_INCLUDE 

以空格分隔的许可证包含列表，用于 archiver 的源码归档。如果配方 LICENSE 中的许可证列于此处，则归档其源码。

默认值由 archiver 继承的 copyleft_filter 设置，包含“GPL*”“LGPL*”和“AGPL*”。

COPYLEFT_PN_EXCLUDE 

指定 archiver 归档源码时应排除的配方列表。覆盖 COPYLEFT_LICENSE_INCLUDE 和 COPYLEFT_LICENSE_EXCLUDE 所决定的许可证包含与排除规则。

默认是空字符串，表示不按名称显式排除任何配方，由 archiver 继承的 copyleft_filter 设置。

COPYLEFT_PN_INCLUDE 

指定 archiver 归档源码时应包含的配方列表。覆盖 COPYLEFT_LICENSE_INCLUDE 和 COPYLEFT_LICENSE_EXCLUDE 所决定的许可证包含与排除规则。

默认是空字符串，表示不按名称显式包含任何配方，由 archiver 继承的 copyleft_filter 设置。

COPYLEFT_RECIPE_TYPES 

以空格分隔的配方类型列表，指定 archiver 归档哪些类型的源码。可用类型为 target、native、 nativesdk、cross、 crosssdk 和 cross-canadian。

默认值为“target*”，由 archiver 继承的 copyleft_filter 设置。

CORE_IMAGE_EXTRA_INSTALL 

指定额外添加到镜像的软件包列表。应在 Build Directory 的 build/conf/local.conf 中设置；若发行版始终需要这些包，也可在发行版 configuration file 中设置。

它替代了不再支持的 POKY_EXTRA_INSTALL。

COREBASE 

指定 OpenEmbedded-Core (OE-Core) 元数据层 meta 的父目录。

COREBASE_FILES 

列出除 build/conf/bblayers.conf 中各层之外，还应从 COREBASE 复制的文件，使构建系统元数据可纳入可扩展 SDK。

必须显式列出，因为 COREBASE 通常还包含构建目录和其他不应复制的文件。使用此列表确保只复制实际需要的内容。

CPP 

运行 C 预处理器所需的最小命令及参数。

CPPFLAGS 

指定传给C 预处理器，即 C 和 C++ 编译器的标志。导出为环境变量，因此编译期间对所构建的软件可见。

根据构建对象，默认初始化为：

为目标构建时使用 TARGET_CPPFLAGS。
为构建主机构建，即 -native 时使用 BUILD_CPPFLAGS。
为 SDK 构建，即 nativesdk- 时使用 BUILDSDK_CPPFLAGS。

CROSS_COMPILE 

目标工具的工具链二进制文件前缀，与 TARGET_PREFIX 相同。

备注

构建系统只在特定上下文设置此变量，例如构建内核及内核模块配方时。

CVE_CHECK_IGNORE 

此变量已弃用，应改用 CVE_STATUS。

CVE_CHECK_MANIFEST_JSON 

继承 vex 时，指定 JSON 格式 CVE 清单的路径。

CVE_CHECK_SKIP_RECIPE 

继承 vex 时，列出要忽略 CVE（公共漏洞和暴露）的软件包名称，即 PN。

CVE_CHECK_STATUSMAP 

将 CVE_STATUS 的各种原因映射到 Patched、Unpatched、Ignored 状态。详情见 meta/conf/cve-check-map.conf:

CVE_CHECK_STATUSMAP[cpe-incorrect] = "Ignored"

CVE_CHECK_VEX_JUSTIFICATION 

将 CVE_STATUS 原因（例如 not-applicable-platform）映射到 vex 理由。设置方式如下:

CVE_CHECK_VEX_JUSTIFICATION[not-applicable-config] = "vulnerableCodeNotPresent"

CVE_PRODUCT 

在配方中定义与上游 NIST CVE 数据库匹配时使用的产品名称。

默认是 ${BPN}；继承 pypi 的配方例外，它根据 PYPI_PACKAGE 设置。若默认值与数据库名称不匹配，或匹配到多个条目，就需要修改。

以下来自 Berkeley DB 配方:

CVE_PRODUCT = "oracle_berkeley_db berkeley_db"

有时产品名不够明确，例如 tar 同时匹配 GNU tar 和 Node.js 的 node-tar 扩展。为避免此问题，可加厂商名前缀，语法如下:

CVE_PRODUCT = "vendor:package"

从 Wrynose（6.0）起，特殊字符不得转义。例如 webkitgtk 配方应使用 webkitgtk+，不再写作 webkitgtk\+。

CVE_STATUS 

指定已修复或应忽略的 CVE ID。以下来自 Python3 配方:

CVE_STATUS[CVE-2020-15523] = "not-applicable-platform: Issue only applies on Windows"

格式为“reason: description”，说明部分可选。原因通过 CVE_CHECK_STATUSMAP 映射为最终 CVE 状态。详情见修复配方中的漏洞。

CVE_STATUS_GROUPS 

多个 CVE 具有相同状态和原因时，可用此变量简化，避免重复多行类似的 CVE_STATUS:

CVE_STATUS_GROUPS = "CVE_STATUS_WIN CVE_STATUS_PATCHED"

CVE_STATUS_WIN = "CVE-1234-0001 CVE-1234-0002"
CVE_STATUS_WIN[status] = "not-applicable-platform: Issue only applies on Windows"
CVE_STATUS_PATCHED = "CVE-1234-0003 CVE-1234-0004"
CVE_STATUS_PATCHED[status] = "fixed-version: Fixed externally"

CVE_VERSION 

使用 vex 或 create-spdx 时，定义配方与 NIST CVE 数据库匹配所使用的版本。

默认是 ${PV}。若配方采用自定义版本号，不能对应上游发布版本及数据库版本，可通过此变量为上述类指定版本。例如:

CVE_VERSION = "2.39"

CXX 

运行 C++ 编译器所需的最小命令及参数。

CXXFLAGS 

指定传给C++ 编译器的标志。导出为环境变量，因此编译期间对所构建的软件可见。

根据构建对象，默认初始化为：

为目标构建时使用 TARGET_CXXFLAGS。
为构建主机构建，即 -native 时使用 BUILD_CXXFLAGS。
为 SDK 构建，即 nativesdk- 时使用 BUILDSDK_CXXFLAGS。

D 

目标安装目录，即 do_install 将组件安装到 Build Directory 中的位置，默认为:

${WORKDIR}/image

备注

读取或写入此目录的任务应在 fakeroot 下运行。

DATE 

构建开始日期，采用年月日（YMD）格式，例如 2015 年 2 月 9 日为“20150209”。

DATETIME 

当前构建开始的日期和时间，格式适合用作时间戳。

DEBIAN_NOAUTONAME 

默认继承 debian 时，指定某个软件包不按 Debian 库包规则重命名。设置时必须使用软件包名称覆盖。以下来自 fontconfig 配方:

DEBIAN_NOAUTONAME:fontconfig-utils = "1"

DEBIANNAME 

默认继承 debian 时，可覆盖单个软件包的库名称。这种需求较少见。必须使用软件包名称覆盖，以下来自 dbus 配方:

DEBIANNAME:${PN} = "dbus-1"

DEBUG_BUILD 

指定构建带调试信息的软件包，影响 SELECTED_OPTIMIZATION 的值。

DEBUG_OPTIMIZATION 

为调试编译系统时，经 TARGET_CFLAGS 和 CFLAGS 传入的选项。默认为“-Og ${DEBUG_LEVELFLAG}”。

DEBUG_PREFIX_MAP 

设置 -fdebug-prefix-map、-fmacro-prefix-map、-ffile-prefix-map 等 C 编译器选项，将二进制调试节中的构建时路径替换为安装时路径。这样编译输出与位置无关，但需要额外命令告知调试器源码位置。

Yocto Project 用它保证可重现构建，即使源码使用 __FILE__ 或 assert() 宏也如此。详情见 reproducible-builds.org。

此变量由 meta/conf/bitbake.conf 设置，不用于用户配置。

DEFAULT_PREFERENCE 

为配方选择优先级提供较弱的倾向。

最常见用法是在软件开发版本的配方中设为“-1”，使未通过 PREFERRED_VERSION 显式选择开发版时，默认构建稳定版。

备注

此倾向较弱。若包含同一配方不同版本的两个层具有不同 BBFILE_PRIORITY，层优先级会覆盖它。

DEFAULT_TIMEZONE 

指定镜像时区，使 tzdata 相应配置 ${sysconfdir}/localtime。有效值为 /usr/share/zoneinfo 中的文件，例如 CET 或 Asia/Baku。

DEFAULTTUNE 

构建系统默认使用的 CPU 和 ABI 调优配置，参与定义 TUNE_FEATURES。

默认由 MACHINE 隐式或显式设置，但可使用 AVAILTUNES 中的可用配置覆盖。

DEPENDS 

列出配方的构建时依赖，即构建时需要其头文件、共享库等内容的其他配方。

例如，foo 配方包含以下赋值:

DEPENDS = "bar"

效果是 foo 的 do_configure 运行前，bar 安装的全部文件已经位于 STAGING_DIR* 指向的相应暂存系统根目录。该机制通过 base 的 [deptask] 声明实现，使 configure 依赖 DEPENDS 各配方的 do_populate_sysroot。

备注

通常无需显式引用 STAGING_DIR_HOST 等变量。标准类和构建变量已经配置为自动使用正确的暂存系统根目录。

也可用于添加构建期间在构建机器上运行的工具。例如配方需要由 codegen 配方构建的代码生成器，可设置:

DEPENDS = "codegen-native"

更多信息见 native 和 EXTRANATIVEPATH。

备注

DEPENDS 是配方名称列表；更准确地说，是通常与配方名相同的 PROVIDES 名称列表。不能填写 foo-dev 这类软件包名称，应使用 foo，这会将 foo 生成的所有包（包括 foo-dev）的文件放入系统根目录。
在 DEPENDS 中列入另一个配方，本身不会在双方生成的软件包间建立运行时依赖。但运行时依赖通常自动添加，因此多数配方仅设置 DEPENDS 即可。详情见《Yocto Project 概览与概念手册》的 “自动添加运行时依赖”一节。
即使安装预编译组件的配方，也常常需要 DEPENDS。例如预编译 libfoo 链接 libbar，其他软件要链接 libfoo，系统根目录必须同时包含两者。若安装 libfoo 的配方未依赖安装 libbar 的配方，其他配方链接 libfoo 可能失败。

运行时依赖见 RDEPENDS。任务和依赖的更多说明见《BitBake 用户手册》的 “Tasks”与 “Dependencies”两节。

DEPLOY_DIR 

指向存放镜像、软件包、SDK 及其他已可在构建系统外使用的输出文件的总目录。默认位于 Build Directory 内的 ${TMPDIR}/deploy。

构建目录结构见“构建目录 --- build/”一节。 deploy 内容详情见《Yocto Project 概览与概念手册》的 “镜像”、 “软件包源”和 “应用开发 SDK”各节。

警告

不要与名称相似的 DEPLOYDIR 混淆。

DEPLOY_DIR_DEB 

指向存放已可在构建系统外使用的 Debian 软件包的位置。仅当 PACKAGE_CLASSES 包含 package_deb 时适用。

BitBake 配置默认将其定义为 DEPLOY_DIR 的子目录:

DEPLOY_DIR_DEB = "${DEPLOY_DIR}/deb"

package_deb 使用它确保 do_package_write_deb 将包写入正确目录。打包机制见《Yocto Project 概览与概念手册》的 “软件包源”一节。

DEPLOY_DIR_IMAGE 

指向存放可部署到目标机器的镜像及关联输出的位置。目录包含 ${MACHINE}，因此是机器专用的。默认位于 Build Directory 内的 ${DEPLOY_DIR}/images/${MACHINE}/。

配方部署文件时不得直接写入此目录；它只适合读取依赖已经部署的文件。应由 deploy 从 DEPLOYDIR 填充，或由 image 从 IMGDEPLOYDIR 填充。

构建目录结构见“构建目录 --- build/”一节。内容详情见《Yocto Project 概览与概念手册》的 “镜像”与 “应用开发 SDK”两节。

DEPLOY_DIR_IPK 

指向存放已可在构建系统外使用的 IPK 软件包的位置。仅当 PACKAGE_CLASSES 包含 package_ipk 时适用。

BitBake 配置默认将其定义为 DEPLOY_DIR 的子目录:

DEPLOY_DIR_IPK = "${DEPLOY_DIR}/ipk"

package_ipk 使用它确保 do_package_write_ipk 将包写入正确目录。打包机制见《Yocto Project 概览与概念手册》的 “软件包源”一节。

DEPLOY_DIR_RPM 

指向存放已可在构建系统外使用的 RPM 软件包的位置。仅当 PACKAGE_CLASSES 包含 package_rpm 时适用。

BitBake 配置默认将其定义为 DEPLOY_DIR 的子目录:

DEPLOY_DIR_RPM = "${DEPLOY_DIR}/rpm"

package_rpm 使用它确保 do_package_write_rpm 将包写入正确目录。打包机制见《Yocto Project 概览与概念手册》的 “软件包源”一节。

DEPLOYDIR 

继承 deploy 时，指向待部署文件的临时工作区。该类定义如下:

DEPLOYDIR = "${WORKDIR}/deploy-${PN}"

继承它的配方应将待部署文件复制到这里，随后由该类复制到 DEPLOY_DIR_IMAGE。

警告

不要与名称相似的 DEPLOY_DIR 混淆。

DESCRIPTION 

软件包管理器使用的软件包说明。未设置时取 SUMMARY 的值。

DEV_PKG_DEPENDENCY 

便于配方禁用或调整 ${PN}-dev 对主软件包 ${PN} 的运行时推荐关系（RRECOMMENDS）。

DISABLE_STATIC 

默认禁用静态链接以节省空间，因为嵌入式系统通常不使用静态库。默认值为“ --disable-static”，需要启用时可设为空字符串。部分配方会独立调整，meta/conf/distro/include/no-static-libs.inc 也会为多个配方禁用静态链接。某些软件或构建工具（例如 CMake）具有显式静态链接开关，此时不使用该变量。

DISTRO 

发行版短名称，长名称见 DISTRO_NAME。

可通过两种方式定义：

使用 distro/ 片段：
```
$ bitbake-config-build enable-fragment distro/<DISTRO>
```
将命令中的 <DISTRO> 替换为发行版名称。
在 Build Directory 的 build/conf/local.conf 中设置。

此值对应名称主体相同、扩展名为 .conf 的发行版配置文件。例如 Poky 的配置是 meta-poky 的 meta-poky/conf/distro/poky.conf。其中设置如下:

DISTRO = "poky"

发行版配置文件位于对应 Metadata 的 conf/distro 目录。 DISTRO 不能包含空格，通常全部小写。

备注

值为空时，使用 OpenEmbedded-Core (OE-Core) 的 meta/conf/distro/defaultsetup.conf 中指定的默认配置。

DISTRO_CODENAME 

指定正在构建的发行版代号。

DISTRO_EXTRA_RDEPENDS 

指定要添加到所有镜像的发行版专用软件包列表。通过 packagegroup-base 生效，因此实际只适用于包含它的较完整镜像。可用此变量将发行版策略与通用镜像分离。与其他发行版变量一样，应在发行版 .conf 中设置。

DISTRO_EXTRA_RRECOMMENDS 

指定若存在就添加到所有镜像的发行版专用软件包列表。软件包可能不存在或为空，例如内核模块。这些包自动安装，但可以移除。

DISTRO_FEATURES 

发行版希望支持的各项软件功能，在发行版配置文件中定义。

多数情况下，功能是否存在会转换为可选支持该功能的配方在 do_configure 中传给 configure 的相应选项。例如包含 x11 时，所有为目标构建、可选支持 X11 的软件都会启用 X11。

备注

只设置此变量并不会自动启用软件包功能，还需通过让 PACKAGECONFIG 跟随 DISTRO_FEATURES 等机制实现。

Bluetooth 和 NFS 也是例子。 Yocto Project 附带的更完整功能列表见“发行版功能”一节。

DISTRO_FEATURES_DEFAULTS 

以空格分隔的默认发行版功能列表，由 OpenEmbedded Build System 提供。不应直接修改，应通过 DISTRO_FEATURES_OPTED_OUT 阻止默认功能启用。

更多信息见默认功能。

DISTRO_FEATURES_FILTER_NATIVE 

列出目标 DISTRO_FEATURES 中若存在，则在构建 native 配方时也应包含的功能。与 DISTRO_FEATURES_NATIVE 筛选的功能共同使用。

DISTRO_FEATURES_FILTER_NATIVESDK 

列出目标 DISTRO_FEATURES 中若存在，则在构建 nativesdk 配方时也应包含的功能。与 DISTRO_FEATURES_NATIVESDK 筛选的功能共同使用。

DISTRO_FEATURES_NATIVE 

列出构建 native 配方时应纳入 DISTRO_FEATURES 的功能。与 DISTRO_FEATURES_FILTER_NATIVE 筛选的功能共同使用。

DISTRO_FEATURES_NATIVESDK 

列出构建 nativesdk 配方时应纳入 DISTRO_FEATURES 的功能。与 DISTRO_FEATURES_FILTER_NATIVESDK 筛选的功能共同使用。

DISTRO_FEATURES_OPTED_OUT 

以空格分隔的退出列表，排除 DISTRO_FEATURES_DEFAULTS 提供的功能。

也可设为 *，退出全部默认功能:

DISTRO_FEATURES_OPTED_OUT = "*"

更多信息见默认功能。

DISTRO_NAME 

发行版长名称，短名称见 DISTRO。

此变量对应名称主体与变量参数相同、扩展名为 .conf 的发行版配置文件。例如 Poky 的配置是 meta-poky 的 meta-poky/conf/distro/poky.conf，其中设置如下:

DISTRO_NAME = "Poky (Yocto Project Reference Distro)"

发行版配置文件位于对应 Metadata 的 conf/distro 目录。

备注

值为空时，使用 OpenEmbedded-Core (OE-Core) 的 meta/conf/distro/defaultsetup.conf 中指定的默认配置。

DISTRO_VERSION 

发行版版本。

DISTROOVERRIDES 

当前发行版专用的冒号分隔覆盖列表，默认包含 DISTRO。可扩展它，为发行版添加额外覆盖。其机制只是将它纳入 OVERRIDES 默认值。

以下来自 meta-poky/conf/distro/poky-tiny.conf:

DISTROOVERRIDES = "poky:poky-tiny"

DL_DIR 

构建过程集中保存下载内容的目录。默认除 Git 仓库外，下载内容均适合用于镜像。如需 Git 仓库压缩包，应设置 BB_GENERATE_MIRROR_TARBALLS。

可在 build/conf/local.conf 中定义此目录。目录自动维护，通常无需手动操作。默认是 Build Directory 的 downloads:

#DL_DIR ?= "${TOPDIR}/downloads"

若要指定其他位置，只需取消该行注释并提供目录。

首次构建会从多个上游项目下载许多源码压缩包，网络较慢时可能耗时较长。全部压缩包保存在这里，后续构建首先在此查找源码。

备注

清理并重新构建时可保留此目录，加快后续源码获取。

同一开发机器上的多个构建可安全共享此目录。防火墙或代理后的源码获取方法见“常见问题”中的相应问题，以及在网络代理后工作 Wiki 页面。

DOC_COMPRESS 

继承 compress_doc 时，设置手册页和 info 页的压缩策略。默认 gz（gzip），也可使用 xz 或 bz2。

策略及用法见 meta/classes-recipe/compress_doc.bbclass 的注释。

DT_FILES 

继承 devicetree 的配方要编译的设备树源码列表，以空格分隔，路径相对于 DT_FILES_PATH。

为方便使用，.dts 和 .dtb 扩展名都可接受。默认空字符串表示构建该目录内的全部设备树源码。

DT_FILES_PATH 

继承 devicetree 编译树外设备树源码时，指定包含待构建 dts 文件的目录，默认是 S。

DT_PADDING_SIZE 

继承 devicetree 时，指定追加到设备树二进制文件的填充大小，通常作为启动时添加额外属性的预留空间。

EFI_ARCH 

EFI 标准中的 CPU 架构名称，设置于 meta/conf/image-uefi.conf。

EFI_PROVIDER 

构建可启动镜像，即 IMAGE_FSTYPES 包含 hddimg、iso 或 wic.vmdk 时，指定使用的 EFI 引导加载程序。默认 grub-efi，也可使用 systemd-boot。

更多信息见 systemd-boot 和 image-live。

EFI_UKI_DIR 

UKI 镜像在 EFI 系统分区中的主要位置。

EFI_UKI_PATH 

UKI 镜像在根文件系统中的路径。

ENABLE_BINARY_LOCALE_GENERATION 

控制构建期间生成哪些 glibc 区域设置。目标内存为 64 Mbytes 或更少时尤其有用。

ERR_REPORT_DIR 

与 report-error 一起使用时，指定错误报告工具生成的调试文件的保存位置。该工具可将构建错误提交到中央数据库。默认是 ${LOG_DIR}/error-report。

可在 configuration file 中按如下方式设置所需位置:

ERR_REPORT_DIR = "path"

ERROR_QA 

指定失败时应报告为错误的质量检查。在发行版配置文件中设置，可控检查列表见“insane”一节。

ESDK_CLASS_INHERIT_DISABLE 

列出可扩展 SDK 配置中要从全局 INHERIT 移除的类。 populate-sdk-ext 设置默认值:

ESDK_CLASS_INHERIT_DISABLE ?= "buildhistory"

某些类不适用于可扩展 SDK，可用此变量禁用。

定制配置的更多信息见《Yocto Project 应用开发与可扩展软件开发工具包（eSDK）手册》的 “配置可扩展 SDK”一节。

ESDK_LOCALCONF_ALLOW 

列出允许从构建系统配置传递到可扩展 SDK 配置的变量。由 populate-sdk-ext 设置，默认列表为空。

此列表覆盖 ESDK_LOCALCONF_REMOVE，也覆盖因变量值以 / 开头而自动加入排除列表的变量。以 / 开头通常表示路径，在 SDK 安装系统上可能无效。

定制配置的更多信息见《Yocto Project 应用开发与可扩展软件开发工具包（eSDK）手册》的 “配置可扩展 SDK”一节。

ESDK_LOCALCONF_REMOVE 

列出禁止从构建系统配置传递到可扩展 SDK 的变量。通常是构建机器专用变量，在 SDK 内可能造成问题。

默认由 populate-sdk-ext 设置，排除：

CONF_VERSION
BB_NUMBER_THREADS
BB_NUMBER_PARSE_THREADS
PARALLEL_MAKE
PRSERV_HOST
SSTATE_MIRRORS DL_DIR
SSTATE_DIR TMPDIR
BB_SERVER_TIMEOUT

定制配置的更多信息见《Yocto Project 应用开发与可扩展软件开发工具包（eSDK）手册》的 “配置可扩展 SDK”一节。

EXCLUDE_FROM_SHLIBS 

让构建系统的共享库解析器扫描共享库时排除整个软件包。

备注

共享库解析部分通过 do_package 中的内部函数 package_do_shlibs 实现，可能隐式定义软件包之间的依赖。

此变量类似 PRIVATE_LIBS，但后者只排除特定库，不排除整个包。

针对某个软件包设为“1”即可使用:

EXCLUDE_FROM_SHLIBS = "1"

EXCLUDE_FROM_WORLD 

要求 BitBake 从 world 构建（bitbake world）中排除该配方。 world 构建会查找、解析并构建 build/conf/bblayers.conf 列出的各层中的全部配方。

要排除，在配方中设为“1”。

备注

配方仍可能作为其他配方的依赖被构建。此设置只保证不将它显式加入 world 构建目标列表。

EXTENDPE 

用于文件名和路径名，根据 PE 生成配方版本前缀。 PE 已设置且大于零时，取其值，例如 PE 为“1”时得到“1”。 PE 未设置（默认情况）或为零时，得到空字符串。

示例见 STAMP。

EXTENDPKGV 

配方最终输出软件包上显示的完整版本规格。通常用于将同一配方另一软件包的运行时依赖固定为完全相同版本:

RDEPENDS:${PN}-additional-module = "${PN} (= ${EXTENDPKGV})"

这样强制软件包管理器同步升级这些包。

EXTERNAL_KERNEL_DEVICETREE 

继承 kernel-fit-image，且 virtual/dtb 的 PREFERRED_PROVIDER 为 devicetree 时，指定包含一个或多个待使用的已编译设备树或设备树覆盖的目录。

EXTERNAL_KERNEL_TOOLS 

设置后表示内核工具不在源码树中。

默认优先使用树内工具，而不是外部安装工具；设置此变量后改为优先使用外部工具。用法见 meta/classes-recipe 中的 kernel-yocto。

EXTERNAL_TOOLCHAIN 

使用外部工具链时，指定其安装目录。

EXTERNALSRC 

继承 externalsrc 时，指向构建系统之外的源码树。设置后会定义 S，供构建系统定位已解包配方源码。

详情见该类说明，以及《Yocto Project 开发任务手册》的 “从外部源码构建软件”一节。

EXTERNALSRC_BUILD 

继承 externalsrc 时，指向构建系统之外的源码构建目录。设置后会定义 B，供构建系统定位 Build Directory。

详情见该类说明，以及《Yocto Project 开发任务手册》的 “从外部源码构建软件”一节。

EXTRA_AUTORECONF 

继承 autotools* 时，指定 do_configure 中执行 autoreconf 的额外参数。

默认值为“--exclude=autopoint”。

EXTRA_IMAGE_FEATURES 

要额外加入镜像的功能列表，多项之间以空格分隔。

本地调整通常在 build/conf/local.conf 中设置，永久修改则在发行版 configuration file 中设置。虽然也可在配方中使用，但不建议这样做。

备注

在镜像配方中启用主要功能，请使用 IMAGE_FEATURES。

可添加功能示例：

dbg-pkgs：为所有已安装包添加 -dbg 包，包含调试和性能分析符号。
empty-root-password：允许 root 使用空密码登录。
allow-empty-password：允许 Dropbear 和 OpenSSH 接受密码字符串为空的账户登录。
allow-root-login：允许 Dropbear 和 OpenSSH 接受 root 登录。
post-install-logging：镜像首次在目标启动时，将安装后脚本日志写入 /var/log/postinstall.log。
dev-pkgs：为所有已安装包添加 -dev 包，便于针对镜像内库进行开发。
read-only-rootfs：创建只读根文件系统镜像。更多信息见《Yocto Project 安全手册》的 “创建只读根文件系统”一节。
tools-debug：添加 gdb、strace 等调试工具。
tools-sdk：添加 gcc、make、pkgconfig 等开发工具。
tools-testapps：添加 ts_print、aplay、arecord 等实用测试工具。

完整功能列表见“镜像功能”一节。

使用此变量定制镜像的示例见《Yocto Project 开发任务手册》的使用自定义镜像功能一节。

EXTRA_IMAGECMD 

为 IMAGE_CMD 指定的镜像创建命令添加额外选项。设置时使用对应镜像类型覆盖。例如:

EXTRA_IMAGECMD:ext3 ?= "-i 4096"

EXTRA_IMAGEDEPENDS 

需要构建、但不提供安装到根文件系统的软件包的配方列表。

某些配方是生成最终镜像必需的，却不需要出现在根文件系统中。可通过此列表建立依赖，典型例子是机器配置要求的引导加载程序。

备注

要向根文件系统添加软件包，请参阅各类 RDEPENDS 和 RRECOMMENDS。

EXTRA_OECMAKE 

额外的 CMake 选项。更多信息见 cmake。

EXTRA_OECONF 

额外的 configure 脚本选项。传递选项的更多信息见 PACKAGECONFIG_CONFARGS。

EXTRA_OEMAKE 

额外的 GNU make 选项。默认空字符串，需要时必须显式设置。

PARALLEL_MAKE 和 PARALLEL_MAKEINST 也通过它传递所需标志。

EXTRA_OEMESON 

额外的 Meson 选项，更多信息见 meson。

除标准选项外，也对应源码 meson_options.txt 中定义的 Meson 构建选项，例如:

EXTRA_OEMESON = "-Dpython=disabled -Dvalgrind=disabled"

自定义 --buildtype 值应通过 MESON_BUILDTYPE 设置。

EXTRA_OESCONS 

继承 scons 时，指定传给 scons 命令行的额外配置选项。

EXTRA_USERS_PARAMS 

继承 extrausers 时，提供镜像层面的用户和组操作。与将配置绑定到特定配方的 useradd* 相比，它作用范围更全局。

可配置的命令集合见 extrausers 类，映射到同名普通 Unix 命令:

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

useradd 或 usermod 的 -p 参数支持硬编码密码，但只能提供哈希。

以下示例添加 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; \
    "

备注

硬编码默认密码通常不安全，某些司法辖区甚至禁止这样做。不建议在生产镜像中使用。

另外，特殊命令 passwd-expire 可让用户密码过期，强制首次登录时修改。例如:

EXTRA_USERS_PARAMS += " useradd myuser; passwd-expire myuser;"

备注

当前远程登录时，passwd-expire 可能只支持 OpenSSH 服务器，不支持 Dropbear。

EXTRANATIVEPATH 

列出 ${STAGING_BINDIR_NATIVE} 的子目录，将其加到环境变量 PATH 最前面。例如，以下设置将“${STAGING_BINDIR_NATIVE}/foo:${STAGING_BINDIR_NATIVE}/bar:” 加到 PATH 前面:

EXTRANATIVEPATH = "foo bar"

FAKEROOT 

见《BitBake 手册》的 FAKEROOT。

FAKEROOTBASEENV 

见《BitBake 手册》的 FAKEROOTBASEENV。

FAKEROOTCMD 

见《BitBake 手册》的 FAKEROOTCMD。

FAKEROOTDIRS 

见《BitBake 手册》的 FAKEROOTDIRS。

FAKEROOTENV 

见《BitBake 手册》的 FAKEROOTENV。

FAKEROOTNOENV 

见《BitBake 手册》的 FAKEROOTNOENV。

FC 

运行 Fortran 编译器所需的最小命令及参数。

FEATURE_PACKAGES 

定义 IMAGE_FEATURES 包含特定功能项时应安装的一个或多个包。设置时应使用功能项名称作为覆盖。例如:

FEATURE_PACKAGES_widget = "package1 package2"

上例中，将 widget 加入 IMAGE_FEATURES 后，镜像包含 package1 和 package2。

备注

这些功能安装的包通常是软件包组，但不要混淆此变量与软件包组概念。软件包组在文档其他位置介绍。

FEED_DEPLOYDIR_BASE_URI 

指向服务器及其文档根目录下提供 OPKG 元数据和 IPK 包的基础 URL，用于运行时软件包管理。在 configuration file 中设置。

例如:

FEED_DEPLOYDIR_BASE_URI = "http://192.168.7.1/BOARD-dir"

此示例假定通过 HTTP 提供软件包，数据库位于 HTTP 文档根目录下的 BOARD-dir。构建系统会在目标中生成与此软件包源配套的配置文件。

FETCHCMD 

见《BitBake 手册》的 FETCHCMD。

FILE 

见《BitBake 手册》的 FILE。

FILES 

放入软件包的文件和目录列表。配方生成的软件包由 PACKAGES 列出。

使用软件包名称覆盖标识输出包，再列出以空格分隔的文件或路径。例如:

FILES:${PN} += "${bindir}/mydir1 ${bindir}/mydir2/myfile"

备注

可以使用 Python glob 语法匹配文件和路径，详细语法见链接。
建议使用路径变量，例如 ${sysconfdir} 而非 /etc， ${bindir} 而非 /usr/bin。列表见 OpenEmbedded-Core (OE-Core) 的 meta/conf/bitbake.conf 开头。该文件还定义各 FILES:* 变量的默认值。

如果某些文件可编辑，且更新时不应由软件包管理系统覆盖，可通过 CONFFILES 标识它们。

FILES_SOLIBSDEV 

定义匹配 SOLIBSDEV 的文件规格，即目标平台共享库的开发符号链接完整路径。

bitbake.conf 中的设置如下:

FILES_SOLIBSDEV ?= "${base_libdir}/lib*${SOLIBSDEV} ${libdir}/lib*${SOLIBSDEV}"

FILESEXTRAPATHS 

以冒号分隔的路径列表，扩展构建系统处理配方和追加文件时搜索文件与补丁的范围。默认搜索目录由 FILESPATH 定义，通过本变量扩展。

建议在 bbappend 中使用，并将路径加到前面:

FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:"

上例首先搜索与追加文件同名的目录。

备注

必须使用立即展开操作符 :=，确保 THISDIR 在遇到该指令时求值，而不是延迟到可能得到错误目录的时刻。

向前追加时还必须保留末尾的分隔冒号，因为这里是在原搜索路径前加入目录。

另一种常见用法:

FILESEXTRAPATHS:prepend := "${THISDIR}/files:"

此例添加与追加文件同目录的 files 子目录。

以下一次添加三个路径:

FILESEXTRAPATHS:prepend := "path_1:path_2:path_3:"

最后一个示例带有 MACHINE 专用覆盖，适合 BSP 层:

FILESEXTRAPATHS:prepend:intel-x86-common := "${THISDIR}/${PN}:"

该语句来自 Yocto Project 源码仓库中 meta-intel/common/recipes-kernel/linux 的 linux-yocto-dev.bbappend。这里的机器覆盖是供多个 meta-intel 机器使用的特殊 PACKAGE_ARCH 定义。

备注

只支持单个 BSP 的层，可以直接以 MACHINE 值作为覆盖。

在 bbappend 中向前追加路径，使不同层中针对同一配方的多个追加文件能够正确地共同扩展搜索范围。

FILESOVERRIDES 

冒号分隔的 OVERRIDES 子集，供构建系统创建 FILESPATH，并通过覆盖自动扩展它。示例见 FILESPATH 说明。覆盖机制见《BitBake 用户手册》的 “Conditional Syntax (Overrides)”一节。

默认定义为:

FILESOVERRIDES = "${TRANSLATED_TARGET_ARCH}:${MACHINEOVERRIDES}:${DISTROOVERRIDES}"

备注

不要手动编辑。其值与构建系统预期的覆盖及使用方式对应。

FILESPATH 

默认补丁和文件搜索目录列表，以冒号分隔。

BitBake 按列表顺序搜索配方 SRC_URI 中各 file:// URI 指定的文件和补丁。

默认值在 OpenEmbedded-Core (OE-Core) 的 meta/classes-global 中的 base 定义:

FILESPATH = "${@oe.utils.base_set_filespath(["${FILE_DIRNAME}/${BP}", \
    "${FILE_DIRNAME}/${BPN}", "${FILE_DIRNAME}/files"], d)}"

通过 FILESOVERRIDES 中的覆盖自动扩展。

备注

不要手动编辑。若要搜索默认之外的目录，应使用 FILESEXTRAPATHS 扩展。
默认目录不会映射到自定义层中 bbappend 所在的目录。若补丁或文件与追加文件放在一起，必须用 FILESEXTRAPATHS 添加位置。

可以利用这种搜索行为组织通用和机器专用配置。例如:

files/defconfig
files/MACHINEA/defconfig
files/MACHINEB/defconfig

若 SRC_URI 包含 file://defconfig，则 MACHINE 为 MACHINEA 时使用 files/MACHINEA，为 MACHINEB 时使用 files/MACHINEB，其他机器使用 files/defconfig。

补丁处理详情见《Yocto Project 概览与概念手册》的 “打补丁”及《开发任务手册》的 “修补代码”，另见 do_patch。

FILESYSTEM_PERMS_TABLES 

允许在打包配置中定义自己的文件权限表。例如整个项目需要为一组用户和组采用一致的自定义权限。最好在软件包本身设置，但不总是可行。

默认使用 OpenEmbedded-Core (OE-Core) 的 meta/files 中的 fs-perms.txt、 fs-perms-volatile-log.txt 和 fs-perms-volatile-tmp.txt。自定义权限表应放在自己的层中。

可以在发行版配置中覆盖此变量，指定一个或多个自定义表，路径必须位于 BBPATH。

移除 files/fs-perms-volatile-log.txt 可禁用默认的易失日志目录；移除 files/fs-perms-volatile-tmp.txt 可禁用易失 tmp 目录。

定义格式可参考上述三个现有文件。

FIRMWARE_COMPRESSION 

压缩 linux-firmware 配方提供的固件。默认空字符串，即不压缩；可选 xz 或 zst，可能显著节省空间。

内核必须设置 CONFIG_FW_LOADER_COMPRESS_XZ 或 CONFIG_FW_LOADER_COMPRESS_ZSTD 才能使用压缩固件。

FIT_ADDRESS_CELLS 

指定 FIT 描述中的 #address-cells。 kernel-fit-image 默认为“1”，对应 32 位地址。

平台若在 UBOOT_LOADADDRESS、UBOOT_ENTRYPOINT 等位置需要 64 位地址，应设为“2”，因为需两个 32 位 cell 表示。

以下将加载地址设为 0x400000000:

FIT_ADDRESS_CELLS = "2"
UBOOT_LOADADDRESS = "0x04 0x00000000"

更多说明见 #address-cells。

FIT_CONF_DEFAULT_DTB 

FIT 包含多个设备树二进制文件时指定默认 DTB。用于 kernel-fit-image。

FIT_CONF_MAPPINGS 

继承 kernel-fit-image 时，指定映射以重命名配置节点，或为已有 DTB 增加配置节点。当 DTB 名称与配置节点名称不能一一对应时很有用，例如内核与引导加载程序命名不同，需要兼容既有启动脚本或配置，也可用于其他场景。

接受空格分隔的映射命令：

dtb-conf:DTB_NAME:NEW_NAME：重命名特定 DTB 的配置节点， DTB_NAME 不包含 .dtb 后缀。
dtb-extra-conf:DTB_NAME:EXTRA_NAME：为已有 DTB 创建额外配置节点，为同一硬件配置提供替代名称，兼容已有启动脚本和引导加载程序配置，或用于其他需要配置别名的场景。

例如:

FIT_CONF_MAPPINGS = "\
    dtb-extra-conf:am335x-bonegreen:bonegreen \
    dtb-conf:am335x-boneblack:bbblack"

此设置根据两个 DTB 生成三个配置节点：

am335x-bonegreen：同名设备树的原始配置节点。
bonegreen：同一个 am335x-bonegreen DTB 的额外节点。
bbblack：am335x-boneblack DTB 重命名后的节点。

该类验证全部映射，确保它们对应已存在的 DTB。

FIT_CONF_PREFIX 

使用 kernel-fit-image 时创建 FIT 配置节点的前缀，默认为 conf-。

FIT_DESC 

编码到 FIT 镜像中的描述字符串，kernel-fit-image 默认设置为:

FIT_DESC ?= "U-Boot fitImage for ${DISTRO_NAME}/${PV}/${MACHINE}"

FIT_GENERATE_KEYS 

决定 FIT 签名密钥不存在时是否生成，密钥保存到 UBOOT_SIGN_KEYDIR。 kernel-fit-image 默认设为“0”。

FIT_HASH_ALG 

指定 FIT 的哈希算法，kernel-fit-image 默认设为“sha256”。

FIT_KERNEL_COMP_ALG 

FIT 内核镜像使用的压缩算法，目前仅支持 gzip（默认）、lzo 或 none。用于 kernel-uboot。

FIT_KERNEL_SIGN_ENABLE 

供 kernel-fit-image 启用或禁用 FIT 签名。默认等于 UBOOT_SIGN_ENABLE，即启用 U-Boot FIT 签名后，构建时也会签名 FIT，运行时由 U-Boot 验证。

设为“1”时，使用 FIT_KERNEL_SIGN_KEYDIR 中 FIT_KERNEL_SIGN_KEYNAME 指定的密钥。

覆盖此值时，也应相应设置上述两个密钥变量。

FIT_KERNEL_SIGN_KEYDIR 

用于 kernel-fit-image，默认等于 UBOOT_SIGN_KEYDIR。构建时使用该目录私钥签名内核，并将同目录公钥注入 U-Boot DTB，用于目标端 FIT 验证。

覆盖时，也应相应设置 FIT_KERNEL_SIGN_ENABLE 和 FIT_KERNEL_SIGN_KEYNAME。

FIT_KERNEL_SIGN_KEYNAME 

用于 kernel-fit-image，默认等于 UBOOT_SIGN_KEYNAME。构建时使用该名称的私钥签名内核，并将同名公钥注入 U-Boot DTB，用于目标端 FIT 验证。

覆盖时，也应相应设置 FIT_KERNEL_SIGN_ENABLE 和 FIT_KERNEL_SIGN_KEYDIR。

FIT_KEY_GENRSA_ARGS 

传给 openssl genrsa 以生成 FIT 签名 RSA 私钥的参数。 kernel-fit-image 默认为“-F4”。

FIT_KEY_REQ_ARGS 

传给 openssl req 以生成 FIT 签名证书的参数。 kernel-fit-image 默认为“-batch -new”， batch 表示非交互模式，new 表示生成新密钥。

FIT_KEY_SIGN_PKCS 

指定 FIT 的签名公钥证书格式，kernel-fit-image 默认设为“x509”。

FIT_LOADABLE_ARCH 

指定 FIT_LOADABLES 中对象的架构，用于其 arch 属性。未指定时使用内核架构。

不能直接赋值，只能定义变量标志。例如:

FIT_LOADABLES = "foo"
FIT_LOADABLE_ARCH[foo] = "arm"

FIT_LOADABLE_COMPRESSION 

指定 FIT_LOADABLES 中对象的压缩类型，用于其 compression 属性。未指定时设为 none。

不能直接赋值，只能定义变量标志。例如:

FIT_LOADABLES = "foo"
FIT_LOADABLE_COMPRESSION[foo] = "gzip"

备注

二进制文件必须已压缩，kernel-fit-image 不执行压缩。

FIT_LOADABLE_DESCRIPTION 

指定 FIT_LOADABLES 中对象的描述，用于其 description 属性。未指定时使用对象名称，加空格和 loadable 字符串。

不能直接赋值，只能定义变量标志。例如:

FIT_LOADABLES = "foo"
FIT_LOADABLE_DESCRIPTION[foo] = "Foo firmware binary"

FIT_LOADABLE_ENTRYPOINT 

指定 FIT_LOADABLES 中对象的入口点，用于其 entry 属性。未指定时省略 entry 属性。

不能直接赋值，只能定义变量标志。例如:

FIT_LOADABLES = "foo"
FIT_LOADABLE_ENTRYPOINT[foo] = "0x80234000"

FIT_LOADABLE_FILENAME 

FIT_LOADABLES 中对象的文件名或相对路径，用于查找待包含的二进制文件，因此每个对象都必须指定。文件必须位于 DEPLOY_DIR_IMAGE。

不能直接赋值，只能定义变量标志。例如:

FIT_LOADABLES = "foo"
FIT_LOADABLE_FILENAME[foo] = "foo-firmware.bin"

FIT_LOADABLE_LOADADDRESS 

指定 FIT_LOADABLES 中对象的加载地址，用于其 load 属性。每个对象都必须指定。

不能直接赋值，只能定义变量标志。例如:

FIT_LOADABLES = "foo"
FIT_LOADABLE_LOADADDRESS[foo] = "0x80230000"

FIT_LOADABLE_OS 

指定 FIT_LOADABLES 中对象的操作系统，用于其 os 属性。未指定时设为 linux。

不能直接赋值，只能定义变量标志。例如:

FIT_LOADABLES = "foo"
FIT_LOADABLE_OS[foo] = "linux"

FIT_LOADABLE_TYPE 

指定 FIT_LOADABLES 中对象的类型，用于其 type 属性。未指定时设为 firmware。

不能直接赋值，只能定义变量标志。例如:

FIT_LOADABLES = "foo"
FIT_LOADABLE_TYPE[foo] = "firmware"

FIT_LOADABLES 

额外加入 FIT 的可加载对象列表，以空格分隔，不包括内核、initramfs、dtsb 等常规组件。列表值用作 FIT 节点名，所有对象通过 loadables 属性加入全部配置。

各对象可通过 FIT_LOADABLE_ARCH、FIT_LOADABLE_COMPRESSION、 FIT_LOADABLE_DESCRIPTION、FIT_LOADABLE_ENTRYPOINT、 FIT_LOADABLE_FILENAME、FIT_LOADABLE_LOADADDRESS、 FIT_LOADABLE_OS 和 FIT_LOADABLE_TYPE 进一步配置。

用于 kernel-fit-image，默认为空。

以下加入 TF-A BL31 固件和压缩的 TEE 固件，分别加载到 0x204E0000 和 0x96000000:

FIT_LOADABLES = "atf tee"

FIT_LOADABLE_FILENAME[atf] = "bl31.bin"
FIT_LOADABLE_DESCRIPTION[atf] = "TF-A Firmware"
FIT_LOADABLE_TYPE[atf] = "tfa-bl31"
FIT_LOADABLE_ARCH[atf] = "arm64"
FIT_LOADABLE_OS[atf] = "arm-trusted-firmware"
FIT_LOADABLE_LOADADDRESS[atf] = "0x204E0000"
FIT_LOADABLE_ENTRYPOINT[atf] = "0x204E0000"

FIT_LOADABLE_FILENAME[tee] = "tee.bin.gz"
FIT_LOADABLE_COMPRESSION[tee] = "gzip"
FIT_LOADABLE_TYPE[tee] = "tee"
FIT_LOADABLE_OS[tee] = "tee"
FIT_LOADABLE_LOADADDRESS[tee] = "0x96000000"

转换为以下 FIT 源码：

images {
        atf {
                description = "TF-A Firmware";
                type = "tfa-bl31";
                compression = "none";
                data = /incbin/("<DEPLOY_DIR_IMAGE>/bl31.bin");
                arch = "arm64";
                os = "arm-trusted-firmware";
                load = <0x204E0000>;
                entry = <0x204E0000>;
        };
        tee {
                description = "tee loadable";
                type = "tee";
                compression = "gzip";
                data = /incbin/("<DEPLOY_DIR_IMAGE>/tee.bin.gz");
                arch = "arm64";
                os = "tee";
                load = <0x96000000>;
        };
};

configurations {
        default = "<my-board>.dtb";
        <my-board>.dtb {
                description = "1 Linux kernel, FDT blob, loadables";
                kernel = "kernel-1";
                fdt = "<my-board>.dtb";
                loadables = "atf", "tee";
        };
};

FIT_MKIMAGE_EXTRA_OPTS 

继承 kernel-fit-image 时，传递生成 FIT 所用 mkimage 的额外选项，满足平台对默认参数之外选项的需求。

例如:

FIT_MKIMAGE_EXTRA_OPTS = "-B 8 -E"

mkimage 将按如下方式调用：

mkimage -B 8 -E -f fit-image.its fitImage

FIT_OS 

控制 FIT 中内核及其他镜像的 os 字段。设为 efi，可将带 EFI stub 的内核作为 EFI 应用加载。默认为 linux。

FIT_PAD_ALG 

指定 FIT 的填充算法，kernel-fit-image 默认设为“pkcs-1.5”。

FIT_SIGN_ALG 

指定 FIT 的签名算法，kernel-fit-image 默认设为“rsa2048”。

FIT_SIGN_INDIVIDUAL 

设为“1”时，kernel-fit-image 除签名配置节点外，还分别签名每个镜像节点，包括内核、DTB、RAM 磁盘及其他类型。需要在 U-Boot 启动过程之外验证签名时可能有用。默认“0”。

UBOOT_SIGN_ENABLE 为“1”且本变量保持“0”时，仅签名配置节点。配置节点包含引用镜像节点的哈希，因此只要通过配置节点加载镜像并验证哈希，即可确保整个 FIT 完整性；通常都属于这种情况。

逐节点签名通常增加复杂性，收益有限。例外可能是未被任何配置引用的镜像节点，或因其他原因直接加载的节点。多数场景设为“0”已提供足够安全性。

详情见 U-Boot 官方的 FIT 签名，尤其是配置签名。

OpenEmbedded-Core (OE-Core) 有意不实现仅签名镜像节点的方式，因为该方式容易受到混搭攻击。

FIT_SIGN_NUMBITS 

指定 FIT 的私钥位数，kernel-fit-image 默认设为“2048”。

FIT_UBOOT_ENV 

将包含 U-Boot 脚本的文本文件加入 FIT，以便在 U-Boot shell 中执行。

继承 kernel-fit-image 时，应将脚本加入 Linux 内核配方的 SRC_URI。例如：

将 boot.cmd 加入内核配方:

FIT_UBOOT_ENV = "boot.cmd"
SRC_URI += "file://${FIT_UBOOT_ENV}"

从 U-Boot shell 使用脚本。FIT 中的名称是 bootscr-${FIT_UBOOT_ENV}。以下从 TFTP 服务器加载 FIT:
```
tftp $loadaddr $fit_tftp_path
source $loadaddr#bootscr-boot.cmd
```

更多信息见官方 U-Boot source 命令。

FONT_EXTRA_RDEPENDS 

继承 fontcache 时，指定字体包的运行时依赖，默认为 fontconfig-utils。

FONT_PACKAGES 

继承 fontcache 时，标识包含需由 Fontconfig 缓存的字体文件的包。默认假定字体位于主包 ${PN}。字体位于其他包时使用此变量。

FORCE_RO_REMOVE 

在根文件系统生成期间，强制移除 ROOTFS_RO_UNNEEDED 所列软件包。设为“1”启用。

FULL_OPTIMIZATION 

编译优化系统时通过 TARGET_CFLAGS 和 CFLAGS 传递的选项。默认为“-O2 ${DEBUG_LEVELFLAG}”。

GCCPIE 

在 GCC 中启用位置无关可执行文件（PIE），使面向返回编程（ROP）攻击更难实施。

security_flags.inc 默认通过以下设置启用:

GCCPIE ?= "--enable-default-pie"

GCCVERSION 

指定编译使用的默认 GCC 版本。 meta/conf/distro/include/tcmode-default.inc 默认设为 8.x:

GCCVERSION ?= "8.%"

可在发行版配置等 configuration file 中覆盖，前提是工作区存在对应 GCC 版本的配方。

GDB 

运行 GNU 调试器所需的最小命令及参数。

GIR_EXTRA_LIBS_PATH 

为使用 GObject introspection、且缺少此设置就无法编译的 GLib 相关配方，指定 .so 文件的额外搜索路径。详情见“启用 GObject 内省支持”一节。

GITDIR 

克隆 Git 仓库时保存本地副本的目录。

GITHUB_BASE_URI 

继承 github-releases 时，指定待获取源码的 GitHub 项目发布文件的基础 URL。默认如下:

GITHUB_BASE_URI ?= "https://github.com/${BPN}/${BPN}/releases/"

GLIBC_GENERATE_LOCALES 

指定要生成的 GLIBC 区域设置列表，避免生成全部区域设置带来的较长耗时。

备注

如果显式移除 en_US.UTF-8，必须适当设置 IMAGE_LINGUAS。

本地测试可在 build/conf/local.conf 设置，也可在发行版 configuration file 设置。

默认生成全部区域设置:

GLIBC_GENERATE_LOCALES = "en_GB.UTF-8 en_US.UTF-8"

GO_IMPORT 

继承 go 时的必需变量，设置为待构建代码创建的 Go 包的导入路径。源码目录包含 go.mod 时，通常与其 module 行中的路径一致。

其他 Go 程序导入该包时将使用此路径。

以下来自 go-helloworld_0.1.bb:

GO_IMPORT = "golang.org/x/example"

GO_INSTALL 

继承 go 时，可选指定源码中哪些包由 go install 编译并安装到 Go 构建空间。

以下来自 crucible:

GO_INSTALL = "\
    ${GO_IMPORT}/cmd/crucible \
    ${GO_IMPORT}/cmd/habtool \
"

默认定义为:

GO_INSTALL ?= "${GO_IMPORT}/..."

... 通配符匹配源码中的全部包。如需排除不需要的包，使用 GO_INSTALL_FILTEROUT。

GO_INSTALL_FILTEROUT 

使用 Go vendor 机制引入依赖时，GO_INSTALL 默认的 ... 通配符会将 vendored 包也纳入构建，产生错误结果。

某些 Go 包结构不合理，... 还可能构建不应包含或无法构建的示例、测试代码。

此可选变量允许过滤部分源码。默认排除包主目录下的 vendor 子目录，这是 vendored 包的正常位置。配方可按需覆盖，以过滤其他子目录。

GO_WORKDIR 

使用 Go Modules 时，当前工作目录必须是包含 go.mod 的目录或其子目录。 go 工具只在当前工作目录和各父目录查找 go.mod，不搜索子目录。

使用 go-mod 时，此可选变量指定不同的 Go 工作目录，默认等于 GO_IMPORT。

GROUPADD_PARAM 

继承 useradd* 时，为软件包指定安装时向 groupadd 传入的参数，以向系统添加组。

以下来自 dbus 配方:

GROUPADD_PARAM:${PN} = "-r netdev"

用分号分隔各组的参数集合，可添加多个组。以下来自 meta-skeleton 层的 useradd-example.bb:

GROUPADD_PARAM:${PN} = "-g 880 group1; -g 890 group2"

标准 Linux 命令说明见 groupadd(8)。

GRUB_GFXSERIAL 

配置 GRUB 启动菜单同时支持图形和串口。在 build/conf/local.conf 或发行版 configuration file 中设为“1”启用。

用法见 grub-efi。

GRUB_MKIMAGE_OPTS 

控制 GRUB 配方 do_mkimage 任务中传给 grub-mkimage 的额外选项。

GRUB_OPTS 

添加到 GRUB 配置的额外选项，多项以分号（;）分隔。

此变量可选，用法见 grub-efi。

GRUB_TIMEOUT 

指定 GRUB 执行默认 LABEL 前的等待时间。

此变量可选，用法见 grub-efi。

GRUB_TITLE 

为 LABELS 定义的 GRUB 标签指定自定义标题。用法见 grub-efi。

GTKIMMODULES_PACKAGES 

继承 gtk-immodules-cache 时，如果待安装的 GTK+ 输入法模块不在主软件包中，用此变量指定包含它们的包。

HGDIR 

见《BitBake 手册》的 HGDIR。

HOMEPAGE 

可获取配方所构建软件更多信息的网站。

HOST_ARCH 

目标架构名称，通常等于 TARGET_ARCH。构建系统支持多种架构，以下只是示例，并非完整列表，因为架构可以配置：

arm
i586
x86_64
powerpc
powerpc64
mips
mipsel

HOST_AS_ARCH 

指定架构专用的汇编器标志。默认初始化取决于构建对象：

目标使用 TARGET_AS_ARCH。
构建主机（-native）使用 BUILD_AS_ARCH。
SDK（nativesdk-）使用 SDK_AS_ARCH。

HOST_CC_ARCH 

指定架构专用的传给 C 编译器的编译器标志。默认初始化取决于构建对象：

目标使用 TARGET_CC_ARCH。
构建主机（-native）使用 BUILD_CC_ARCH。
SDK（nativesdk-）使用 SDK_CC_ARCH。

HOST_LD_ARCH 

指定架构专用的链接器标志。默认初始化取决于构建对象：

目标使用 TARGET_LD_ARCH。
构建主机（-native）使用 BUILD_LD_ARCH。
SDK（nativesdk-）使用 SDK_LD_ARCH。

HOST_OS 

目标操作系统名称，通常等于 TARGET_OS。 glibc 系统可设为 linux，musl 系统为 linux-musl。 ARM/EABI 目标还可使用 linux-gnueabi 和 linux-musleabi。

HOST_PREFIX 

交叉工具链前缀，通常等于 TARGET_PREFIX。

HOST_SYS 

指定当前配方构建上下文所针对的系统，包括架构和操作系统。构建系统根据 HOST_ARCH、HOST_VENDOR、HOST_OS 自动设置。

备注

无需手动设置。

例如：

在运行 Linux 的 32 位 x86 机器上构建 native 配方，值为 i686-linux。
为运行 Linux 的小端 MIPS 目标构建，值可能为 mipsel-linux。

HOST_VENDOR 

指定厂商名称，通常等于 TARGET_VENDOR。

HOSTTOOLS 

允许在构建任务中调用的主机工具列表，以空格分隔，用于降低主机环境污染的可能性。如果列表中的工具在主机上找不到，构建系统会报错，不启动构建。

另见 HOSTTOOLS_NONFATAL。

HOSTTOOLS_NONFATAL 

允许在构建任务中调用的主机工具列表，以空格分隔，用于降低主机环境污染的可能性。与 HOSTTOOLS 不同，找不到所列工具时不会报错，因此可用于筛选可选主机工具。

IMAGE_BASENAME 

镜像输出文件的基本名称，默认是配方名称 ${PN}。

IMAGE_BOOT_FILES 

使用 Wic 的 bootimg_partition 源插件准备镜像时，安装到启动分区的文件列表，以空格分隔。默认保留源文件名称；要改名，以分号分隔原名和目标名。源文件必须位于 DEPLOY_DIR_IMAGE。例如:

IMAGE_BOOT_FILES = "u-boot.img uImage;kernel"
IMAGE_BOOT_FILES = "u-boot.${UBOOT_SUFFIX} ${KERNEL_IMAGETYPE}"

也可以通过 glob 模式选取源文件，此时目标名必须与源路径的基本文件名相同。要安装到目标位置的子目录，在分号后提供目录名。例如:

IMAGE_BOOT_FILES = "bcm2835-bootfiles/*"
IMAGE_BOOT_FILES = "bcm2835-bootfiles/*;boot/"

第一例将 ${DEPLOY_DIR_IMAGE}/bcm2835-bootfiles 的全部文件安装到分区根目录，第二例将同样文件安装到分区的 boot 子目录。

Wic 用法见《Yocto Project 开发任务手册》的 “使用 Wic 创建分区镜像”，参考资料见“OpenEmbedded Kickstart（.wks）参考”章。

IMAGE_BUILDINFO_FILE 

使用 image-buildinfo 时，指定镜像中保存构建信息的文件，默认 ${sysconfdir}/buildinfo。

IMAGE_BUILDINFO_VARS 

使用 image-buildinfo 时，以空格分隔指定输出文件 Build Configuration 部分包含的变量。默认是 DISTRO 和 DISTRO_VERSION。

IMAGE_CLASSES 

所有镜像都应继承的类列表，通常用于在全部镜像配方中启用功能。

类必须位于 classes-recipe/ 或 classes/ 子目录。

IMAGE_CMD 

创建特定类型镜像文件的命令，对应 IMAGE_FSTYPES 中的 ext3、btrfs 等值。应使用对应镜像类型覆盖，例如:

IMAGE_CMD:jffs2 = "mkfs.jffs2 --root=${IMAGE_ROOTFS} --faketime \
    --output=${IMGDEPLOYDIR}/${IMAGE_NAME}${IMAGE_NAME_SUFFIX}.jffs2 \
    ${EXTRA_IMAGECMD}"

除非添加新镜像类型，通常无需设置。更多示例见 image_types，即 meta/classes-recipe/image_types.bbclass。

IMAGE_CONTAINER_NO_DUMMY 

镜像的 IMAGE_FSTYPES 包含 container 时，要求在 configuration file 中将 Linux 内核 virtual/kernel 的 PREFERRED_PROVIDER 设为 linux-dummy，否则报错。

本变量设为“1”时允许选择其他提供者，跳过检查和错误；其他值仍执行检查。应在使用 container 类型的镜像配方中设置。

为何推荐 linux-dummy，见 image-container。

IMAGE_DEVICE_TABLES 

指定一个或多个自定义设备表文件，创建镜像时传给 makedevs。这些文件列出应在镜像 /dev 下创建的基本设备节点。未设置时，沿 BBPATH 查找并使用 files/device_table-minimal.txt。文件格式可参考 meta/files/device_table-minimal.txt。

IMAGE_EFI_BOOT_FILES 

使用 Wic 的 bootimg_efi 源插件准备镜像时，安装到启动分区的文件列表，以空格分隔。默认保留源文件名称；要改名，以分号分隔原名和目标名。源文件必须位于 DEPLOY_DIR_IMAGE。例如:

IMAGE_EFI_BOOT_FILES = "${KERNEL_IMAGETYPE};bz2"
IMAGE_EFI_BOOT_FILES = "${KERNEL_IMAGETYPE} microcode.cpio"

也可以通过 glob 模式选取源文件，此时目标名必须与源路径的基本文件名相同。要安装到目标位置的子目录，在分号后提供目录名。例如:

IMAGE_EFI_BOOT_FILES = "boot/loader/*"
IMAGE_EFI_BOOT_FILES = "boot/loader/*;boot/"

第一例将 ${DEPLOY_DIR_IMAGE}/boot/loader/ 的全部文件安装到分区根目录，第二例将同样文件安装到分区的 boot 子目录。

Wic 用法见《Yocto Project 开发任务手册》的 “使用 Wic 创建分区镜像”，参考资料见“OpenEmbedded Kickstart（.wks）参考”章。

IMAGE_EXTRA_PARTITION_FILES 

通过 Wic 的 extra_partition 源插件生成镜像时，安装到额外分区的文件列表，以空格分隔。默认保持源文件名；若需改名，在原名后以分号分隔指定目标名。源文件必须位于 DEPLOY_DIR_IMAGE。例如:

IMAGE_EXTRA_PARTITION_FILES = "foobar file.conf;config"

上例中 foobar 保持原名，file.conf 安装后改名为 config。

也可用 glob 模式选择源文件，但忽略隐藏文件，且不递归搜索子目录。目标文件保持源路径的基本文件名。若需安装到目标内改名后的目录，在分号后提供目录名。例如:

IMAGE_EXTRA_PARTITION_FILES = "foo/*"
IMAGE_EXTRA_PARTITION_FILES = "foo/*;bar/"

第一行将 foo 目录内全部文件安装到目标分区根目录；第二行安装到 bar 子目录。 bar/ 不存在时自动创建。

多个额外分区共存时，可通过标签、UUID 或分区名称选择目标。例如当前镜像使用以下 WKS:

part --source extra_partition --fstype=ext4 --label foo
part --source extra_partition --fstype=ext4 --uuid e7d0824e-cda3-4bed-9f54-9ef5312d105d
part --source extra_partition --fstype=ext4 --part-name config

并使用以下配置:

IMAGE_EXTRA_PARTITION_FILES_label-foo = "foo/*"
IMAGE_EXTRA_PARTITION_FILES_uuid-e7d0824e-cda3-4bed-9f54-9ef5312d105d = "foo/*;bar/"
IMAGE_EXTRA_PARTITION_FILES_part-name-config = "config"

结果为：

标签为 foo 的分区得到 foo 目录全部文件。
UUID 为 e7d0824e-cda3-4bed-9f54-9ef5312d105d 的分区，将 foo 目录全部文件安装到 bar 子目录。
名为 config 的分区得到 config 文件。

Wic 用法见《Yocto Project 开发任务手册》的 “使用 Wic 创建分区镜像”，参考资料见“OpenEmbedded Kickstart（.wks）参考”章。

IMAGE_FEATURES 

镜像包含的主要功能列表，通常在镜像配方中配置。虽然也可在 Build Directory 的 build/conf/local.conf 中设置，但不建议这样做。

备注

在镜像配方之外启用额外功能，应使用 EXTRA_IMAGE_FEATURES。

可用功能列表见“镜像功能”。定制示例见《Yocto Project 开发任务手册》的使用自定义镜像功能一节。

IMAGE_FSTYPES 

指定构建系统创建根文件系统时使用的格式。例如以下会生成 .ext3 和 .tar.bz2 两种格式:

IMAGE_FSTYPES = "ext3 tar.bz2"

完整支持列表见 IMAGE_TYPES。

备注

在镜像配方中设置且使用 inherit image 时，必须在继承语句之前设置。
由于此变量的处理方式，不能用 :append 或 :prepend 更新，必须使用 += 添加一个或多个选项。

IMAGE_FSTYPES_DEBUGFS 

IMAGE_GEN_DEBUGFS 为“1”时生成的文件系统镜像类型列表，支持的内容与 IMAGE_FSTYPES 相同。

IMAGE_GEN_DEBUGFS 

在 image 配方中设为“1”时，构建系统生成包含镜像已安装包的调试符号和源码的配套镜像。通过添加软件包源中可用的全部 -dbg 和 -src 包实现，这些包在拆分软件包中自动生成。

IMAGE_INSTALL 

配方通过 image 指定要安装到镜像的软件包。使用时应注意避免顺序问题。

镜像配方设置此变量，core-image 等辅助类还会把 IMAGE_FEATURES 转换为自动生成的条目，加入默认内容。

推荐使用以下方式:

IMAGE_INSTALL:append = " package-name"

务必保留引号与软件包名之间的空格。

备注

core-image-minimal-initramfs 镜像不应通过本变量指定软件包，应使用 PACKAGE_INSTALL，让 Initramfs 使用固定包集合，不受 IMAGE_INSTALL 影响。创建方法见《Yocto Project 开发任务手册》的 “构建初始 RAM 文件系统（Initramfs）镜像”一节。
不建议在 build/conf/local.conf 或镜像配方中，用 += 操作本变量，可能造成顺序问题。 core-image 使用 ?= 设置默认值，因此 local.conf 中的 += 会产生非预期行为。镜像配方中同样的操作是否成功取决于具体情况，两者都可能违背用户对 += 的通常预期。

IMAGE_LINGUAS 

指定根文件系统构建时安装的区域设置列表。构建系统将本地化文件自动拆分为独立包；设置此变量后，会为已选定安装的包同步安装对应的区域设置包。例如:

IMAGE_LINGUAS = "pt-br de-de"

上例安装镜像中各包的巴西葡萄牙语和德语文件，包括 -locale-pt-br、-locale-de-de，也包括 -locale-pt、-locale-de，因为部分软件只按语言、不按国家提供文件。

GLIBC 区域设置生成见 GLIBC_GENERATE_LOCALES。

IMAGE_LINK_NAME 

输出镜像符号链接名，不包含 IMAGE_NAME 中的版本部分。默认由 IMAGE_BASENAME 和 IMAGE_MACHINE_SUFFIX 得到:

IMAGE_LINK_NAME ?= "${IMAGE_BASENAME}${IMAGE_MACHINE_SUFFIX}"

备注

可以设为空字符串禁用符号链接，但也需为 IMAGE_NAME 设置合理值，例如:

IMAGE_LINK_NAME = ""
IMAGE_NAME = "${IMAGE_BASENAME}${IMAGE_MACHINE_SUFFIX}${IMAGE_VERSION_SUFFIX}"

IMAGE_MACHINE_SUFFIX 

镜像文件名扩展名之前的机器专用后缀，默认设置如下:

IMAGE_MACHINE_SUFFIX ??= "-${MACHINE}"

默认 DEPLOY_DIR_IMAGE 已有 MACHINE 子目录，因此可能无需在每个文件名中重复机器后缀。可设为空以移除:

IMAGE_MACHINE_SUFFIX = ""

不要与 IMAGE_NAME_SUFFIX 混淆。

IMAGE_MANIFEST 

镜像清单文件，列出组成镜像的全部已安装包，每包一行，格式如下:

packagename packagearch version

rootfs-postcommands 定义如下:

IMAGE_MANIFEST = "${IMGDEPLOYDIR}/${IMAGE_NAME}${IMAGE_NAME_SUFFIX}.manifest"

位置由 IMGDEPLOYDIR 和 IMAGE_NAME 得到。镜像创建过程见《Yocto Project 概览与概念手册》的 “生成镜像”一节。

IMAGE_NAME 

不含扩展名的输出镜像名称，默认由 IMAGE_LINK_NAME 和 IMAGE_VERSION_SUFFIX 设置:

IMAGE_NAME ?= "${IMAGE_LINK_NAME}${IMAGE_VERSION_SUFFIX}"

IMAGE_NAME_SUFFIX 

镜像输出文件名后缀，默认 .rootfs，用于与构建中生成的其他文件区分。不需要时可设为空字符串，例如 Initramfs 镜像配方通常清空它。

IMAGE_OUTPUT_MANIFEST 

直接或通过 core-image 继承 image 时，指向JSON 清单文件，列出 IMAGE_FSTYPES 定义的各创建任务生成的镜像。 image 类设置如下:

IMAGE_OUTPUT_MANIFEST = "${IMAGE_OUTPUT_MANIFEST_DIR}/manifest.json"

IMAGE_OUTPUT_MANIFEST_DIR 

直接或通过 core-image 继承 image 时，指向保存 JSON 清单文件的目录，列出 IMAGE_FSTYPES 定义的各创建任务生成的镜像。 image 类设置如下:

IMAGE_OUTPUT_MANIFEST_DIR = "${WORKDIR}/deploy-image-output-manifest"

IMAGE_OVERHEAD_FACTOR 

定义用于初始镜像大小的乘数。当镜像实际磁盘用量乘以此值，大于 IMAGE_ROOTFS_SIZE 与 IMAGE_ROOTFS_EXTRA_SPACE 之和时，采用乘积来确定大小。乘数为镜像增加额外可用空间。默认 1.3，即按这种方式计算时增加 30% 空间。安装后脚本和包管理系统也会消耗这部分空间，因此最终可用空间少于理论值。总体计算方法见 IMAGE_ROOTFS_SIZE。

默认增加的 30% 通常足以支持启动和基本安装后操作，并留少量空余。若不足，可提高值，例如增加 50%:

IMAGE_OVERHEAD_FACTOR = "1.5"

也可以通过 IMAGE_ROOTFS_EXTRA_SPACE 保证增加指定大小的空闲空间。

使用 Wic 时还会应用第二个余量系数，由 --overhead-factor 指定，省略时默认 1.3。详情见 OpenEmbedded Kickstart（.wks）参考的命令：part 或 partition 一节。

IMAGE_PKGTYPE 

定义构建系统所用软件包类型（DEB、RPM 或 IPK），由 package_deb、package_rpm 或 package_ipk 相应设置。

populate_sdk_* 和 image 使用它为镜像和 SDK 打包。

不应手动设置，而是通过 PACKAGE_CLASSES 选择适当 package_* 类间接设置。构建系统采用列表中第一个软件包类型。

IMAGE_POSTPROCESS_COMMAND 

指定最终镜像输出文件创建之后调用的函数列表，以空格分隔:

IMAGE_POSTPROCESS_COMMAND += "function"

若函数内的命令需要根文件系统路径，可以使用 ${IMAGE_ROOTFS}，它指向将成为根文件系统镜像的目录。更多信息见 IMAGE_ROOTFS。

IMAGE_PREPROCESS_COMMAND 

指定最终镜像输出文件创建之前调用的函数列表，以空格分隔:

IMAGE_PREPROCESS_COMMAND += "function"

若函数内的命令需要根文件系统路径，可以使用 ${IMAGE_ROOTFS}，它指向将成为根文件系统镜像的目录。更多信息见 IMAGE_ROOTFS。

IMAGE_ROOTFS 

根文件系统构建期间，即 do_rootfs 任务期间的位置。此变量不可配置，不要修改。

IMAGE_ROOTFS_ALIGNMENT 

输出镜像文件的对齐大小，单位 Kbytes。大小不是其整数倍时，向上取整至最近的整数倍。默认为“1”，另见 IMAGE_ROOTFS_SIZE。

IMAGE_ROOTFS_EXTRA_SPACE 

镜像额外创建的空闲磁盘空间，单位 Kbytes，默认“0”。在按 IMAGE_ROOTFS_SIZE 的规则确定大小后追加。

适合需要确保镜像安装并运行后仍有指定空闲空间的场景。例如确保 5 Gbytes:

IMAGE_ROOTFS_EXTRA_SPACE = "5242880"

Yocto Project Build Appliance 通过以下设置请求额外 40 Gbytes:

IMAGE_ROOTFS_EXTRA_SPACE = "41943040"

IMAGE_ROOTFS_MAXSIZE 

生成镜像的最大允许大小，单位 kilobytes，超过则构建失败。

比较前会进行多步计算：第一步计算 IMAGE_ROOTFS 目录大小；第二步乘以 IMAGE_OVERHEAD_FACTOR；第三步与 IMAGE_ROOTFS_SIZE 取较大值，再加 IMAGE_ROOTFS_EXTRA_SPACE；第四步若有小数就向上取整，否则直接转换为整数；第五步加上 IMAGE_ROOTFS_ALIGNMENT 再减 1；第六步减去该结果除以 IMAGE_ROOTFS_ALIGNMENT 的余数。这样将第四步结果向上对齐到最近的 IMAGE_ROOTFS_ALIGNMENT 整数倍。

若设置了本变量，就与上述结果比较，与最终镜像类型无关。默认未设置。

必须放入 SD 卡或固定大小分区等有限空间的镜像，建议设置此变量。

IMAGE_ROOTFS_SIZE 

生成镜像的大小，单位 Kbytes。最终大小算法考虑镜像初始磁盘用量、请求大小及额外空闲空间，计算如下:

if (image-du * overhead) < rootfs-size:
    internal-rootfs-size = rootfs-size + xspace
else:
    internal-rootfs-size = (image-du * overhead) + xspace
where:
    image-du = Returned value of the du command on the image.
    overhead = IMAGE_OVERHEAD_FACTOR
    rootfs-size = IMAGE_ROOTFS_SIZE
    internal-rootfs-size = Initial root filesystem size before any modifications.
    xspace = IMAGE_ROOTFS_EXTRA_SPACE

相关信息见 IMAGE_OVERHEAD_FACTOR 和 IMAGE_ROOTFS_EXTRA_SPACE。

IMAGE_TYPEDEP 

指定一种镜像类型对另一种的依赖。以下来自 image-live:

IMAGE_TYPEDEP:live = "ext3"

此设置确保 IMAGE_FSTYPES 包含 live 时先生成 ext3 镜像，因为 live 镜像的一个组件是包含根文件系统的 ext3 分区。

IMAGE_TYPES 

默认支持的完整镜像类型列表：

btrfs
container
cpio
cpio.gz
cpio.lz4
cpio.lzma
cpio.xz
cramfs
erofs
erofs-lz4
erofs-lz4hc
ext2
ext2.bz2
ext2.gz
ext2.lzma
ext3
ext3.gz
ext4
ext4.gz
f2fs
hddimg
iso
jffs2
jffs2.sum
multiubi
squashfs
squashfs-lz4
squashfs-lzo
squashfs-xz
tar
tar.bz2
tar.gz
tar.lz4
tar.xz
tar.zst
ubi
ubifs
wic
wic.bz2
wic.gz
wic.lzma
wic.zst
wicenv

更多信息见 OpenEmbedded-Core (OE-Core) 中的 meta/classes-recipe/image_types*.bbclass。

IMAGE_VERSION_SUFFIX 

默认 IMAGE_NAME 和 KERNEL_ARTIFACT_NAME 的版本后缀部分。默认为 "-${DATETIME}"，也可设为来自外部构建环境的版本字符串，使全部构建产物一致使用该后缀。

IMGDEPLOYDIR 

直接或通过 core-image 继承 image 时，指向部署文件的临时工作区，image 类设置如下:

IMGDEPLOYDIR = "${WORKDIR}/deploy-${PN}-image-complete"

镜像配方应将待部署文件复制到这里，再由该类复制到 DEPLOY_DIR_IMAGE。

IMGMANIFESTDIR 

直接或通过 core-image 继承 image 时，指定保存 JSON 镜像清单的临时区域。清单列出 IMAGE_FSTYPES 定义的各创建任务生成的镜像。 image 类设置如下:

IMGMANIFESTDIR = "${WORKDIR}/image-task-manifest"

INCOMPATIBLE_LICENSE 

以空格分隔的许可证名称列表，名称形式与 LICENSE 相同。全局设置时从构建排除，在镜像配方本地设置时从该镜像排除。

全局设置后，没有其他可选许可证的配方不会构建，单独使用不兼容许可证的软件包会被删除。这通常使构建难以完成，因为无法满足构建时依赖。因此推荐只在需要限制的具体镜像配方中设置，不限制构建过程，但在从软件包组装镜像文件系统时检查许可证。

支持有限的通配符，目前仅允许以下模式：

AGPL-3.0*"：AGPL-3.0-only、AGPL-3.0-or-later
GPL-3.0*：GPL-3.0-only、GPL-3.0-or-later
LGPL-3.0*：LGPL-3.0-only、LGPL-3.0-or-later

若 LICENSE 通过 WITH 指定许可证例外，基础许可证仍会匹配并被禁止。要显式允许 SPDX 许可证例外，必须在 INCOMPATIBLE_LICENSE_EXCEPTIONS 列出。

备注

只有以下设置会定期测试:

INCOMPATIBLE_LICENSE = "GPL-3.0* LGPL-3.0* AGPL-3.0*"

虽然可用其他设置，但可能需要移除对某些组件的依赖，或为其提供替代，才能生成可正常工作的系统镜像。

INCOMPATIBLE_LICENSE_EXCEPTIONS 

以空格分隔的软件包与 SPDX 许可证或许可证例外配对列表，允许使用即使已被 INCOMPATIBLE_LICENSE 禁止的许可证。包与许可证之间用冒号分隔。例如:

INCOMPATIBLE_LICENSE_EXCEPTIONS = "gdbserver:GPL-3.0-only gdbserver:LGPL-3.0-only gcc:GCC-exception-3.1"

INHERIT 

全局继承指定类。类中的匿名函数不在基础配置和各独立配方中执行。构建系统忽略各配方内对此变量的修改。类必须位于 classes-global/ 或 classes/ 子目录。

更多信息见《BitBake 用户手册》的 inherit 配置指令一节。

INHERIT_DISTRO 

列出在发行版层面继承的类，通常无需修改。类必须位于 classes-global/ 或 classes/ 子目录。

meta/conf/distro/defaultsetup.conf 中的默认值为:

INHERIT_DISTRO ?= "debian devshell sstate license remove-libtool create-spdx"

INHIBIT_AUTOTOOLS_DEPS 

阻止 autotools* 自动添加默认构建时依赖。继承此类时，通常向 DEPENDS 添加 autoconf-native、automake-native、libtool-native 和 libtool-cross，支持相应构建过程。

若要阻止自动添加，可设置:

INHIBIT_AUTOTOOLS_DEPS = "1"

默认值为空。设为“0”不会取消禁止行为，只有空字符串才会取消。

INHIBIT_DEFAULT_DEPS 

阻止向 DEPENDS 添加默认依赖，即 C 编译器和标准 C 库 libc。通常用于无需 C 编译器编译的配方。设为“1”启用。

INHIBIT_DEFAULT_RUST_DEPS 

阻止 rust 自动添加默认构建时依赖。继承此类时，通常向 DEPENDS 添加 rust-native 和 ${RUSTLIB_DEP}（后者仅在交叉编译时加入），支持相应构建过程。

若要阻止自动添加，可设置:

INHIBIT_DEFAULT_RUST_DEPS = "1"

默认值为空。设为“0”不会取消禁止行为，只有空字符串才会取消。

INHIBIT_PACKAGE_DEBUG_SPLIT 

阻止打包期间拆分调试信息。默认在 do_package 中拆分，方式见 PACKAGE_DEBUG_SPLIT_STYLE。

要阻止拆分，设置:

INHIBIT_PACKAGE_DEBUG_SPLIT = "1"

INHIBIT_PACKAGE_STRIP 

设为“1”时，不剥离输出包中的二进制文件，同时使 -dbg 包不包含源码文件。

默认剥离二进制文件，将调试符号放入 ${PN}-dbg。因此，一般计划调试时不应设置此变量。

INHIBIT_SYSROOT_STRIP 

设为“1”时，阻止剥离最终系统根目录中的二进制文件。默认会执行剥离，配方显式设为“1”后禁用。

使用时需包含 staging，该类的 sys_strip() 检查此变量并处理。

备注

此变量只用于少见特殊场景。例如使用外部 GCC 工具链构建裸机固件，即使工具链二进制文件可剥离，构建所需的其他文件也可能不可剥离。

INHIBIT_UPDATERCD_BBCLASS 

阻止 update-rc.d 自动安装和注册 SysV 初始化脚本。继承此类时，通常为 INITSCRIPT_PACKAGES 所列软件包安装并注册脚本，确保服务在传统 SysV 初始化系统的适当运行级别启动和停止。

若要阻止自动添加，可设置:

INHIBIT_UPDATERCD_BBCLASS = "1"

默认值为空。设为“0”不会取消禁止行为，只有空字符串才会取消。

INIT_MANAGER 

指定系统初始化管理器，可选：

sysvinit
systemd
mdev-busybox

sysvinit 选择传统 UNIX 初始化系统 SysVinit。这是 Poky 的默认选择，搭配 Udev 设备管理器，见“选择设备管理器”。

systemd 选择 systemd，附带 udev。

mdev-busybox 选择更简单的 BusyBox init 与 BusyBox mdev。它最简单轻量，可能最适合 CPU 较慢、内存有限的低端系统。

具体实现是将 conf/distro/include/init-manager-${INIT_MANAGER}.inc 加入全局配置。详情见 meta/conf/distro/include/init-manager-*.inc，以及《Yocto Project 开发任务手册》的“选择初始化管理器”一节。

INITRAMFS_DEPLOY_DIR_IMAGE 

指定 do_bundle_initramfs 获取 INITRAMFS_IMAGE 的部署目录。 kernel 默认设为 ${DEPLOY_DIR_IMAGE}。只有通过 INITRAMFS_MULTICONFIG 从独立多配置构建 Initramfs 时才应修改。

INITRAMFS_FSTYPES 

启动使用的 Initramfs 输出镜像格式，支持类型与 IMAGE_FSTYPES 相同。

OpenEmbedded-Core (OE-Core) 的 meta/conf/bitbake.conf 默认设为 cpio.gz。Linux 内核的 Initramfs 机制与 initrd 不同，要求可选压缩的 cpio 归档。

INITRAMFS_IMAGE 

指定构建 Initramfs 镜像的配方 PROVIDES 名称。它使所用根文件系统配方（例如 core-image-sato）额外依赖并构建该配方。提供的 Initramfs 配方应将 IMAGE_FSTYPES 设为 INITRAMFS_FSTYPES。

Initramfs 提供早期系统初始化所需的临时根文件系统，例如加载定位并挂载真正根文件系统所需的模块。

备注

示例见 OpenEmbedded-Core (OE-Core) 的 meta/recipes-core/images/core-image-minimal-initramfs.bb。要使用该示例，将此变量设为 core-image-minimal-initramfs。

更多用法见 meta/conf/templates/default/local.conf.sample.extended、 image 和 kernel。

默认值为空，此时不构建 Initramfs 镜像。

INITRAMFS_IMAGE_BUNDLE 可将生成镜像嵌入内核。创建方法见《Yocto Project 开发任务手册》的 “构建初始 RAM 文件系统（Initramfs）镜像”一节。

INITRAMFS_IMAGE_BUNDLE 

控制内核编译时是否通过额外的 do_bundle_initramfs 步骤，将 INITRAMFS_IMAGE 配方输出与内核合并为单个二进制文件，利用内核 CONFIG_INITRAMFS_SOURCE 功能。

备注

捆绑将 Initramfs 代码与 GPLv2 的 Linux 内核二进制文件合并，因此其中只能包含兼容 GPLv2 的软件。

备注

额外编译步骤可避免 Initramfs 包含内核模块时形成循环依赖： Initramfs 为获得模块而依赖内核，而内核又因嵌入 Initramfs 而依赖其配方。

合并后的二进制文件放入 Build Directory 的 tmp/deploy。在配置文件中设为“1”，即可生成内嵌指定 Initramfs 的内核镜像:

INITRAMFS_IMAGE_BUNDLE = "1"

kernel 默认设为空字符串:

INITRAMFS_IMAGE_BUNDLE ?= ""

备注

必须在配置文件中设置，不能在配方文件中设置。

更多信息见 local.conf.sample.extended。创建方法见《Yocto Project 开发任务手册》的 “构建初始 RAM 文件系统（Initramfs）镜像”一节。

INITRAMFS_IMAGE_NAME 

此值需要与 IMAGE_LINK_NAME 同步，但使用 INITRAMFS_IMAGE 而非 IMAGE_BASENAME。默认设置如下：

INITRAMFS_IMAGE_NAME ?= "${@['${INITRAMFS_IMAGE}${IMAGE_MACHINE_SUFFIX}', ''][d.getVar('INITRAMFS_IMAGE') == '']}"

即，设置 INITRAMFS_IMAGE 后，根据它和 IMAGE_MACHINE_SUFFIX 确定名称。

INITRAMFS_LINK_NAME 

初始 RAM 文件系统镜像的链接名，在 meta/classes-recipe/kernel-artifact-names.bbclass 中设置:

INITRAMFS_LINK_NAME ?= "initramfs-${KERNEL_ARTIFACT_LINK_NAME}"

同文件中的 KERNEL_ARTIFACT_LINK_NAME 值如下:

KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}"

更多信息见 MACHINE。

INITRAMFS_MAXSIZE 

Initramfs 最大允许大小，单位 Kbytes，超过则构建失败。

比较前的计算步骤与 IMAGE_ROOTFS_MAXSIZE 相同，详见该条目。因此比较的是计算结果，与压缩等最终镜像类型无关。默认值在 meta/conf/bitbake.conf 设置。

INITRAMFS_MULTICONFIG 

定义 kernel 用于创建多配置依赖的 multiconfig，允许内核捆绑来自独立多配置的 INITRAMFS_IMAGE，应与 INITRAMFS_DEPLOY_DIR_IMAGE 配合使用。

更多信息见《Yocto Project 开发任务手册》的 “嵌入来自独立 Multiconfig 的 Initramfs 镜像”一节。

INITRAMFS_NAME 

初始 RAM 文件系统镜像的基本名称，在 meta/classes-recipe/kernel-artifact-names.bbclass 中设置:

INITRAMFS_NAME ?= "initramfs-${KERNEL_ARTIFACT_NAME}"

更多信息见 KERNEL_ARTIFACT_NAME。

INITRD 

要连接并用作初始 RAM 磁盘 initrd 的文件系统镜像列表。这是 image-live 使用的可选变量。

INITRD_IMAGE 

构建 live 可启动镜像，即 IMAGE_FSTYPES 包含 live 时，指定提供初始 RAM 磁盘镜像的配方。默认 core-image-minimal-initramfs。

更多信息见 image-live。

INITSCRIPT_NAME 

初始化脚本安装到 ${sysconfdir}/init.d 后的文件名。配方使用 update-rc.d 时，此变量必需。

INITSCRIPT_PACKAGES 

包含初始化脚本的软件包列表。指定多个包时，应为其他 INITSCRIPT_* 变量追加软件包名覆盖。

用于 update-rc.d，可选，默认为 PN。

INITSCRIPT_PARAMS 

传给 update-rc.d 的选项，例如:

INITSCRIPT_PARAMS = "start 99 5 2 . stop 20 0 1 6 ."

上例脚本顺序为 99，在运行级别 2 和 5 启动，在 0、1、6 停止。

update-rc.d 设置默认值为 defaults。参数直接传给命令，有效参数见 update-rc.d。

INSANE_SKIP 

指定配方中特定软件包应跳过的质量检查。例如跳过主包中的 .so 符号链接检查，可添加以下设置。必须使用软件包名称覆盖，此处为 ${PN}:

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

有效检查列表见“insane”一节。

INSTALL_TIMEZONE_FILE 

tzdata 默认打包 /etc/timezone。在配置层面将此变量设为“0”可禁用。

IPK_FEED_URIS 

使用 IPK 后端且目标启用软件包管理时，用此变量配置目标 opkg，使其指向指定服务器的软件包源。建立源后，可在运行时安装或升级软件包。

KARCH 

组装配置时使用的内核架构，本版本支持：

powerpc
i386
x86_64
arm
qemu
mips

在 BSP 描述中定义。

KBRANCH 

构建时显式标识要验证、打补丁和配置的内核分支的正则表达式。必须设置它，以确保使用所需的准确分支。

值在内核配方及追加文件中设置。例如 linux-yocto_4.12 的配方 meta/recipes-kernel/linux/linux-yocto_4.12.bb 中为:

KBRANCH ?= "standard/base"

追加文件还可指定特定机器或硬件的分支，位于对应 BSP 层。例如 Beaglebone 和通用 32/64 位 IA 机器在 meta-yocto-bsp 中使用 meta-yocto-bsp/recipes-kernel/linux/linux-yocto_6.1.bbappend，相关设置如下:

KBRANCH:genericx86  = "v6.1/standard/base"
KBRANCH:genericx86-64  = "v6.1/standard/base"
KBRANCH:beaglebone-yocto = "v6.1/standard/beaglebone"

这些语句标识构建各受支持 BSP 时所用分支。

KBUILD_DEFCONFIG 

与 kernel-yocto 配合时，指定树内内核配置文件。

通常 defconfig 像补丁和配置片段一样放在自己的层中，即树外文件。若要使用内核树本身的 defconfig，可通过此变量指定。在内核配方的追加文件中使用以下形式:

KBUILD_DEFCONFIG:<machine> ?= "defconfig_file"

以下 raspberrypi2 MACHINE 使用 bcm2709_defconfig:

KBUILD_DEFCONFIG:raspberrypi2 = "bcm2709_defconfig"

也可在追加文件中使用:

KBUILD_DEFCONFIG:pn-linux-yocto ?= "defconfig_file"

更多信息见《Yocto Project Linux 内核开发手册》的使用树内 defconfig 一节。

KCONF_AUDIT_LEVEL 

继承 kernel-yocto 且 KMETA_AUDIT 非空时，控制是否报告与用户指定值不同的内核配置。整数值默认为 1：

0：不报告。
1：以警告报告，若设置 KMETA_AUDIT_WERROR 则报错。
2：do_kernel_configme 未能生成 .config 时，输出含错误的 merge_config_build.log 内容，而不只是提供路径。

详情见 kernel-yocto 类，以及 yocto-kernel-tools 中的 symbol_why.py。

KCONF_BSP_AUDIT_LEVEL 

继承 kernel-yocto 且 KMETA_AUDIT 非空时，可报告以下问题：

用户指定的内核配置未进入最终配置。
多个输入文件为同一配置指定不同值。

整数值默认为 0：

0：不报告。
1：报告未进入最终配置的选项，不限当前 ARCH。
2：报告未进入最终配置的选项，严格限于当前 ARCH。
3：除级别 2 的问题外，还报告多输入文件定义不同值的选项。

值为 1、2、3 且设置 KMETA_AUDIT_WERROR 时会报错。

详情见 kernel-yocto 类，以及 yocto-kernel-tools 中的 symbol_why.py。

KCONFIG_CONFIG_ROOTDIR 

为使用 cml1 的配方覆盖 .config 文件默认位置。

KCONFIG_MODE 

与 kernel-yocto 一起使用，指定 defconfig 未声明选项的处理方式。有效值为:

KCONFIG_MODE = "alldefconfig"
KCONFIG_MODE = "allnoconfig"

alldefconfig 对未显式指定选项使用 Kconfig 默认值； allnoconfig 则禁用这些选项。未设置此变量时，按 allnoconfig 处理 defconfig。

要生成兼容 allnoconfig 的配置，可复制正常 Linux 内核构建的 .config，重命名为 defconfig，通过自己的层放入内核 ${WORKDIR}，无需显式设置本变量。

兼容 alldefconfig 的配置可通过 do_savedefconfig 生成，同样通过层放入 ${WORKDIR}，并显式设置:

KCONFIG_MODE = "alldefconfig"

KERNEL_ALT_IMAGETYPE 

指定在 KERNEL_IMAGETYPE 和 KERNEL_IMAGETYPES 之外额外创建的另一种内核镜像类型。

KERNEL_ARTIFACT_NAME 

指定全部内核构建产物名称，可通过修改此变量更改。 meta/classes-recipe/kernel-artifact-names.bbclass 中默认值为:

KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}${IMAGE_MACHINE_SUFFIX}${IMAGE_VERSION_SUFFIX}"

另见 PKGE、PKGV、PKGR、IMAGE_MACHINE_SUFFIX 和 IMAGE_VERSION_SUFFIX。

KERNEL_CLASSES 

kernel 应继承的内核镜像类型定义类列表。通常通过追加来启用扩展类型，也可注册自定义内核镜像类型。

KERNEL_CONSOLE 

保存内核命令行 console 参数，可用于 Wic 镜像的 wks 描述等位置。

默认取 SERIAL_CONSOLES 的第一个控制台设备和设置，如果没有则使用 ttyS0,115200。

层或 BSP 指定的某些 KERNEL_FEATURES 缺少配置片段时，内核配置和构建会报错停止。

可在 configuration file 中设置，将错误变为警告:

KERNEL_DANGLING_FEATURES_WARN_ONLY = "1"

仍会提醒可能出现运行时问题，但允许继续配置和构建。

KERNEL_DEBUG_TIMESTAMPS 

设为“1”启用内核构建期间的时间戳功能。为保证可复现性，默认“0”禁用。

KERNEL_DEPLOY_DEPEND 

控制镜像配方对内核的依赖，默认 virtual/kernel:do_deploy。小型 initramfs 或其他无需内核的镜像，可在镜像配方中设为空字符串。

KERNEL_DEVICETREE 

指定生成的 Linux 设备树 .dtb 文件名称。

备注

仍兼容指定设备树完整路径的旧方式，但推荐只提供 .dtb 文件名。

需要继承 kernel-devicetree。

KERNEL_DEVICETREE_BUNDLE 

设为“1”时，将 Linux 内核与设备树二进制文件捆绑为单个文件。目前仅支持 32 位 arm 架构。 kernel-devicetree 默认设为“0”。

KERNEL_DTB_LINK_NAME 

内核设备树二进制文件（DTB）的链接名，在 meta/classes-recipe/kernel-artifact-names.bbclass 中设置:

KERNEL_DTB_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}"

同文件中的 KERNEL_ARTIFACT_LINK_NAME 值为:

KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}"

更多信息见 MACHINE。

KERNEL_DTB_NAME 

内核设备树二进制文件（DTB）的基本名称，在 meta/classes-recipe/kernel-artifact-names.bbclass 中设置:

KERNEL_DTB_NAME ?= "${KERNEL_ARTIFACT_NAME}"

更多信息见 KERNEL_ARTIFACT_NAME。

KERNEL_DTBDEST 

供 kernel-devicetree 修改 DTB 安装目录。 kernel 默认设为 ${KERNEL_IMAGEDEST}。

KERNEL_DTBVENDORED 

供 kernel-devicetree 控制 DTB 安装时是否保留厂商子目录。 false 表示忽略，true 表示保留。 kernel 默认设为 false。

KERNEL_DTC_FLAGS 

生成设备树时，通过 DTC_FLAGS 环境变量传给内核构建系统的 dtc 标志。需继承 kernel-devicetree。

KERNEL_EXTRA_ARGS 

编译内核时，构建系统传给 make 的额外命令行参数。

KERNEL_FEATURES 

包含额外内核元数据。默认 BSP Metadata 通过 KMACHINE 和 KBRANCH 提供，本变量可在内核配方或追加文件中为全部或特定 BSP 加入更多元数据。

添加内容包括配置片段和功能描述，后者通常包含补丁及配置片段。通常按机器覆盖，提供已验证但可选的内核配置与功能集合。

以下来自 linux-yocto-rt_4.12，为全部 BSP 加入 netfilter 和 taskstats，为全部 QEMU 机器加入 virtio，最后两行针对具体机器添加配置:

KERNEL_EXTRA_FEATURES ?= "features/netfilter/netfilter.scc features/taskstats/taskstats.scc"
KERNEL_FEATURES:append = " ${KERNEL_EXTRA_FEATURES}"
KERNEL_FEATURES:append:qemuall = " cfg/virtio.scc"
KERNEL_FEATURES:append:qemux86 = " cfg/sound.scc cfg/paravirt_kvm.scc"
KERNEL_FEATURES:append:qemux86-64 = " cfg/sound.scc"

KERNEL_FIT_LINK_NAME 

内核 FIT 镜像的链接名，在 meta/classes-recipe/kernel-artifact-names.bbclass 中设置:

KERNEL_FIT_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}"

同文件中的 KERNEL_ARTIFACT_LINK_NAME 值为:

KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}"

更多信息见 MACHINE。

KERNEL_FIT_NAME 

内核 FIT 镜像的基本名称，在 meta/classes-recipe/kernel-artifact-names.bbclass 中设置:

KERNEL_FIT_NAME ?= "${KERNEL_ARTIFACT_NAME}"

更多信息见 KERNEL_ARTIFACT_NAME。

KERNEL_IMAGE_LINK_NAME 

内核镜像的链接名，在 meta/classes-recipe/kernel-artifact-names.bbclass 中设置:

KERNEL_IMAGE_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}"

同文件中的 KERNEL_ARTIFACT_LINK_NAME 值为:

KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}"

更多信息见 MACHINE。

KERNEL_IMAGE_MAXSIZE 

内核镜像文件最大允许大小，单位 kibibytes。设置后，do_sizecheck 检查 KERNEL_IMAGETYPES 的全部镜像，任何超限镜像产生警告，只有全部都过大时才失败。

适用于内核存储空间有限的目标。默认未设置，即不检查大小。

KERNEL_IMAGE_NAME 

内核镜像的基本名称，在 meta/classes-recipe/kernel-artifact-names.bbclass 中设置:

KERNEL_IMAGE_NAME ?= "${KERNEL_ARTIFACT_NAME}"

更多信息见 KERNEL_ARTIFACT_NAME。

KERNEL_IMAGE_STRIP_EXTRA_SECTIONS 

指定内核相关 do_strip 任务从 vmlinux 镜像剥离的节，例如:

KERNEL_IMAGE_STRIP_EXTRA_SECTIONS = ".comment .note.* .debug"

KERNEL_IMAGETYPE 

设备所需的内核类型，通常由机器配置设置，默认 zImage，构建内核时作为 make 的目标传入。

额外类型使用 KERNEL_IMAGETYPES。

KERNEL_IMAGETYPES 

除 KERNEL_IMAGETYPE 之外要构建的内核镜像类型列表，通常由机器配置设置。

KERNEL_LOCALVERSION 

向内核镜像版本追加字符串，对应内核 CONFIG_LOCALVERSION。

仅适用于继承 kernel 且未自行设置本地版本的内核配方，因此对 linux-yocto 内核无效。

KERNEL_MODULE_AUTOLOAD 

列出启动时需要自动加载的内核模块。

备注

替代已弃用的 module_autoload。

可在内核或树外模块配方能识别的位置设置，例如机器配置、发行版配置、配方追加文件或配方本身。语法为:

KERNEL_MODULE_AUTOLOAD += "module_name1 module_name2 module_name3"

构建系统据此填充 /etc/modules-load.d/modname.conf，每行一个模块。常见用法:

KERNEL_MODULE_AUTOLOAD += "module_name"

要用 modprobe.d 语法填充 modname.conf，见 KERNEL_MODULE_PROBECONF。

KERNEL_MODULE_INSTALL_PREFIX 

继承 module 时，指定目标上内核模块的安装目录。

KERNEL_MODULE_PROBECONF 

列出预期具有 module_conf_modname 值的模块，这些值指定各模块配置。提供方式见 module_conf_*。

KERNEL_PACKAGE_NAME 

内核软件包基本名称，例如 kernel-modules、kernel-image、kernel-dbg 中的 kernel。 kernel 默认设为 kernel。

KERNEL_PATH 

内核源码位置，module 将其设为 STAGING_KERNEL_DIR。用法见《Yocto Project Linux 内核开发手册》的 “集成树外模块”一节。

为尽可能兼容树外驱动的模块构建，系统也识别相同含义的 KERNEL_SRC。两者都是外部 Makefile 指向内核源码目录的常见变量。

KERNEL_SPLIT_MODULES 

继承 kernel-module-split 时，控制模块独立打包或合并到单包。某些场景希望使用包含全部内核模块的 KERNEL_PACKAGE_NAME 整体包以加快安装。

默认为 1，即每模块一个包；其他任何值都会生成包含全部模块的单个整体包。

备注

设为 0 时，仍可将 kernel-modules 加入 IMAGE_INSTALL 一次安装全部模块，假定 KERNEL_PACKAGE_NAME 为 kernel-modules。原理是创建占位 kernel-modules 包，依赖每个独立模块包。

KERNEL_SRC 

内核源码位置，module 将其设为 STAGING_KERNEL_DIR。用法见《Yocto Project Linux 内核开发手册》的 “集成树外模块”一节。

为尽可能兼容树外驱动的模块构建，系统也识别相同含义的 KERNEL_PATH。两者都是外部 Makefile 指向内核源码目录的常见变量。

KERNEL_STRIP 

指定剥离内核二进制文件所用的 strip 命令，通常是 GNU binutils strip 或 llvm-strip。

KERNEL_TOOLCHAIN 

指定构建 Linux 内核的工具链，可选值与 PREFERRED_TOOLCHAIN_TARGET 相同。

KERNEL_VERSION 

从内核源码 version.h 或 utsrelease.h 提取的内核版本。只有内核配置完成后才生效，因此无法在配置前的上下文中使用。

KERNELDEPMODDEPEND 

指定是否需要使用 PKGDATA_DIR 引用的数据，不控制数据是否存在，只控制是否使用。 Initramfs 不需要这些数据时，可在其配方中设置，避免潜在循环依赖。

KFEATURE_DESCRIPTION 

配置片段的简短说明，用于描述该片段的 .scc 文件。例如 smp.scc 描述启用 SMP:

define KFEATURE_DESCRIPTION "Enable SMP"

KMACHINE 

内核所认识的机器名称，有时不同于构建系统名称。例如构建系统的 core2-32-intel-common 在 Linux Yocto 内核中称为 intel-core2-32。此变量用于在两种名称间映射。

映射位于 Yocto Linux 内核的 meta 分支。例如 common/recipes-kernel/linux/linux-yocto_3.19.bbappend:

LINUX_VERSION:core2-32-intel-common = "3.19.0"
COMPATIBLE_MACHINE:core2-32-intel-common = "${MACHINE}"
SRCREV_meta:core2-32-intel-common = "8897ef68b30e7426bc1d39895e71fb155d694974"
SRCREV_machine:core2-32-intel-common = "43b9eced9ba8a57add36af07736344dcc383f711"
KMACHINE:core2-32-intel-common = "intel-core2-32"
KBRANCH:core2-32-intel-common = "standard/base"
KERNEL_FEATURES:append:core2-32-intel-common = " ${KERNEL_FEATURES_INTEL_COMMON}"

该语句表示内核使用 intel-core2-32，构建系统使用 core2-32-intel-common。

KMETA_AUDIT 

继承 kernel-yocto 时，启用或禁用内核配置审计。默认 yes，即启用，设为空字符串则禁用。

KMETA_AUDIT_WERROR 

继承 kernel-yocto，且本变量与 KMETA_AUDIT 均非空时，检测到内核配置问题将报错而不仅是警告。详情见 KCONF_AUDIT_LEVEL 和 KCONF_BSP_AUDIT_LEVEL。

KMETA_CONFIG_FEATURES 

定义 kernel-yocto 启用的功能，支持：

prefer-modules：内核配置按如下方式定义时，优先设为 m，而非默认 y:
```
CONFIG_FOO=y # OVERRIDE:$MODULE_OR_Y
```

默认值为空字符串。

KTYPE 

组装配置所用的内核类型，linux-yocto 配方定义 standard、tiny、preempt-rt。更多信息见《Yocto Project Linux 内核开发手册》的 “内核类型”一节。

在 BSP 描述中定义，其值必须匹配内核配方的 LINUX_KERNEL_TYPE。

LABELS 

自动配置的目标列表。用法见 grub-efi。

LAYERDEPENDS 

此层依赖的层列表，以空格分隔，可在层名后附加所需版本。例如:

LAYERDEPENDS_mylayer = "anotherlayer (=3)"

上例把 anotherlayer 的版本 3 与 LAYERVERSION_anotherlayer 比较。缺少依赖或指定版本不完全匹配时会报错。用于 conf/layer.conf，必须以特定层名为后缀，例如 LAYERDEPENDS_mylayer。

LAYERDIR 

在 layer.conf 中提供当前层路径。文件之外不可用，引用在该文件解析完成时立即展开。

LAYERDIR_RE 

见《BitBake 手册》的 LAYERDIR_RE。

LAYERRECOMMENDS 

推荐与本层一起使用的层列表，以空格分隔。可在层名末尾添加推荐版本，例如:

LAYERRECOMMENDS_mylayer = "anotherlayer (=3)"

上例把 anotherlayer 的版本 3 与 LAYERVERSION_anotherlayer 比较。用于 conf/layer.conf，必须以特定层名为后缀，例如 LAYERRECOMMENDS_mylayer。

LAYERSERIES_COMPAT 

见《BitBake 手册》的 LAYERSERIES_COMPAT。

LAYERVERSION 

可选地用单个数字指定层版本，供其他层的 LAYERDEPENDS 指定版本依赖。用于 conf/layer.conf，必须以特定层名为后缀，例如 LAYERVERSION_mylayer。

LD 

运行 链接器 所需的最小命令及参数。

LDFLAGS 

传给链接器的标志，导出为环境变量，在编译步骤对软件可见。默认根据构建对象初始化：

目标使用 TARGET_LDFLAGS。
构建主机（-native）使用 BUILD_LDFLAGS。
SDK（nativesdk-）使用 BUILDSDK_LDFLAGS。

LEAD_SONAME 

配方打包多个库时，指定 debian 命名政策应采用的主要已编译库文件，即 .so 文件。与该类配合使用。

LIC_FILES_CHKSUM 

配方源码中许可证文本的校验和，用于跟踪许可文本变化。文本变化时触发构建失败，让开发者有机会审查许可变更。

除 LICENSE 为 CLOSED 外，所有配方必须定义此变量。

更多信息见《Yocto Project 开发任务手册》的 “跟踪许可证变化”一节。

LICENSE 

OpenEmbedded 配方的必需字段，应包含描述源码许可的 SPDX License Expression。规则包括：

可以选择许可证时，用 OR 分隔名称。
不同源码部分适用不同许可证时，用 AND 分隔。
所有名称必须是有效的 SPDX 许可证标识符。
不在 SPDX 许可证列表中的许可证，必须使用 LicenseRef- 前缀。

例如:

LICENSE = "LGPL-2.1-only OR GPL-3.0-only"
LICENSE = "MPL-1.0 AND LGPL-2.1-only"
LICENSE = "GPL-2.0-or-later"

第一例来自 Qt，可选择按 LGPL 2.1 或 GPL 3 分发；第二例来自 Cairo，不同源码部分由两个许可证覆盖；最后一个来自 sysstat，只有单一许可证。

也可按软件包指定，处理输出各组件许可不同的情况。例如代码为 GPLv2，附带文档为 GNU Free Documentation License 1.2:

LICENSE = "GFDL-1.2 AND GPL-2.0-only"
LICENSE:${PN} = "GPL-2.0.only"
LICENSE:${PN}-doc = "GFDL-1.2"

备注

LICENSE 必须搭配对应的 LIC_FILES_CHKSUM。

LICENSE_CREATE_PACKAGE 

设为“1”时，为每个配方生成额外的 ${PN}-lic 包，并加入 RRECOMMENDS:${PN}。

该包在 /usr/share/licenses 创建名为 ${PN} 的目录，安装包含许可和版权信息的文件。这些文件包括 meta/common-licenses 中匹配配方 LICENSE 的许可证副本，以及 LIC_FILES_CHKSUM 标记为许可证文本的文件副本。

相关信息见 COPY_LIC_DIRS、COPY_LIC_MANIFEST，以及《Yocto Project 开发任务手册》的 “提供许可证文本”一节。

LICENSE_FLAGS 

为配方指定额外标志，必须通过 LICENSE_FLAGS_ACCEPTED 允许后才能构建。多个标志以空格分隔。

它独立于 LICENSE，通常标记在商业产品中使用时可能需要额外许可的配方。更多信息见“启用商业许可配方”。

LICENSE_FLAGS_ACCEPTED 

列出允许的许可证标志，使配方 LICENSE_FLAGS 中这些标志不阻止构建。更多信息见《Yocto Project 开发任务手册》的 “启用商业许可配方”。

LICENSE_FLAGS_DETAILS 

为 LICENSE_FLAGS 中的标志补充详情。未通过 LICENSE_FLAGS_ACCEPTED 接受时，错误消息会包含这些说明。

例如带 EULA 的配方可设置:

LICENSE_FLAGS = "FooBar-EULA"
LICENSE_FLAGS_DETAILS[FooBar-EULA] = "For further details, see https://example.com/eula."

若 Foobar-EULA 不在接受列表中，会得到更有帮助的消息:

Has a restricted license 'FooBar-EULA' which is not listed in your LICENSE_FLAGS_ACCEPTED.
For further details, see https://example.com/eula.

LICENSE_PATH 

构建中使用的额外许可证路径。默认由 COMMON_LICENSE_DIR 指向通用许可文本目录，本变量可将搜索位置扩展到其他区域:

LICENSE_PATH += "path-to-additional-common-licenses"

LINUX_KERNEL_TYPE 

组装配置使用的内核类型，linux-yocto 定义 standard、tiny、preempt-rt。更多信息见《Yocto Project Linux 内核开发手册》的 “内核类型”一节。

未指定时默认为 standard。与 KMACHINE 一起形成内核工具的搜索参数，以在内核 Metadata 中找到适当描述，构建源码和配置。

LINUX_VERSION 

所构建 Linux 内核镜像基于 kernel.org 的版本，在内核配方中定义。例如 meta/recipes-kernel/linux 中的 linux-yocto-3.4.bb:

LINUX_VERSION ?= "3.4.24"

此变量用于定义配方 PV:

PV = "${LINUX_VERSION}+git"

LINUX_VERSION_EXTENSION 

编译进 Linux 内核版本字符串的扩展，在内核配方中定义。例如 linux-yocto 配方均设置为:

LINUX_VERSION_EXTENSION ?= "-yocto-${LINUX_KERNEL_TYPE}"

实际设置内核 CONFIG_LOCALVERSION，通过 uname 可见。假设使用上述值，输出例如:

$ uname -r
3.7.0-rc8-custom

LOCALE_PATHS 

以空白分隔的路径列表，拆分软件包期间扫描这些位置生成 -locale 包，默认包含 ${datadir}/locale。

LOCALE_UTF8_IS_DEFAULT 

设置后，未显式编码的区域设置名（例如 en_US）总是使用 UTF-8，非 UTF-8 则重命名为 en_US.ISO-8859-1 等形式。否则按 Glibc 的 SUPPORTED 文件指定编码。不支持预编译区域设置。

LOG_DIR 

构建系统写入总体日志的目录，默认为 ${TMPDIR}/log。各任务专用日志目录见 T。

LTO 

定义 lto 发行版功能的专用标志，追加到 TARGET_LDFLAGS，为链接器添加链接时优化选项。

MACHINE 

指定镜像的目标设备，可通过两种方式定义：

使用 machine/ 片段：

$ bitbake-config-build enable-fragment machine/<MACHINE>

将 <MACHINE> 替换为机器名。

在 Build Directory 的 build/conf/local.conf 中设置。

其值对应同名机器配置文件，用于设置机器专用配置。例如 qemux86 对应 OpenEmbedded-Core (OE-Core) 的 meta/conf/machine/qemux86.conf。

Yocto Project 附带支持以下机器:

MACHINE ?= "qemuarm"
MACHINE ?= "qemuarm64"
MACHINE ?= "qemumips"
MACHINE ?= "qemumips64"
MACHINE ?= "qemuppc"
MACHINE ?= "qemux86"
MACHINE ?= "qemux86-64"
MACHINE ?= "genericx86"
MACHINE ?= "genericx86-64"
MACHINE ?= "beaglebone"

最后五个是 meta-yocto-bsp 层提供的参考硬件开发板。

备注

添加额外 BSP 层会增加 MACHINE 的可选值。

MACHINE_ARCH 

机器专用架构名称，由 MACHINE 或 TUNE_PKGARCH 自动设置，不应手动编辑。

MACHINE_ESSENTIAL_EXTRA_RDEPENDS 

镜像必须安装的机器专用软件包列表，构建依赖它们存在，且它们是机器启动必需的。影响基于 packagegroup-core-boot 的镜像，包括 core-image-minimal。

类似 MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS，但对这些包建立构建依赖，列表项不存在时镜像无法构建。

例如启动时必须执行 example-init 初始化硬件，可在机器 .conf 中设置:

MACHINE_ESSENTIAL_EXTRA_RDEPENDS += "example-init"

MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS 

推荐安装的机器专用软件包列表。构建不依赖它们存在，但这些功能是机器启动必需的。影响基于 packagegroup-core-boot 的镜像，包括 core-image-minimal。

与 MACHINE_ESSENTIAL_EXTRA_RDEPENDS 不同，缺少列表中的包仍可构建。常用于必需内核模块，因为功能可能直接编入内核，此时不会生成模块包。

例如机器必须有触摸屏驱动才能使用，驱动可能编为模块或内置。希望模块形式时安装，但内置时也能构建成功。假设模块包为 kernel-module-ab123，可在机器 .conf 中设置:

MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-module-ab123"

备注

此例的 kernel-module-ab123 配方需要显式设置 PACKAGES，确保 BitBake 不用内核配方的 PACKAGES_DYNAMIC 满足依赖。

机器必需功能的例子包括闪存、屏幕、键盘、鼠标或触摸屏驱动，具体取决于机器。

MACHINE_EXTRA_RDEPENDS 

镜像需要安装、但不是启动必需的机器专用包列表。功能更完整的镜像在构建时依赖这些包存在。

影响所有基于 packagegroup-base 的镜像，不包括 core-image-minimal 和 core-image-full-cmdline。

类似 MACHINE_EXTRA_RRECOMMENDS，但建立构建依赖，缺包时无法构建。

例如机器 WiFi 不是启动必需，但完整镜像希望启用它。固件包始终应存在，因此可强制依赖。假设名称为 wifidriver-firmware，在机器 .conf 中设置:

MACHINE_EXTRA_RDEPENDS += "wifidriver-firmware"

MACHINE_EXTRA_RRECOMMENDS 

镜像可安装、但不是启动必需的机器专用包列表，构建不依赖这些包存在。

只影响基于 packagegroup-base 的镜像，不包括 core-image-minimal 和 core-image-full-cmdline。

类似 MACHINE_EXTRA_RDEPENDS，但缺包时仍可构建。

例如完整镜像希望启用非启动必需的 WiFi，但驱动编入内核时不会生成模块包，此时仍应允许构建成功。假设模块包为 kernel-module-examplewifi，在机器 .conf 中设置:

MACHINE_EXTRA_RRECOMMENDS += "kernel-module-examplewifi"

MACHINE_FEATURES 

指定 MACHINE 硬件能支持的功能列表。启用相关信息见 DISTRO_FEATURES、COMBINED_FEATURES 和 IMAGE_FEATURES。

Yocto Project 附带支持的列表见“机器功能”一节。

MACHINE_FEATURES_DEFAULTS 

构建系统提供的默认机器功能列表，以空格分隔。不应直接修改，应通过 MACHINE_FEATURES_OPTED_OUT 禁用默认功能。

更多信息见默认功能。

MACHINE_FEATURES_OPTED_OUT 

以空格分隔，列出退出 MACHINE_FEATURES_DEFAULTS 的功能。

也可设为 *，退出全部默认功能:

MACHINE_FEATURES_OPTED_OUT = "*"

更多信息见默认功能。

MACHINEOVERRIDES 

适用于当前机器的冒号分隔覆盖列表，默认包含 MACHINE。可扩展以添加更多覆盖。例如 QEMU 模拟的 qemuarm、qemux86 等机器包含 meta/conf/machine/include/qemu.inc，在前面添加:

MACHINEOVERRIDES =. "qemuall:"

这样可以为全部 QEMU 机器覆盖变量，例如 connman-conf 配方中:

SRC_URI:append:qemuall = " file://wired.config \
    file://wired-setup \
    "

底层机制只是将此变量纳入 OVERRIDES 的默认值。

MAINTAINER 

发行版维护者邮箱。

MESON_BUILDTYPE 

meson 使用的 --buildtype 参数。 DEBUG_BUILD 为“1”时默认 debug，否则为 plain。

可选值见 Meson 内置选项。 plain、debug、debugoptimized、release、minsize 等值控制调试符号及编译优化方式：无优化、性能优化或大小优化。

MESON_INSTALL_TAGS 

meson 使用的安装标签，即 meson install 的 --tags 参数。

MESON_TARGET 

meson 在 do_compile 中构建的 Meson 目标。未指定时构建默认目标。

METADATA_BRANCH 

OpenEmbedded-Core 层当前检出的分支，路径由 COREBASE 确定。

METADATA_REVISION 

OpenEmbedded-Core 层当前检出的修订版本，路径由 COREBASE 确定。

MIME_XDG_PACKAGES 

当前 mime-xdg 无法检测通过绝对符号链接安装的 .desktop。用此变量使该类仍为这些包创建安装后和删除后脚本，调用 update-destop-database。

MIRRORS 

额外源码获取路径。搜索顺序是本地下载目录、PREMIRRORS、上游源，最后是本变量指定的位置。

默认值定义于核心元数据层的 meta/classes-global/mirrors.bbclass。更多详情见《BitBake 手册》的 MIRRORS。

MLPREFIX 

为创建配方或软件包特殊变体（例如 Multilib）而加到 PN 的前缀。需要向名称添加或移除前缀的场景会使用它，例如 BPN。 PN 添加前缀后，相应设置本变量。

备注

ML 表示 MultiLib，是历史命名。最初 nativesdk 是配方名后缀，后来改成前缀，也适合使用本变量表示。

例如 BBCLASSEXTEND 为目标配方增加 nativesdk 变体时， DEPENDS 中的 foo 会自动改为 nativesdk-foo，但以下依赖不会自动改写:

do_foo[depends] += "recipe:do_foo"

要让它随变体转换，可写为:

do_foo[depends] += "${MLPREFIX}recipe:do_foo"

module_autoload 

已由 KERNEL_MODULE_AUTOLOAD 替代。应将全部旧设置改为向新变量追加，例如:

module_autoload_rfcomm = "rfcomm"

应改为:

KERNEL_MODULE_AUTOLOAD += "rfcomm"

更多信息见 KERNEL_MODULE_AUTOLOAD。

module_conf 

为 /etc/modprobe.d/modname.conf 指定 modprobe.d(5) 语法行。

可在内核或树外模块配方能识别的位置使用，例如机器、发行版配置，配方及其追加文件。同时必须将模块名列入 KERNEL_MODULE_PROBECONF。

通用语法为:

module_conf_module_name = "modprobe.d-syntax"

必须使用内核模块名称覆盖。运行 man modprobe.d 查看准确语法。

设置后构建系统将相应语法行写入文件。以下为 mymodule 添加 arg1 和 arg2:

module_conf_mymodule = "options mymodule arg1=val1 arg2=val2"

开机自动加载模块见 KERNEL_MODULE_AUTOLOAD。

MODULE_TARBALL_DEPLOY 

控制是否创建包含本次内核构建全部模块的 modules-*.tgz。设为“0”禁用。

MODULE_TARBALL_LINK_NAME 

内核模块压缩包的链接名，在 meta/classes-recipe/kernel-artifact-names.bbclass 设置:

MODULE_TARBALL_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}"

同文件中的 KERNEL_ARTIFACT_LINK_NAME 为:

KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}"

更多信息见 MACHINE。

MODULE_TARBALL_NAME 

内核模块压缩包的基本名称，在 meta/classes-recipe/kernel-artifact-names.bbclass 设置:

MODULE_TARBALL_NAME ?= "${KERNEL_ARTIFACT_NAME}"

更多信息见 KERNEL_ARTIFACT_NAME。

MOUNT_BASE 

非 systemd 系统使用 udev-extraconf 时，自动挂载文件系统的基础目录，默认 /run/media。

MOUNT_GROUP 

非 systemd 系统使用 udev-extraconf 时，自动挂载文件系统的组，默认 disk。

MULTIMACH_TARGET_SYS 

唯一标识软件包所针对的目标系统类型，使不同类型的输出进入同一输出目录的不同子目录。

默认值为:

${PACKAGE_ARCH}${TARGET_VENDOR}-${TARGET_OS}

cross-canadian 等类可能修改它。示例见 STAMP，更多信息见 STAGING_DIR_TARGET。

NATIVELSBSTRING 

标识主机发行版的字符串，由发行组织 ID 加版本组成，来自 lsb_release 或 /etc/lsb-release。例如 Ubuntu 12.10 为 Ubuntu-12.10，无法确定时为 Unknown。

默认用于隔离不同发行版的 native 共享状态包，例如避免 glibc 版本不兼容。若设置 SANITY_TESTED_DISTROS，还会与其比较。

NM 

运行 nm 所需的最小命令及参数。

NO_GENERIC_LICENSE 

配方使用非通用且非 CLOSED 的许可证时，避免质量检查错误。例如 linux-firmware 含大量专用许可证，有时也会添加仅适用于特定包的新许可证，而不希望为此加入大量通用许可证文件。本变量允许复制通用许可证目录中不存在的许可文本。

添加方式:

NO_GENERIC_LICENSE[license_name] = "license_file_in_fetched_source"

以下使用获取源码中的 LICENSE.Abilis.txt:

NO_GENERIC_LICENSE[Firmware-Abilis] = "LICENSE.Abilis.txt"

NO_RECOMMENDATIONS 

阻止安装全部“仅推荐”包，即仅通过 RRECOMMENDS 引入的包。设为“1”启用:

NO_RECOMMENDATIONS = "1"

可在 configuration file 全局设置，或直接在镜像配方中指定:

NO_RECOMMENDATIONS = "1"

如果其他包通过 RDEPENDS 强制依赖这些包，构建系统会忽略排除请求，仍安装它们以避免依赖错误。

备注

某些推荐包（例如内核模块）可能是特定系统功能必需的，需要自行通过 IMAGE_INSTALL 添加。

所有打包后端均支持。另见 BAD_RECOMMENDATIONS 和 PACKAGE_EXCLUDE。

NOAUTOPACKAGEDEBUG 

禁用 .debug 文件的自动拆包。如果配方需手动设置 FILES:${PN}-dbg，可定义此变量，自行确定调试包内容。例如:

NOAUTOPACKAGEDEBUG = "1"
FILES:${PN}-dev = "${includedir}/${QT_DIR_NAME}/Qt/*"
FILES:${PN}-dbg = "/usr/src/debug/"
FILES:${QT_BASE_NAME}-demos-doc = "${docdir}/${QT_DIR_NAME}/qch/qt.qch"

NON_MULTILIB_RECIPES 

不应构建 multilib 版本的配方列表。 OE-Core 的 multilib.conf 提供合理初始值:

NON_MULTILIB_RECIPES = "grub grub-efi make-mod-scripts ovmf u-boot"

OBJCOPY 

运行 objcopy 所需的最小命令及参数。

OBJDUMP 

运行 objdump 所需的最小命令及参数。

OE_BINCONFIG_EXTRA_MANGLE 

继承 binconfig 时，指定传给 sed 的额外参数，用于修改配置脚本在编译期间形成的路径。此类将全部路径改为指向 sysroots/，使使用脚本的构建获得正确的交叉编译布局。

额外参数应用方式见 OpenEmbedded-Core (OE-Core) 的 meta/classes-recipe/binconfig.bbclass。

OE_FRAGMENTS 

当前构建启用的配置片段列表。用法见《Yocto Project 参考手册》的使用配置片段。

OE_FRAGMENTS_BUILTIN 

可通过 bitbake-config-build 设置的内置片段列表。用法见《Yocto Project 参考手册》的使用配置片段。

OE_FRAGMENTS_METADATA_VARS 

标准 Configuration Fragment 中必须设置的变量列表。在 OpenEmbedded-Core (OE-Core) 中为 BB_CONF_FRAGMENT_SUMMARY 和 BB_CONF_FRAGMENT_DESCRIPTION。

OE_FRAGMENTS_PREFIX 

定义 BitBake 在层中查找配置片段的路径前缀。用法见《Yocto Project 参考手册》的使用配置片段。

OE_INIT_ENV_SCRIPT 

可扩展 SDK 内设置构建环境的脚本名称，默认 oe-init-build-env。使用自定义脚本时，将此变量设为其名称。

OE_SHARED_UMASK 

共享文件的 umask 定义，例如 SSTATE_DIR 或 DL_DIR 中的文件。

OE_TERMINAL 

控制构建系统如何在开发主机启动交互式终端，例如 BitBake 使用 -c devshell 时。详情见《Yocto Project 开发任务手册》的 “使用开发 Shell”。

可选值：

auto
gnome
xfce
rxvt
screen
konsole
none

OECMAKE_GENERATOR 

供 cmake 选择 CMake 生成的构建后端。默认 Ninja，比 GNU make 更快。如果 Ninja 构建失败，可改为 GNU make:

OECMAKE_GENERATOR = "Unix Makefiles"

OEQA_REPRODUCIBLE_TEST_LEAF_TARGETS 

设置可复现性测试的构建目标，但允许大多数依赖使用共享状态。这里指 DEPENDS 显式列出的依赖，可能不包括 [depends] 标志、PACKAGE_DEPENDS 及其他机制定义的全部依赖。见可重现构建。

OEQA_REPRODUCIBLE_TEST_PACKAGE 

设置可复现性测试使用的软件包管理器。见 reproducible.py 和可重现构建。

OEQA_REPRODUCIBLE_TEST_SSTATE_TARGETS 

设置可复现性测试中可使用共享状态重建的目标。见可重现构建。

OEQA_REPRODUCIBLE_TEST_TARGET 

设置可复现性测试构建目标，默认通过 bitbake world 编译全部可用配方。另见 EXCLUDE_FROM_WORLD 和可重现构建。

OEROOT 

加载顶层构建环境设置脚本的来源目录。运行 Yocto Project 提供的 oe-init-build-env 时，解析为包含该脚本的目录。更多用法见初始化脚本。

OLDEST_KERNEL 

生成的二进制文件必须支持的最低 Linux 内核版本，传入 glibc 构建。

默认来自 meta/conf/bitbake.conf，可在自定义发行版配置中覆盖。

OPENSSH_HOST_KEY_DIR 

OpenSSH 主机密钥存放目录，默认 /etc/ssh。

OPENSSH_HOST_KEY_DIR_READONLY_CONFIG 

设备使用只读文件系统时的 OpenSSH 主机密钥目录，默认 /var/run/ssh。

OPKG_MAKE_INDEX_EXTRA_PARAMS 

opkg-make-index 命令的额外参数。

OPKGBUILDCMD 

使用 package_ipk 时构建 opkg 包的命令，该类定义如下:

OPKGBUILDCMD ??= 'opkg-build -Z zstd -a "${ZSTD_DEFAULTS}"'

OVERLAYFS_ETC_DEVICE 

使用 overlayfs-etc 时，指定 /etc 读写层所挂载的设备。无默认值，启用该类时必须设置。例如所需设备为 /dev/mmcblk0p2:

OVERLAYFS_ETC_DEVICE = "/dev/mmcblk0p2"

OVERLAYFS_ETC_EXPOSE_LOWER 

使用 overlayfs-etc 时，设为“1”可在 OVERLAYFS_ETC_MOUNT_POINT 的 lower/ 子目录中只读访问原 /etc 内容。默认“0”。

OVERLAYFS_ETC_FSTYPE 

使用 overlayfs-etc 时，指定 /etc 读写层的文件系统类型。无默认值，启用该类时必须设置。例如 ext4:

OVERLAYFS_ETC_FSTYPE = "ext4"

OVERLAYFS_ETC_MOUNT_OPTIONS 

使用 overlayfs-etc 时，指定读写层挂载选项，默认 defaults。

OVERLAYFS_ETC_MOUNT_POINT 

使用 overlayfs-etc 时，指定各文件系统层的父挂载路径。无默认值，启用该类时必须设置。例如 /data:

OVERLAYFS_ETC_MOUNT_POINT = "/data"

OVERLAYFS_ETC_USE_ORIG_INIT_NAME 

使用 overlayfs-etc 时，控制生成的 init 命名方式。默认“1”，更多信息见该类文档。

OVERLAYFS_MOUNT_POINT 

继承 overlayfs 时，指定挂载点，例如:

OVERLAYFS_MOUNT_POINT[data] = "/data"

假定 BSP 其他位置（例如 systemd-machine-units 配方）已定义 data.mount systemd 单元，并安装到镜像。更多信息见 overlayfs 类。

备注

虽然此类由各配方继承，本变量仍应在机器配置中设置。

OVERLAYFS_QA_SKIP 

继承 overlayfs 时，为特定挂载禁用质量检查。例如:

OVERLAYFS_QA_SKIP[data] = "mount-configured"

备注

虽然此类由各配方继承，本变量仍应在机器配置中设置。

OVERLAYFS_WRITABLE_PATHS 

继承 overlayfs 时，指定配方运行时使用的可写路径。例如:

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

OVERRIDES 

当前生效的冒号分隔覆盖列表。覆盖是 BitBake 在解析结束时选择性改写变量的机制，此列表表示构建状态，包括当前配方、目标机器等。

例如列表含 an-override 时，以下赋值在解析结束时将 FOO 改为 overridden:

FOO:an-override = "overridden"

更多信息见《BitBake 用户手册》的 “Conditional Syntax (Overrides)”。

默认包含 CLASSOVERRIDE、MACHINEOVERRIDES 和 DISTROOVERRIDES。另一个重要默认覆盖是 pn-${PN}，允许在 .conf 中针对单个配方设置变量，例如:

FOO:pn-myrecipe = "myrecipe-specific value"

备注

运行 bitbake-getvar -r myrecipe OVERRIDES 可直接查看生效覆盖。详情见《Yocto Project 开发任务手册》的 “查看变量值”。

P 

配方名称和版本，组成如下:

${PN}-${PV}

P4DIR 

见《BitBake 手册》的 P4DIR。

PACKAGE_ADD_METADATA 

定义添加到软件包的额外元数据，将要注入的数据设为变量值即可。多个字段通过字面分隔符 \n 分开。

可添加 _IPK、_DEB、_RPM 后缀设置特定包类型，也可添加软件包名后缀设置特定包。

更多信息见《Yocto Project 开发任务手册》的 “向软件包添加自定义元数据”一节。

PACKAGE_ARCH 

输出软件包的架构。目标构建默认 TUNE_PKGARCH，构建主机默认 BUILD_ARCH， SDK 构建默认 ${SDK_ARCH}-${SDKPKGSUFFIX}。

备注

更多信息见 SDK_ARCH。

如果输出只适用于特定目标机器，而非该机器架构的一般系统，应在配方中设置为 MACHINE_ARCH:

PACKAGE_ARCH = "${MACHINE_ARCH}"

PACKAGE_ARCHS 

与目标机器兼容的架构列表，自动设置，通常不应手动编辑。以空格分隔并按优先级排列。默认“all any noarch ${PACKAGE_EXTRA_ARCHS} ${MACHINE_ARCH}”。

PACKAGE_BEFORE_PN 

便于在 PACKAGES 的 ${PN} 之前添加软件包，使新增包优先取得通常归入默认包的文件。

PACKAGE_CLASSES 

指定构建系统打包时使用的软件包管理器，可提供一个或多个以下值:

PACKAGE_CLASSES ?= "package_rpm package_deb package_ipk"

创建镜像或 SDK 时只使用第一个管理器，但所有额外指定的打包类仍会生成相应软件包。例如发行版 configuration file 中设置:

PACKAGE_CLASSES ?= "package_ipk"

则使用 IPK 管理器创建镜像或 SDK。打包和性能影响见“package”。

PACKAGE_DEBUG_SPLIT_STYLE 

决定为 GDB 创建调试包时如何拆分和打包调试信息及源码。可以合并到单包、将源码放入独立可安装包，或完全不打包源码。

可选值：

.debug：调试信息和源码都放入 *-dbg。调试符号位于二进制文件旁的 .debug 目录，例如 /bin 对应 /bin/.debug。源码位于同包的 /usr/src/debug。
debug-file-directory：同样全部放入 *-dbg，但调试符号统一位于 /usr/lib/debug，并按二进制安装路径细分，例如 /bin 对应 /usr/lib/debug/bin。源码仍位于同包的 /usr/src/debug。
debug-with-srcpkg：调试信息按 .debug 方式放入 *-dbg，源码放入独立可安装的 *-src。这是 OE-Core 的 bitbake.conf 默认设置。
debug-without-src：与 .debug 相同，但完全不打包源码。

备注

INHIBIT_PACKAGE_DEBUG_SPLIT 可以覆盖上述大部分拆分行为。

GDB 使用方法见《Yocto Project 开发任务手册》的 “使用 GNU 调试器（GDB）远程调试”。

PACKAGE_EXCLUDE 

列出不应安装到镜像的软件包，例如:

PACKAGE_EXCLUDE = "package_name package_name package_name ..."

可在 configuration file 中全局设置，或直接在镜像配方设置:

PACKAGE_EXCLUDE = "package_name"

如果其他包通过 RDEPENDS 强制依赖被排除包，构建系统会产生致命安装错误并停止。可利用此行为，通过迭代开发逐步移除系统中特定组件。

所有打包后端均支持。另见 NO_RECOMMENDATIONS 和 BAD_RECOMMENDATIONS。

PACKAGE_EXCLUDE_COMPLEMENTARY 

安装配套软件包时排除特定包。例如通过 IMAGE_FEATURES 安装 dev-pkgs 时，可能不希望安装某个 multilib 的全部包。可用此变量指定匹配待排除包的正则表达式。

PACKAGE_EXTRA_ARCHS 

与设备 CPU 兼容的架构列表。为使用 XScale、ARM926-EJS 等不同处理器的多个设备构建时很有用。

PACKAGE_FEED_ARCHS 

可选指定构建时软件包源 URI 中的软件包架构，追加到由 PACKAGE_FEED_URIS 和 PACKAGE_FEED_BASE_PATHS 组成的 URI 末尾。

备注

可用于仅允许特定架构。通常无需限制时可省略，此时当前机器的全部可用架构都纳入远程软件包源。

例如在 build/conf/local.conf 定义三个变量:

PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \
                     https://example.com/packagerepos/updates"
PACKAGE_FEED_BASE_PATHS = "rpm rpm-dev"
PACKAGE_FEED_ARCHS = "all core2-64"

生成的软件包源如下：

https://example.com/packagerepos/release/rpm/all
https://example.com/packagerepos/release/rpm/core2-64
https://example.com/packagerepos/release/rpm-dev/all
https://example.com/packagerepos/release/rpm-dev/core2-64
https://example.com/packagerepos/updates/rpm/all
https://example.com/packagerepos/updates/rpm/core2-64
https://example.com/packagerepos/updates/rpm-dev/all
https://example.com/packagerepos/updates/rpm-dev/core2-64

PACKAGE_FEED_BASE_PATHS 

构建软件包源 URI 的基础路径，即中间部分，位于 PACKAGE_FEED_URIS 与 PACKAGE_FEED_ARCHS 之间。

例如在 build/conf/local.conf 定义三个变量:

PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \
                     https://example.com/packagerepos/updates"
PACKAGE_FEED_BASE_PATHS = "rpm rpm-dev"
PACKAGE_FEED_ARCHS = "all core2-64"

生成的软件包源如下：

https://example.com/packagerepos/release/rpm/all
https://example.com/packagerepos/release/rpm/core2-64
https://example.com/packagerepos/release/rpm-dev/all
https://example.com/packagerepos/release/rpm-dev/core2-64
https://example.com/packagerepos/updates/rpm/all
https://example.com/packagerepos/updates/rpm/core2-64
https://example.com/packagerepos/updates/rpm-dev/all
https://example.com/packagerepos/updates/rpm-dev/core2-64

PACKAGE_FEED_URIS 

软件包源 URI 的前部。最终 URI 由此变量、PACKAGE_FEED_BASE_PATHS 和 PACKAGE_FEED_ARCHS 组成。

例如在 build/conf/local.conf 定义三个变量:

PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \
                     https://example.com/packagerepos/updates"
PACKAGE_FEED_BASE_PATHS = "rpm rpm-dev"
PACKAGE_FEED_ARCHS = "all core2-64"

生成的软件包源如下：

https://example.com/packagerepos/release/rpm/all
https://example.com/packagerepos/release/rpm/core2-64
https://example.com/packagerepos/release/rpm-dev/all
https://example.com/packagerepos/release/rpm-dev/core2-64
https://example.com/packagerepos/updates/rpm/all
https://example.com/packagerepos/updates/rpm/core2-64
https://example.com/packagerepos/updates/rpm-dev/all
https://example.com/packagerepos/updates/rpm-dev/core2-64

PACKAGE_INSTALL 

传给软件包管理器、用于安装到镜像的最终包列表。

实际安装由包管理器控制，因此此列表不等于最终实际安装的全部包。它是镜像构建内部变量，通常应使用 IMAGE_INSTALL 指定安装内容。例外是 core-image-minimal-initramfs：处理 Initramfs 镜像时应使用本变量。创建方法见《Yocto Project 开发任务手册》的 “构建初始 RAM 文件系统（Initramfs）镜像”。

PACKAGE_INSTALL_ATTEMPTONLY 

创建镜像时尝试安装的软件包列表，某项安装失败不会报错。通常不由用户定义。

PACKAGE_NO_LOCALE 

设为“1”，阻止构建系统将 PKGD 中的区域设置拆分到独立包。

例如 quilt 在 do_package 后自动产生拆分包，其 WORKDIR 如下：

$ ls -1 packages-split/
guards
guards-doc
quilt
quilt-dbg
quilt-dev
quilt-doc
quilt-locale-de
quilt-locale-fr
quilt-locale-ja
quilt-locale-ru
quilt-ptest
quilt-src
quilt-staticdev

可以看到自动生成 quilt-locale-*。设为“1”后得到：

$ ls -1 packages-split/
guards
guards-doc
quilt
quilt-dbg
quilt-dev
quilt-doc
quilt-locale
quilt-ptest
quilt-src
quilt-staticdev

quilt-locale 包含此前各 quilt-locale-* 合并后的内容。

PACKAGE_PREPROCESS_FUNCS 

文件拆分到各包之前，预处理 PKGD 目录的函数列表。

PACKAGE_WRITE_DEPS 

安装前和安装后脚本依赖的 native/cross 工具列表。如果脚本可以在根文件系统创建时而非目标端执行，但需要 native 工具，必须将工具列于此处。

安装后脚本说明见《Yocto Project 开发任务手册》的 “安装后脚本”。

PACKAGECONFIG 

按配方启用或禁用功能的机制。配方中定义功能，并用参数描述其行为。基本结构如下，为便于阅读分成多行:

PACKAGECONFIG ??= "f1 f2 f3 ..."
PACKAGECONFIG[f1] = "\
    --with-f1, \
    --without-f1, \
    build-deps-for-f1, \
    runtime-deps-for-f1, \
    runtime-recommends-for-f1, \
    packageconfig-conflicts-for-f1"
PACKAGECONFIG[f2] = "\
     ... and so on and so on ...

变量本身是空格分隔的启用功能列表。每个功能通过最多六个按固定顺序、以逗号分隔的参数定义行为。任一参数均可省略，但必须保留分隔逗号。顺序为：

启用时加入 PACKAGECONFIG_CONFARGS 的额外参数。
禁用时加入 PACKAGECONFIG_CONFARGS 的额外参数。
启用时增加的构建依赖 DEPENDS。
启用时增加的运行时依赖 RDEPENDS。
启用时增加的运行时推荐 RRECOMMENDS。
与此功能冲突，即互斥的 PACKAGECONFIG 设置。

以下 librsvg 配方的 gtk 功能使用三个参数:

PACKAGECONFIG[gtk] = "--with-gtk3,--without-gtk3,gtk+3"

启用时，--with-gtk3 加入 configure 参数，gtk+3 加入 DEPENDS。禁用时，例如其他层的 bbappend 禁用了功能，则传入 --without-gtk3。

无论创建还是修改功能块，都遵循相同结构。创建时直接写在配方中。修改现有设置可通过两种方式：

追加文件： 在层中创建 recipename.bbappend，完全覆盖:
```
PACKAGECONFIG = "f4 f5"
```
或只追加:
```
PACKAGECONFIG:append = " f4"
```
配置文件： 与追加方式相同，但编辑 build/conf/local.conf 或发行版 configuration file。可以完全覆盖:
```
PACKAGECONFIG:pn-recipename = "f4 f5"
```
或只修改:
```
PACKAGECONFIG:append:pn-recipename = " f4"
```

以下 cmake 配方包含 systemd 服务，通过 PACKAGECONFIG 将服务转为可便捷启用或禁用的功能:

example.c
example.service
CMakeLists.txt

CMakeLists.txt 包含:

if(WITH_SYSTEMD)
   install(FILES ${PROJECT_SOURCE_DIR}/example.service DESTINATION /etc/systemd/systemd)
endif(WITH_SYSTEMD)

要安装 example.service，必须向 cmake 传入 -DWITH_SYSTEMD=ON。包含 CMakeLists.txt 的配方通常继承 cmake 类，它以 EXTRA_OECMAKE 运行 cmake，后者会追加 PACKAGECONFIG_CONFARGS。由于该变量自动取 PACKAGECONFIG 标志的第一或第二项，配方可写为:

inherit cmake
PACKAGECONFIG = "systemd"
PACKAGECONFIG[systemd] = "-DWITH_SYSTEMD=ON,-DWITH_SYSTEMD=OFF"

此配方还可以检查实际使用的 INIT_MANAGER 是否为 systemd:

PACKAGECONFIG = "${@'systemd' if d.getVar('INIT_MANAGER') == 'systemd' else ''}"

PACKAGECONFIG_CONFARGS 

从 PACKAGECONFIG 生成的空格分隔配置选项列表。

autotools* 和 cmake 等类分别用它向 configure 和 cmake 传递选项。如果使用 PACKAGECONFIG 却没有使用处理 do_configure 的类，就需要自行适当使用本变量。

PACKAGEFUNCS 

根据 PKGDEST 中拆分包处理元数据的函数列表， package 按列表顺序执行。

PACKAGEGROUP_DISABLE_COMPLEMENTARY 

继承 packagegroup 时，设为“1”可禁用默认自动生成 -dev、-dbg 等普通配套包的行为。

PACKAGES 

配方创建的软件包列表，默认值如下:

${PN}-src ${PN}-dbg ${PN}-staticdev ${PN}-dev ${PN}-doc ${PN}-locale ${PACKAGE_BEFORE_PN} ${PN}

打包时，do_package 按顺序遍历列表，根据每个包的 FILES 分配文件。一个文件匹配多个包时，分给最先出现、即最左侧的包。

空包默认不生成，即 FILES:pkg 没有匹配 do_install 安装的文件；可通过 ALLOW_EMPTY 强制生成。

PACKAGES_DYNAMIC 

声明配方承诺满足其他配方对可选模块的运行时依赖，但本变量只表达承诺，不实际满足依赖。例如另一包的强制 RDEPENDS 在构建时由此变量匹配，但最终没有生成对应模块包，则该包无法正常使用。将其纳入镜像时，do_rootfs 会收到软件包系统的依赖错误。

若可能发生这种情况，且没有该依赖时软件仍可正常使用，通常应使用软依赖 RRECOMMENDS 而非 RDEPENDS。

拆包用法示例见《Yocto Project 开发任务手册》的 “处理可选模块打包”。

PACKAGESPLITFUNCS 

对文件进行额外拆包的函数列表。配方可向本变量或 populate_packages 函数前面追加处理。两种方式都应适当设置 PACKAGES、FILES、RDEPENDS 及其他打包变量，完成所需拆分。

PARALLEL_MAKE 

do_compile 期间传给 make、ninja 或 Go 等专用构建工具的额外选项，用于控制本机构建主机上的并行编译，通常形式为 -j x，x 为最大并行线程数。

备注

使用 make 时，必须传入 ${EXTRA_OEMAKE} 才能生效，简单方式是使用 oe_runmake。

默认自动设为构建系统使用的核心数。

备注

编译期间依赖问题导致竞争条件时，可在配方中清空此变量作为临时解决方法。详情见《Yocto Project 开发任务手册》的 “调试并行 Make 竞态”。

单插槽系统通常无需修改就能获得最佳并行度。多物理 CPU 的大型系统可能需要确保不超过 -j 20。

加速构建见“加快构建”，限制资源见限制主机资源使用量。

PARALLEL_MAKEINST 

do_install 期间传给 make install、ninja install 等命令的额外选项，用于并行安装，默认等于 PARALLEL_MAKE。

备注

使用 make 时，必须传入 ${EXTRA_OEMAKE} 才能生效，简单方式是使用 oe_runmake。

安装期间依赖问题导致竞争条件时，可在配方中清空本变量作为临时解决方法。详情见《Yocto Project 开发任务手册》的 “调试并行 Make 竞态”。

PATCHRESOLVE 

补丁失败后的处理方式，可为 noop 或 user。默认 noop 使构建直接失败；user 则启动 shell，并切换到正确位置，供手动解决冲突。

在 build/conf/local.conf 中设置。

PATCHTOOL 

do_patch 使用的工具，可为 patch、quilt 或 git。默认 quilt，但 quilt-native 自身打补丁时工具尚不可用，因此使用 patch。

要使用其他工具，在配方中设置以下任一种:

PATCHTOOL = "patch"
PATCHTOOL = "quilt"
PATCHTOOL = "git"

PE 

配方 epoch，默认未设置。版本方案出现向后不兼容变化时，用于保证仍可升级。

是 PKGE 的默认值。

PEP517_WHEEL_PATH 

继承 python_pep517 的配方中，表示生成 wheel 二进制归档的 dist/ 目录路径，dist 为 distribution 的缩写。

PERSISTENT_DIR 

见《BitBake 手册》的 PERSISTENT_DIR。

PF 

包含全部版本和修订号的配方或软件包名称，例如 glibc-2.13-r20+svnr15508/、bash-4.2-r1/。组成是 ${PN}-${EXTENDPE}${PV}-${PR}。

PIXBUF_PACKAGES 

继承 pixbufcache 时，指定包含 gdk-pixbuf 加载器的软件包。默认假定加载器在主包 ${PN}，位于其他包时使用此变量。

PKG 

构建系统生成的软件包最终名称。

备注

必须结合软件包名称覆盖使用。

例如 debian 通过 PKG:packagename 重命名输出包。

PKG_CONFIG_PATH 

当前构建上下文的 pkg-config 文件路径，pkg-config 从环境中读取。

PKGD 

文件拆分为各软件包之前的待打包文件目录，默认如下，不要修改:

${WORKDIR}/package

PKGDATA_DIR 

保存打包期间生成数据的共享全局状态目录。 do_packagedata 为各配方整理包数据并安装到该区域。默认如下，不应修改:

${TMPDIR}/pkgdata/${MACHINE}

使用示例见《Yocto Project 概览与概念手册》的 “自动添加运行时依赖”，以及《开发任务手册》的 “使用 oe-pkgdata-util 查看软件包信息”。

PKGDEST 

拆分后各软件包文件所在的父目录，默认如下:

${WORKDIR}/packages-split

构建系统在其下为 PACKAGES 中各包创建子目录。不要修改默认值。

PKGDESTWORK 

do_package 保存软件包元数据的临时工作区，默认如下:

${WORKDIR}/pkgdata

不要修改默认值。do_packagedata 将数据复制到 PKGDATA_DIR，使其全局可用。

PKGE 

配方生成软件包的 epoch，默认等于 PE。

PKGR 

配方生成软件包的修订号，默认等于 PR。

PKGV 

配方生成软件包的版本，默认等于 PV。 PV 包含 + 时，后续打包阶段会加入版本控制信息。更多信息见《Yocto Project 开发任务手册》的使用外部源码管理系统。

警告

版本控制信息由 package 在较晚阶段加入，因此 bitbake -e 和 bitbake-getvar 无法显示。应在构建完成后使用 oe-pkgdata-util package-info <package name> 获取。详情见《Yocto Project 开发任务手册》的使用 oe-pkgdata-util 查看软件包信息。

PN 

根据上下文表示配方名或输出软件包名。

对于构建系统用来生成软件包的输入文件，表示配方名，通常从文件名提取。例如 expat_2.0.1.bb 默认得到 expat。对于构建系统生成的文件，则表示软件包名。

如适用，也包含特殊前后缀。例如 bash 的 native 构建为 bash-native，目标构建为 bash，Multilib 构建为 lib64-bash。

POPULATE_SDK_POST_HOST_COMMAND 

构建系统创建 SDK 的主机部分后调用的函数列表，以空格分隔:

POPULATE_SDK_POST_HOST_COMMAND += "function"

函数内命令若需 SDK 路径，可使用 ${SDK_DIR}，指向创建 SDK 输出所用父目录。更多信息见 SDK_DIR。

POPULATE_SDK_POST_TARGET_COMMAND 

构建系统创建 SDK 的目标部分后调用的函数列表，以空格分隔:

POPULATE_SDK_POST_TARGET_COMMAND += "function"

函数内命令若需 SDK 路径，可使用 ${SDK_DIR}，指向创建 SDK 输出所用父目录。更多信息见 SDK_DIR。

PR 

配方修订号，默认 r0，后续通常为 r1、r2 等。 PV 增加时通常重置为 r0。

备注

构建系统不依赖 PR 判断是否重建，而使用任务输入校验和、时间戳和共享状态缓存。

此变量主要影响已构建镜像中的动态软件包安装。作为 PKGR 默认值，它帮助管理器在多个包具有相同 PV（即 PKGV）时判断新旧。同一组件的这些包通常安装同一个上游版本，但后续 PR 包含打包修复。

备注

不改变软件包内容或元数据的修改，无需递增 PR。

手动管理繁琐易错，因此有自动化方案。见《Yocto Project 开发任务手册》的“使用 PR 服务”。

PREFERRED_PROVIDER 

多个配方提供相同项目时，指定首选提供者。变量必须以提供项目名称为后缀，值为首选配方的 PN。常见示例:

PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto"

多个配方提供 virtual/kernel，上例选定其中一个配方。其他示例:

PREFERRED_PROVIDER_virtual/xserver = "xserver-xf86"
PREFERRED_PROVIDER_virtual/libgl ?= "mesa"

更多信息见“使用虚拟提供者”。

备注

对 virtual/* 项目使用此变量时，所有提供该项目却未被选中的配方都禁止构建。这通常正是所需行为，因为该机制用于选择互斥替代提供者。

PREFERRED_PROVIDERS 

见《BitBake 手册》的 PREFERRED_PROVIDERS。

PREFERRED_RPROVIDER 

与 PREFERRED_PROVIDER 类似，但针对提供运行时组件的软件包。提供者在配方中通过针对特定包的 RPROVIDES 声明。例如:

PREFERRED_RPROVIDER_virtual-x-terminal-emulator = "rxvt-unicode"

这将 X 终端模拟器的运行时提供者设为 rxvt-unicode。该包能够提供此组件，是因为配方为 rxvt-unicode（${PN}）定义:

RPROVIDES:${PN} = "virtual-x-terminal-emulator"

虚拟提供者详情见“使用虚拟提供者”。

PREFERRED_TOOLCHAIN 

选择编译配方的工具链，不应全局覆盖本变量。应覆盖 PREFERRED_TOOLCHAIN_TARGET、PREFERRED_TOOLCHAIN_NATIVE 和 PREFERRED_TOOLCHAIN_SDK。

PREFERRED_TOOLCHAIN_NATIVE 

控制编译 native 配方的工具链，应在 configuration file 中全局设置。可选值见 PREFERRED_TOOLCHAIN_TARGET。不支持所选工具链的配方可通过 TOOLCHAIN_NATIVE 本地覆盖。

PREFERRED_TOOLCHAIN_SDK 

控制编译 nativesdk 配方的工具链，应在 configuration file 中全局设置。可选值见 PREFERRED_TOOLCHAIN_TARGET。

PREFERRED_TOOLCHAIN_TARGET 

控制针对目标 MACHINE 架构编译的工具链，目前可选：

gcc：默认，GCC/Binutils 工具链。
clang：Clang/LLVM 工具链。

使 base 继承 meta/classes/toolchain 中的一个类，因此应在 configuration file 全局设置。这些类定义 CC、CXX、LD 等交叉编译命令。

不支持所选工具链的配方可通过 TOOLCHAIN 本地覆盖。

PREFERRED_VERSION 

同一配方存在多个版本时，指定首选版本。必须以要选择的 PN 为后缀，并指定对应 PV。下例中的名称是 python，版本为 3.4.0。

支持有限的 % 通配符，匹配任意数量字符，适合包含较长且可能变化的修订号的版本:

PREFERRED_VERSION_python = "3.4.0"
PREFERRED_VERSION_linux-yocto = "5.0%"

备注

% 只能位于字符串末尾，不能出现在其他位置。

版本匹配 PV，而不一定是配方文件名中的版本部分。例如 foo_git.bb 的 PV 为 1.2.3+git，应将 PREFERRED_VERSION_foo 设为 1.2.3%，设为 git 不会生效，因为匹配的是 PV 定义，而非文件名。

若配置文件设置难以覆盖，可通过 OVERRIDES 使用机器专用覆盖，例如:

PREFERRED_VERSION_linux-yocto:qemux86 = "5.0%"

最坏情况下还可使用最强的 forcevariable 覆盖，但不推荐:

PREFERRED_VERSION_linux-yocto:forcevariable = "5.0%"

备注

:forcevariable 没有特殊处理，只有因为 OVERRIDES 默认包含 forcevariable 才生效。

指定版本不存在时产生警告。若希望改为错误，见 REQUIRED_VERSION。

PREMIRRORS 

额外源码获取路径。搜索顺序是本地下载目录、本变量指定位置、上游源，最后 MIRRORS。

默认值定义于核心元数据层的 meta/classes-global/mirrors.bbclass。

例如，在 Build Directory 的 build/conf/site.conf 中添加以下配置，优先尝试指定服务器:

PREMIRRORS:prepend = "\
    git://.*/.* https://downloads.yoctoproject.org/mirror/sources/ \
    ftp://.*/.* https://downloads.yoctoproject.org/mirror/sources/ \
    http://.*/.* https://downloads.yoctoproject.org/mirror/sources/ \
    https://.*/.* https://downloads.yoctoproject.org/mirror/sources/ \
"

这样会拦截 Git、FTP、HTTP、HTTPS 请求并定向到 http:// 源码镜像站。也可用 file:// 指向本地目录或网络共享。

更多详情见《BitBake 手册》的 PREMIRRORS。

PRIORITY 

软件包重要性，是发行版策略的一部分，因为配方的重要程度取决于发行版用途，因此通常不在配方中设置。

可为 required、standard、extra、optional，默认 optional。

PRIVATE_LIBS 

配方安装的、共享库解析器应忽略的库。通常用于软件包含其他配方也提供的库的私有版本时，避免无关包错误依赖私有库包，而它们本应依赖标准版本。

按文件名指定，例如 meta-browser 中 Firefox 配方:

PRIVATE_LIBS = "libmozjs.so \
                libxpcom.so \
                libnspr4.so \
                libxul.so \
                libmozalloc.so \
                libplc4.so \
                libplds4.so"

更多信息见《Yocto Project 概览与概念手册》的 “自动添加运行时依赖”。

PROVIDES 

配方的别名列表。其自身 PN 已隐式包含，无需声明提供自己。额外别名等同于配方名，可用于满足其他配方 DEPENDS 中的构建依赖。

例如 eudev_3.2.9.bb 中:

PROVIDES += "udev"

使 eudev 也可通过 udev 名称使用。

备注

PN 始终隐式加在前面，因此上例 += 虽非严格必需，但推荐保留以免混淆。

此机制还用于虚拟目标，即代表某项功能的名称，例如 Linux 内核。提供者将虚拟目标加入 PROVIDES，依赖者在 DEPENDS 中引用它，从而不限定具体提供者。

惯例名称为 virtual/function，例如 virtual/kernel；斜杠只是名称一部分，没有特殊语法。 PREFERRED_PROVIDER 选择实际配方。

备注

运行时依赖也有对应的虚拟机制，但只依赖普通变量赋值。例如 VIRTUAL-RUNTIME_dev_manager 指管理 /dev 目录的组件包。在配置中通过以下赋值即可选择运行时提供者:

VIRTUAL-RUNTIME_dev_manager = "udev"

PRSERV_HOST 

网络 PR 服务的主机和端口。 OpenEmbedded-Core (OE-Core) 的 meta/conf/templates/default/local.conf.sample.extended 示例为:

PRSERV_HOST = "localhost:0"

要自动启动本地 PR 服务，必须设置此变量；设置其他值可连接远程服务。

PRSERV_UPSTREAM 

以 host:port 指定本地 PR 服务器要连接的上游 PR 服务器，使上游软件包可以应用本地修复。

PSEUDO_IGNORE_PATHS 

pseudo 监控和记录文件操作时应忽略的路径前缀，以逗号分隔且不含空格，避免 pseudo 上下文外写文件引发问题，并减少开销。匹配任一前缀就忽略，可使用部分目录名或文件名。同时出现在本变量与 PSEUDO_INCLUDE_PATHS 中时，后者优先。

PSEUDO_INCLUDE_PATHS 

pseudo 监控和记录文件操作时应包含的路径前缀，以逗号分隔且不含空格，避免上下文外写文件引发问题，并减少 pseudo 开销。匹配任一前缀就包含，可使用部分目录名或文件名。同时出现在 PSEUDO_IGNORE_PATHS 和本变量中时，本变量优先。

PTEST_ENABLED 

配方构建时是否启用软件包测试功能。不要直接设置，应向 DISTRO_FEATURES 添加或移除 ptest。

PTEST_PYTEST_DIR 

ptest-python-pytest 使用的路径，指定 Python 包源码树中供 pytest 运行的单元测试目录。默认 tests，更多信息见该类文档。

PV 

配方版本，通常从文件名提取，例如 expat_2.0.1.bb 默认得到 2.0.1。通常不在配方内覆盖，除非从 Git、Subversion 等源码仓库构建不稳定开发版。

是 PKGV 的默认值。

PYPI_PACKAGE 

继承 pypi 时，指定要构建的 PyPI 包名。默认根据 BPN 移除 python- 或 python3- 前缀得到。若仍不匹配包名，例如具有特殊前缀、下划线或大写字母，需要显式设置。

PYPI_PACKAGE_EXT 

继承 pypi 时，从 PyPI 获取包的扩展名，默认 tar.gz。

PYPI_SRC_URI 

继承 pypi 时，获取软件包的完整 pythonhosted URI。默认根据 PYPI_PACKAGE、PYPI_PACKAGE_EXT 和 PV 构造。除非构建不稳定开发版本，多数配方无需设置。

PYTHON_ABI 

继承 setuptools3 的配方中，表示当前 Python ABI。默认 m，由构建系统设置，无需自行指定。

用于构造系统根目录中 Python 头文件和库的安装目录名，例如 .../python3.3m/...。

QA_EMPTY_DIRS 

指定打包时预期为空的目录列表。如果 ERROR_QA 或 WARN_QA 包含 empty-dirs，就会检查这些目录，并分别产生错误或警告。

默认值设置于 insane.bbclass。

QA_EMPTY_DIRS_RECOMMENDATION 

指定目录必须为空的原因建议。如果发现该目录含文件，会将建议加入错误消息。必须以要匹配的目录路径作为覆盖项。

若未指定，默认使用 "but it is expected to be empty"。

以下是 /dev 存在文件时的消息示例:

QA_EMPTY_DIRS_RECOMMENDATION:/dev = "but all devices must be created at runtime"

QB_CMDLINE_IP_SLIRP 

如果 QB_NETWORK_DEVICE 向 QEMU 添加多个网络接口，通常需相应修改 Linux 内核命令行 ip= 参数。此变量控制该值，详情见内核文档： https://www.kernel.org/doc/Documentation/filesystems/nfs/nfsroot.txt。

QB_CMDLINE_IP_TAP 

类似 QB_CMDLINE_IP_SLIRP。

用法如下:

QB_CMDLINE_IP_TAP = "ip=192.168.7.@CLIENT@::192.168.7.@GATEWAY@:255.255.255.0::eth0"

tap 接口要求静态 IP，runqemu 会将 @CLIENT@ 和 @GATEWAY@ 替换为 QEMU 客户机的 IP 与网关地址。

QB_DEFAULT_BIOS 

为 DEPLOY_DIR_IMAGE 中的文件路径提供默认值，供 runqemu 指定 QEMU 的 -bios。例如，为 qemuarm64 仿真 U-Boot，可设置:

QB_DEFAULT_BIOS = "u-boot.bin"

此例假定 U-Boot 配方已构建，且 u-boot.bin 已部署到 DEPLOY_DIR_IMAGE。

备注

使用 runqemu 时，BIOS 环境变量优先于此变量。

QB_DEFAULT_FSTYPE 

控制默认启动的文件系统类型，以 DEPLOY_DIR_IMAGE 中根文件系统镜像的扩展名表示，例如 ext4.zst。

QB_DEFAULT_KERNEL 

使用 runqemu 时，控制 DEPLOY_DIR_IMAGE 中默认启动的 Linux 内核镜像，例如 bzImage。

QB_DRIVE_TYPE 

使用 runqemu 时指定仿真的驱动器类型。有效值：

/dev/hd：IDE 驱动器。
/dev/mmcblk：SD 卡。
/dev/sd：SCSI 驱动器。
/dev/vd：VirtIO 驱动器。
/dev/vdb：块 VirtIO 驱动器。

QB_GRAPHICS 

使用 runqemu 时控制仿真的 QEMU 显卡类型，例如 -vga std。

运行 QEMU 时会将该值追加到参数列表。

QB_KERNEL_CMDLINE_APPEND 

控制传给 QEMU -append 的选项，即 Linux 内核命令行。

例如:

QB_KERNEL_CMDLINE_APPEND = "console=ttyS0"

QB_MEM 

控制分配给仿真机器的内存量，指定方式如下:

QB_MEM = "-m 512"

QB_NETWORK_DEVICE 

使用 runqemu 时控制 QEMU 实例化的网络设备，必须与 QB_TAP_OPT 兼容。

例如:

QB_NETWORK_DEVICE = "-device virtio-net-pci,netdev=net0,mac=@MAC@"

runqemu 用预定义 MAC 地址替换 @MAC@。

QB_NFSROOTFS_EXTRA_OPT 

使用 runqemu 时，控制追加到 Linux 内核命令行 NFS 根文件系统选项的额外内容。

例如:

QB_NFSROOTFS_EXTRA_OPT = "wsize=4096,rsize=4096"

QB_OPT_APPEND 

使用 runqemu 时，控制启动 QEMU 时追加的通用选项。

QB_RNG 

使用 runqemu 时，控制主机随机数生成器直通。系统模式熵不足时可加速启动。

例如:

QB_RNG = "-object rng-random,filename=/dev/urandom,id=rng0 -device virtio-rng-pci,rng=rng0"

QB_ROOTFS_EXTRA_OPT 

使用 runqemu 时，控制追加到根文件系统设备选项的额外内容。

QB_SERIAL_OPT 

使用 runqemu 时控制串口选项。

例如:

QB_SERIAL_OPT = "-serial mon:stdio"

QB_SMP 

使用 runqemu 时控制 QEMU 客户机可用 CPU 核数，每个核心映射为主机一个线程。

例如:

QB_SMP = "-smp 8"

QB_TAP_NAMESERVER 

使用 runqemu 时，控制 QEMU 客户机默认的名称服务器。

QB_TAP_OPT 

使用 runqemu 时控制 tap 模式网络选项。

例如:

QB_TAP_OPT = "-netdev tap,id=net0,ifname=@TAP@,script=no,downscript=no"

runqemu 会将 @TAP@ 替换为实际使用的 tap 接口，如 tap0、tap1。

RANLIB 

运行 ranlib 的最小命令与参数。

RCONFLICTS 

与软件包冲突的包列表。必须先移除冲突包，才能安装软件包。

与所有包控制变量一样，必须使用软件包名称覆盖，例如:

RCONFLICTS:${PN} = "another_conflicting_package_name"

OpenEmbedded 使用的 BitBake 支持带版本的依赖，并屏蔽不同打包格式的语法差异。 RCONFLICTS 指定版本的通用语法如下:

RCONFLICTS:${PN} = "package (operator version)"

operator 可以为：

=
<
>
<=
>=

例如，以下指定 foo 的 1.2 或更高版本:

RCONFLICTS:${PN} = "foo (>= 1.2)"

RDEPENDS 

列出软件包的运行时依赖，即为了正常运行必须安装的其他包。以下赋值声明 foo 需要 bar 和 baz:

RDEPENDS:foo = "bar baz"

最常见的运行时依赖会自动检测并添加，因此多数配方不需设置 RDEPENDS。详情见 Yocto Project 概述与概念手册的 “自动添加运行时依赖”。

上述赋值使 do_package_write_* 写出 foo 时，将 bar 和 baz 声明为其内部依赖。具体方式取决于 PACKAGE_CLASSES 选择的包格式。包管理器安装时会知道还需安装依赖包。

为确保 bar 和 baz 被构建，此赋值也会加入任务依赖：从本配方的 do_build （不要与 do_compile 混淆）指向生成 bar、baz 的配方的 do_package_write_*。

RDEPENDS 列出的必须是软件包名，而非配方名。两者通常相同，但此处提供的是包名。配方默认生成的包列表见 PACKAGES。

该变量作用于正在构建的软件包，因此始终应附加包名，因为一个配方可以构建多个包。例如，开发包依赖 perl 时:

RDEPENDS:${PN}-dev += "perl"

此例中开发包依赖 perl，因此变量包含 ${PN}-dev 包名。

备注

RDEPENDS:${PN}-dev 默认包含 ${PN}，由 meta/conf/bitbake.conf 设置。修改时不要意外移除它，应用 "+=" 而不是 "="。

包名必须与 PACKAGES 中一致。PKG 可指定最终包的其他名称，例如 debian 用它重命名，但不能在 RDEPENDS 中使用最终名称，因为该变量应独立于包格式。

BitBake 支持带版本的依赖，并屏蔽不同包格式的语法差异。通用语法如下:

RDEPENDS:${PN} = "package (operator version)"

operator 可以为：

=
<
>
<=
>=

version 填入版本号。

备注

可用 EXTENDPKGV 提供完整包版本。

例如，以下依赖 foo 1.2 或更高版本:

RDEPENDS:${PN} = "foo (>= 1.2)"

构建时依赖见 DEPENDS。任务与依赖的更多信息见 BitBake 用户手册的 “Tasks”及 “Dependencies”。

READELF 

运行 readelf 的最小命令与参数。

RECIPE_MAINTAINER 

定义配方维护者姓名与电子邮件地址，供提交变更的用户参考，也供自动工具发送漏洞或源码更新等通知。

可在发行版全局 maintainers.inc 中定义:

meta/conf/distro/include/maintainers.inc:RECIPE_MAINTAINER:pn-sysvinit = "Ross Burton <ross.burton@arm.com>"

也可直接在配方中定义，例如 libgpiod:

RECIPE_MAINTAINER = "Bartosz Golaszewski <brgl@bgdev.pl>"

RECIPE_NO_UPDATE_REASON 

如果配方不应升级为更新的上游版本，可在配方中用此变量说明原因。 devtool check-upgrade-status 会显示它，见 “检查配方的升级状态”。

RECIPE_SYSROOT 

指向填充了 DEPENDS 指定配方所提供全部文件的目录。可以把它视为配方自己的根目录 /，编译器从中查找头文件及其他所需文件。

根据配方类型与构建目标，用它定义 STAGING_DIR_HOST 或 STAGING_DIR_TARGET。

例如：

#include <header.h> 要求 header.h 位于 "${RECIPE_SYSROOT}/usr/include"。
-lexample 要求 libexample.so 位于 "${RECIPE_SYSROOT}/lib" 或系统根目录中的其他库目录。

默认 "${WORKDIR}/recipe-sysroot"，不要修改。

RECIPE_SYSROOT_NATIVE 

类似 RECIPE_SYSROOT，但文件由 native 配方提供，使面向目标机器构建的配方能使用本机工具。

用于定义 STAGING_DIR_NATIVE。

默认 "${WORKDIR}/recipe-sysroot-native"，不要修改。

RECIPE_UPGRADE_EXTRA_TASKS 

使用 devtool upgrade 升级时，指定新源码解包后执行的任务，空格分隔。

部分配方升级解包后需要额外任务，例如继承 cargo-update-recipe-crates 的配方，每当 Cargo.toml/Cargo.lock 变化，都需运行 do_update_crates。

REPODIR 

见 BitBake 手册的 REPODIR。

REQUIRED_COMBINED_FEATURES 

继承 features_check 时，指定 OpenEmbedded Build System 构建配方所需的组合功能，即 MACHINE_FEATURES 与 DISTRO_FEATURES 的交集。列表中的任一功能若不在当前 COMBINED_FEATURES 中，就跳过配方；尝试构建时会报错。

REQUIRED_DISTRO_FEATURES 

继承 features_check 时，指定构建配方所需的发行版功能。列表中任一功能若不在当前 DISTRO_FEATURES 中，就跳过配方；尝试构建时会报错。

REQUIRED_IMAGE_FEATURES 

继承 features_check 时，指定 OpenEmbedded Build System 构建配方所需的镜像功能。列表中任一功能若不在当前 IMAGE_FEATURES 中，就跳过配方；尝试构建时会报错。

与其他 REQUIRED_*_FEATURES 不同，它仅针对镜像配方，因为 IMAGE_FEATURES 由 core-image 处理。但也可在发行版等 Configuration File 中设置，让要求适用于使用此 DISTRO 的全部镜像。

REQUIRED_MACHINE_FEATURES 

继承 features_check 时，指定 OpenEmbedded Build System 构建配方所需的 MACHINE_FEATURES。列表中任一功能若不在当前 MACHINE_FEATURES 中，就跳过配方；尝试构建时会报错。

REQUIRED_TUNE_FEATURES 

继承 features_check 时，指定 OpenEmbedded Build System 构建配方所需的调优功能。列表中任一功能若不在当前 TUNE_FEATURES 中，就跳过配方；尝试构建时会报错。

REQUIRED_VERSION 

多版本配方可用时指定首选版本。行为与 PREFERRED_VERSION 相同，但指定版本不可用时会报错并立即停止构建。

同一配方同时设置两者时，REQUIRED_VERSION 优先。

RETAIN_DIRS_ALWAYS 

继承 retain 时，指定始终归档的配方专属目录，空格分隔，不论构建是否失败。

RETAIN_DIRS_FAILURE 

继承 retain 时，指定配方构建失败时归档的专属目录，空格分隔。

RETAIN_DIRS_GLOBAL_ALWAYS 

继承 retain 时，指定始终归档、非配方专属的目录，空格分隔，不论构建是否失败。

RETAIN_DIRS_GLOBAL_FAILURE 

继承 retain 时，指定构建失败时归档、非配方专属的目录，空格分隔。

RETAIN_ENABLED 

禁用 retain 创建工作目录压缩包。当通过 INHERIT 全局继承时，可为特定配方设置以禁用。

RETAIN_IGNORE_TASKS 

继承 retain 时，列出不应触发保留的任务。

RETAIN_OUTDIR 

继承 retain 时，指定保存工作目录压缩包的位置，默认 ${TMPDIR}/retain。

RETAIN_TARBALL_SUFFIX 

继承 retain 时，指定工作目录压缩包后缀，默认 ${DATETIME}.tar.gz。

RM_WORK_EXCLUDE 

启用 rm_work 时，指定不删除工作目录的配方。详情见“rm_work”。

RM_WORK_EXCLUDE_ITEMS 

启用 rm_work 时，指定相对配方 WORKDIR 需要保留的文件或目录，详情见“rm_work”。

ROOT_HOME 

定义 root 主目录。BitBake 配置默认如下:

ROOT_HOME ??= "/home/root"

备注

采用此默认值可能是因为部分嵌入式方案使用只读根文件系统，希望将可写数据集中存放。

设置 INIT_MANAGER = systemd 时，默认改为:

ROOT_HOME ?= "/root"

也可在发行版配置或 build/conf/local.conf 中覆盖。

ROOTFS 

指定作为根文件系统包含的文件系统镜像。

这是 image-live 使用的可选变量。

ROOTFS_POSTINSTALL_COMMAND 

指定构建系统安装软件包后调用的函数，空格分隔:

ROOTFS_POSTINSTALL_COMMAND += "function"

函数中的命令如需根文件系统路径，可用 ${IMAGE_ROOTFS}，它指向最终成为根文件系统镜像的目录。详情见 IMAGE_ROOTFS。

ROOTFS_POSTPROCESS_COMMAND 

指定构建系统创建根文件系统后调用的函数，空格分隔:

ROOTFS_POSTPROCESS_COMMAND += "function"

函数中的命令如需根文件系统路径，可用 ${IMAGE_ROOTFS}，它指向最终成为根文件系统镜像的目录。详情见 IMAGE_ROOTFS。

ROOTFS_POSTUNINSTALL_COMMAND 

指定构建系统移除多余包后调用的函数。镜像禁用运行时包管理时，会移除 base-passwd、shadow、update-alternatives 等包。函数以空格分隔:

ROOTFS_POSTUNINSTALL_COMMAND += "function"

函数中的命令如需根文件系统路径，可用 ${IMAGE_ROOTFS}，它指向最终成为根文件系统镜像的目录。详情见 IMAGE_ROOTFS。

ROOTFS_PREPROCESS_COMMAND 

指定构建系统创建根文件系统前调用的函数，空格分隔:

ROOTFS_PREPROCESS_COMMAND += "function"

函数中的命令如需根文件系统路径，可用 ${IMAGE_ROOTFS}，它指向最终成为根文件系统镜像的目录。详情见 IMAGE_ROOTFS。

RPMBUILD_EXTRA_PARAMS 

指定 rpmbuild 命令的额外用户自定义参数。

RPROVIDES 

软件包同时提供的包名别名列表，可在构建和目标运行时满足其他包的 RDEPENDS。

备注

包自身名称已隐式包含在此列表中。

与所有包控制变量一样，必须使用包名覆盖，例如:

RPROVIDES:${PN} = "widget-abi-2"

RRECOMMENDS 

列出扩展当前软件包可用性的其他包。当前包不依赖它们才能成功构建，而是用它们提供扩展功能。必需的运行时依赖见 RDEPENDS。

安装当前包时，包管理器会自动安装推荐包。可用 BAD_RECOMMENDATIONS、NO_RECOMMENDATIONS 和 PACKAGE_EXCLUDE 阻止安装。

推荐包可以不实际生成，但必须有配方通过 PACKAGES、 PACKAGES_DYNAMIC 或 RPROVIDES 声明提供它，否则构建报错。若有该配方但未生成此包，构建仍可继续。

变量作用于软件包，必须附加覆盖，指定被扩展功能的包。例如，为开发包扩展无线支持:

RRECOMMENDS:${PN}-dev += "wireless_package_name"

包名 ${PN}-dev 必须与 PACKAGES 命名空间一致，即 debian 等类重命名之前的名称。

BitBake 支持带版本的推荐依赖，并屏蔽打包格式语法差异。通用语法:

RRECOMMENDS:${PN} = "package (operator version)"

operator 可为：

=
<
>
<=
>=

例如，推荐 foo 1.2 或更高版本:

RRECOMMENDS:${PN} = "foo (>= 1.2)"

RREPLACES 

本包替换的其他包列表。升级时，包管理器据此决定用哪个包替换其他包。若还要同时删除旧包，必须也将旧包名加入 RCONFLICTS。

与所有包控制变量一样，必须使用包名覆盖，例如:

RREPLACES:${PN} = "other_package_being_replaced"

BitBake 支持带版本的替换，并屏蔽打包格式语法差异。通用语法:

RREPLACES:${PN} = "package (operator version)"

operator 可为：

=
<
>
<=
>=

例如，替换 foo 1.2 或更高版本:

RREPLACES:${PN} = "foo (>= 1.2)"

RSUGGESTS 

安装软件包时建议包管理器额外安装的包。并非所有包管理器都支持。仅在目标系统通过包管理器从软件包源安装时生效。

与所有包控制变量一样，必须使用包名覆盖，例如:

RSUGGESTS:${PN} = "useful_package another_package"

更多信息见 Yocto Project 开发任务手册的使用运行时软件包管理。

RUST_CHANNEL 

指定构建 stable、beta 或 nightly Rust，默认 stable。其他值不保证始终可用，使用风险自担。

S 

Build Directory 中解包后的配方源码位置，默认 ${UNPACKDIR}/${BPN}-${PV}。 BPN 为基础配方名，PV 为版本。若压缩包解出目录不是 ${BPN}-${PV}，或源码来自 Git、Subversion 等 SCM，必须在配方中设置 S，告知构建系统源码位置。

例如，Source Directory 顶层为 bitbake-builds，默认 Build Directory 为 bitbake-builds/build， db 配方解包工作目录如下:

bitbake-builds/build/tmp/work/qemux86-poky-linux/db/5.1.19-r3/sources/db-5.1.19

解包源码位于 db-5.1.19 文件夹。

SANITY_REQUIRED_UTILITIES 

指定 BitBake 初始健全性检查应检查的命令行工具。主机缺少任一个，BitBake 就立即报错退出。

SANITY_TESTED_DISTROS 

已测试主机发行版标识符列表，由发行商 ID 加版本构成，从 lsb_release 或 /etc/lsb-release 获取。列表以显式换行符 \n 分隔。若列表非空且当前 NATIVELSBSTRING 不在其中，构建系统会警告该主机发行版未经测试。

SBOM_CVE_CHECK_EXPORT_VARS 

继承 sbom-cve-check 时，列出声明待生成导出文件的变量。

每个变量必须设置 type 和 ext 标志：

type 作为 sbom-cve-check 的 --export-type 参数。
ext 为文件扩展名／后缀，输出名为 ${IMAGE_NAME}${ext}。

例如:

SBOM_CVE_CHECK_EXPORT_VARS = "SBOM_CVE_CHECK_EXPORT_SPDX3"
SBOM_CVE_CHECK_EXPORT_SPDX3[type] = "spdx3"
SBOM_CVE_CHECK_EXPORT_SPDX3[ext] = ".sbom-cve-check.spdx.json"

SBOM_CVE_CHECK_EXTRA_ARGS 

继承 sbom-cve-check 时，向 sbom-cve-check 传入额外参数。

更多信息见工具文档。

SBOM_CVE_CHECK_SCAN_SCOPE 

继承 sbom-cve-check 时，控制扫描目标、native 或两者。

有效值：

target（默认）：扫描目标上下文的配方。
native：扫描 native 上下文。
both：扫描目标和 native 两种上下文。

SBOM_CVE_CHECK_SHOW_WARNINGS 

继承 sbom-cve-check 时，控制发现 Unpatched CVE 后是否警告。输出示例：

WARNING: core-image-minimal-1.0-r0 do_sbom_cve_check: glibc-2.43+git: Found unpatched CVEs: CVE-2010-4756

"1" 显示警告，"0" 不显示。

更多信息见检查漏洞。

SDK_ARCH 

SDK 的目标架构。通常不直接设置，而使用 SDKMACHINE。

SDK_ARCHIVE_TYPE 

指定 SDK 归档类型。有效值：

tar.xz （默认）
tar.zst
7zip
zip

只能指定一种。

SDK_AS_ARCH 

构建 nativesdk 的架构专用汇编器标志，默认等于 BUILD_AS_ARCH。

SDK_BUILDINFO_FILE 

使用 image-buildinfo 时，指定 SDK 内写入构建信息的文件，默认 /buildinfo。

SDK_CC_ARCH 

构建 nativesdk 的架构专用 C 编译器标志，默认等于 BUILD_CC_ARCH。

SDK_CUSTOM_TEMPLATECONF 

构建可扩展 SDK 时，若为 "1" 且 Build Directory （TOPDIR）存在 conf/templateconf.cfg，则将该文件复制到 SDK。

SDK_DEPLOY 

populate_sdk_base 设置并用于部署 SDK 的目录，定义如下:

SDK_DEPLOY = "${TMPDIR}/deploy/sdk"

SDK_DIR 

构建系统创建 SDK 输出时使用的父目录，由 populate_sdk_base 定义为:

SDK_DIR = "${WORKDIR}/sdk"

备注

此目录属于 WORKDIR，是临时目录。最终输出目录为 SDK_DEPLOY。

SDK_EXT_TYPE 

控制是否将共享状态产物复制到可扩展 SDK。默认 full 会复制全部所需产物，minimal 则不包含它们。

备注

使用 minimal 时，必须在 SDK 配置设置 SSTATE_MIRRORS，以便按需获取。

SDK_FEATURES 

定义标准 SDK 或可扩展 SDK 的功能列表，在 do_populate_sdk 或 do_populate_sdk_ext 时解析。类似 IMAGE_FEATURES，但针对 SDK。

完整列表见 SDK 功能。

SDK_HOST_MANIFEST 

SDK 主机部分的清单文件，列出构成该部分的所有已安装包，每包一行:

packagename packagearch version

populate_sdk_base 定义如下:

SDK_HOST_MANIFEST = "${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.host.manifest"

位置由 SDK_DEPLOY 和 TOOLCHAIN_OUTPUTNAME 推导。

SDK_INCLUDE_PKGDATA 

为 "1" 时，在可扩展 SDK 包含 world 目标全部配方的包数据。这样 devtool search 能找到这些配方，devtool add 也能更有效地映射依赖。

备注

这会构建整个 world，显著增加构建时间，也略微增大 SDK。

SDK_INCLUDE_TOOLCHAIN 

为 "1" 时，在可扩展 SDK 包含工具链。尤其适用于 SDK_EXT_TYPE 为 minimal，既要较小 SDK 又要可用工具链的场景。例如，希望从 IDE 或其他工具直接使用，而不额外安装工具链。

SDK_EXT_TYPE 为 minimal 时默认 "0"，为 full 时默认 "1"。

SDK_LD_ARCH 

构建 nativesdk 的架构专用链接器标志，默认等于 BUILD_LD_ARCH。

SDK_NAME 

SDK 输出文件的基础名。默认值设置于 meta-poky/conf/distro/poky.conf，由 DISTRO、TCLIBC、SDKMACHINE、IMAGE_BASENAME、 TUNE_PKGARCH 和 MACHINE 推导:

SDK_NAME = "${DISTRO}-${TCLIBC}-${SDKMACHINE}-${IMAGE_BASENAME}-${TUNE_PKGARCH}-${MACHINE}"

SDK_OS 

指定 SDK 所针对的操作系统，默认 BUILD_OS。

SDK_OUTPUT 

构建系统创建 SDK 输出的位置，由 populate_sdk_base 定义:

SDK_DIR = "${WORKDIR}/sdk"
SDK_OUTPUT = "${SDK_DIR}/image"
SDK_DEPLOY = "${DEPLOY_DIR}/sdk"

备注

通过 SDK_DIR 属于 WORKDIR，因此是临时目录。最终输出目录为 SDK_DEPLOY。

SDK_PACKAGE_ARCHS 

与 SDK 机器兼容的架构列表，自动设置，通常不应手改。空格分隔，按优先级排列，默认 "all any noarch ${SDK_ARCH}-${SDKPKGSUFFIX}"。

SDK_POSTPROCESS_COMMAND 

指定 SDK 创建后调用的函数，空格分隔：

SDK_POSTPROCESS_COMMAND += "function"

函数命令若需 SDK 路径，可用 ${SDK_DIR}，它指向创建 SDK 输出的父目录，详情见 SDK_DIR。

SDK_PREFIX 

nativesdk 的工具链程序前缀。构建 nativesdk 时用它设置 TARGET_PREFIX，默认 "${SDK_SYS}-"。

SDK_RECRDEP_TASKS 

加入可扩展 SDK 的共享状态任务列表。默认包含：

尽管此变量默认 ""，以上四个任务总会加入。若需额外任务，例如构建 SDK_TARGETS 必需的自定义任务，应通过此变量指定。

SDK_SYS 

指定 SDK 构建所针对的系统，包括架构和操作系统。

构建系统根据 SDK_ARCH、SDK_VENDOR、SDK_OS 自动设置，无需自行设置。

SDK_TARGET_MANIFEST 

SDK 目标部分的清单，列出构成该部分的全部已安装包，每包一行:

packagename packagearch version

populate_sdk_base 定义如下:

SDK_TARGET_MANIFEST = "${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.target.manifest"

位置由 SDK_DEPLOY 和 TOOLCHAIN_OUTPUTNAME 推导。

SDK_TARGETS 

标准或可扩展 SDK 安装时，从共享状态安装的目标列表，默认 "${PN}"，即构建 SDK 所用的镜像。

这是内部变量，通常不修改。

SDK_TITLE 

SDK 安装器显示的标题，默认基于 DISTRO_NAME 或 DISTRO，在 populate_sdk_base 中定义:

SDK_TITLE ??= "${@d.getVar('DISTRO_NAME') or d.getVar('DISTRO')} SDK"

poky 参考发行版设为 "Poky (Yocto Project Reference Distro)"。

修改方法见 eSDK 手册的 “修改可扩展 SDK 安装程序标题”。

SDK_UPDATE_URL 

可扩展 SDK 更新服务器的可选 URL。设置后，SDK 内运行 devtool sdk-update 默认使用此服务器。

SDK_VENDOR 

指定 SDK 供应商名称。

SDK_VERSION 

指定 SDK 版本。Poky 配置 /meta-poky/conf/distro/poky.conf 的默认设置为:

SDK_VERSION = "${@d.getVar('DISTRO_VERSION').replace('snapshot-${METADATA_REVISION}', 'snapshot')}"

另见 DISTRO_VERSION 和 METADATA_REVISION。

SDK_ZIP_OPTIONS 

SDK_ARCHIVE_TYPE 为 zip 时，传给 zip 命令的额外选项，默认 "-y"。

SDKEXTPATH 

可扩展 SDK 的默认安装目录，基于 DISTRO，在 populate_sdk_base 中定义:

SDKEXTPATH ??= "~/${@d.getVar('DISTRO')}_sdk"

Poky 参考发行版设为 "poky_sdk"。

修改方法见 eSDK 手册的 “修改 SDK 的默认安装目录”。

SDKIMAGE_FEATURES 

等效于 IMAGE_FEATURES，但应用于用以下命令从镜像生成的 SDK:

$ bitbake -c populate_sdk imagename

SDKMACHINE 

SDK 所针对的运行机器。SDK 可在此值指定的目标上运行。该值对应已启用层内 conf/machine-sdk/ 下的 .conf 文件。 OpenEmbedded-Core 提供 aarch64、i586、i686、ppc64、ppc64le、x86_64 等。

默认 BUILD_ARCH，即针对构建主机架构生成 SDK。

备注

不可在发行版配置文件设置，否则不会生效。

SDKPATH 

收集 SDK 组件并构建安装器所用的路径。

SDKPATHINSTALL 

构建系统生成的 SDK 向用户建议的安装路径。运行安装脚本时显示为默认位置，用户可覆盖。

SDKTARGETSYSROOT 

SDK 安装到默认 SDKPATHINSTALL 后，交叉编译所用系统根目录的完整路径。

SECTION 

软件包所属分类，包管理工具可使用此变量。

SELECTED_OPTIMIZATION 

为目标构建时传给 C 编译器的优化标志，通过 TARGET_CFLAGS 默认值传递。

通常取 FULL_OPTIMIZATION；DEBUG_BUILD = "1" 时，使用 DEBUG_OPTIMIZATION。

SERIAL_CONSOLES 

定义通过 getty 启用的串口控制台。波特率与 TTY 设备名用分号分隔，多设备用空格分隔:

SERIAL_CONSOLES = "115200;ttyS0 115200;ttyS1"

SETUPTOOLS_BUILD_ARGS 

继承 setuptools3 时，在 setuptools3_do_compile() 向 setup.py build 传入额外参数。

SETUPTOOLS_SETUP_PATH 

继承 setuptools3 时，若 setup.py 不在源码根目录 S，用此变量指定其所在目录。例如源码来自 Git，setup.py 位于 python/pythonmodule:

SETUPTOOLS_SETUP_PATH = "${S}/python/pythonmodule"

SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS 

指定不应用于计算任务签名的跨配方任务依赖。例如:

SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS += "intone->mplayer2"

上例中 intone 依赖 mplayer2。

依赖左侧可用特殊标记 "*"，匹配除右侧配方之外的全部配方，例如:

SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS += "*->quilt-native"

上例中，除 quilt-native 本身之外的所有配方，计算签名时忽略 quilt-native 的任务签名。

可借此移除影响签名、因依赖配方变化而强制重建的依赖关系。

备注

若错误地排除依赖，第一配方构建后第二配方的接口改变，可能使软件在运行时损坏。

SIGGEN_EXCLUDERECIPES_ABISAFE 

完全稳定、不会变化的配方列表。ABI 体现于构建任务输出。此变量可移除影响任务签名的跨配方依赖，避免配方变化导致强制重建。

备注

错误加入条目可能导致运行时故障，尤其是在其他配方构建后接口发生变化时。

SIGGEN_LOCKEDSIGS 

锁定任务列表，格式如下:

SIGGEN_LOCKEDSIGS += "<package>:<task>:<signature>"

共享状态缓存若存在指定 task、package 的 signature，BitBake 使用缓存而非重建。不存在时则构建任务，下次使用缓存。

例如:

SIGGEN_LOCKEDSIGS += "bc:do_compile:09772aa4532512baf96d433484f27234d4b7c11dd9cda0d6f56fa1b7ce6f25f0"

可用以下命令获取 bc 全部任务的签名:

bitbake -S none bc

然后检查 build/tmp/stamps/<arch>/bc 中形如 <PV>.do_compile.sigdata.09772aa4532512baf96d433484f27234d4b7c11dd9cda0d6f56fa1b7ce6f25f0 的文件。

也可用 bblock 自动生成此行。

SIGGEN_LOCKEDSIGS_TASKSIG_CHECK 

指定任务签名检查的调试级别，支持三级：

info：任务锁定且当前签名匹配时显示 Note 提醒。
warn：任务锁定但当前签名不匹配时显示 Warning。
error：与 warn 相同，但显示 Error 并中止。

SIGGEN_LOCKEDSIGS_TYPES 

SIGGEN_LOCKEDSIGS 允许的覆盖，主要用于架构专属锁定。常用值为 ${PACKAGE_ARCHS}:

SIGGEN_LOCKEDSIGS_TYPES += "${PACKAGE_ARCHS}"

SIGGEN_LOCKEDSIGS_core2-64 += "bc:do_compile:09772aa4532512baf96d433484f27234d4b7c11dd9cda0d6f56fa1b7ce6f25f0"
SIGGEN_LOCKEDSIGS_cortexa57 += "bc:do_compile:12178eb6d55ef602a8fe638e49862fd247e07b228f0f08967697b655bfe4bb61"

此例仅为 core2-64 和 cortexa57 锁定 bc 的 do_compile， mips32r2 等其他架构不受影响。

SITEINFO_BITS 

目标 CPU 位数，应为 "32" 或 "64"。

SITEINFO_ENDIANNESS 

目标字节序，"le" 为小端，"be" 为大端。

SKIP_FILEDEPS 

从 RPM 包的 Provides 区段移除全部文件。包含 libstdc++、glibc 等预构建二进制和库的软件包需要这样处理。

在 configuration file 中设为 "1" 启用:

SKIP_FILEDEPS = "1"

SKIP_RECIPE 

阻止构建指定配方。以 PN 作为变量标志 varflag，并提供原因，尝试构建时会报告。

可在 build/conf/local.conf 或发行版配置中使用，以下阻止构建 myrecipe:

SKIP_RECIPE[myrecipe] = "Not supported by our organization."

SOC_FAMILY 

以冒号分隔，将使用同系列 SoC 的机器分组。通常在所有相关机器配置共同包含的 .inc 文件中设置。

备注

必须包含 conf/machine/include/soc-family.inc，才会加入 MACHINEOVERRIDES。

SOLIBS 

目标共享库的后缀。Linux 系统默认 ".so.*"，由 meta/conf/bitbake.conf 定义。

FILES:${PN} 默认值引用此变量。

SOLIBSDEV 

目标共享库开发用符号链接的后缀。Linux 默认 ".so"，由 meta/conf/bitbake.conf 定义。

FILES:${PN}-dev 默认值引用此变量。

SOURCE_DATE_EPOCH 

以自 UNIX 纪元（1970-01-01 00:00:00 UTC）起的秒数表示日期，多个构建系统用它固定二进制中的时间戳，许多上游项目已支持。

详情见官方规范。

meta/lib/oe/reproducible.py 根据每个配方的源码计算该值。

配方如需覆盖默认行为，应自行设置:

SOURCE_DATE_EPOCH = "1613559011"

SOURCE_MIRROR_FETCH 

获取文件以创建源码镜像时，在 configuration file 中设为 "1"，会获取所有配方源码，不论其是否兼容当前配置。 COMPATIBLE_MACHINE 和／或 COMPATIBLE_HOST 指定其他机器或主机时，配方被视为不兼容。

备注

仅在创建源码镜像时设置，普通构建不要设置。

SOURCE_MIRROR_URL 

定义自己的 PREMIRRORS，在尝试 SRC_URI 上游之前优先获取。

必须全局继承 own-mirrors 并提供镜像 URL。语法:

INHERIT += "own-mirrors"
SOURCE_MIRROR_URL = "http://example.com/my_source_mirror"

备注

只能指定单个 URL。

备注

镜像若需用户名和密码，必须配置 build host，使构建系统能够获取。

推荐在 $HOME/.netrc 设置以下参数，HOME 是 build host 主目录:

machine example.com
login <user>
password <password>

文件权限必须为 400 或 600，防止其他用户读取:

chmod 600 "$HOME/.netrc"

也可在 SOURCE_MIRROR_URL 的 URL 中通过 user 和 pswd 参数配置:

SOURCE_MIRROR_URL = "http://example.com/my_source_mirror;user=<user>;pswd=<password>"

SPDX_AUTHORS 

列出 SPDX 数据作者。与 SPDX_IMAGE_SUPPLIER 等主体变量略有不同：基础变量提供后缀列表，用于构造所创建作者的变量前缀。例如:

SPDX_AUTHORS = "myorg myself"
SPDX_AUTHORS_myorg_name = "My Organization"
SPDX_AUTHORS_myorg_type = "organization"
SPDX_AUTHORS_myself_name = "My Name"
SPDX_AUTHORS_myself_type = "Person"

可通过 _ref 后缀引用其他对象，例如:

SPDX_AUTHORS_myself_ref = "SPDX_IMAGE_SUPPLIER"

其他变量也可用正确前缀引用作者:

SPDX_IMAGE_SUPPLIER_ref = "SPDX_AUTHORS_myorg"

SPDX_BUILD_HOST 

描述构建主机的基础变量名。其值必须是 SPDX_IMPORTS 中的键，使生成的 SPDX 能引用外部定义的主机身份数据。

要求 SPDX_INCLUDE_BITBAKE_PARENT_BUILD 为 "1"。

警告

设置后 SPDX 输出不再可复现，因为主机身份可能随构建而变。

另见 SPDX_INCLUDE_BITBAKE_PARENT_BUILD、SPDX_IMPORTS、 SPDX_INVOKED_BY 和 SPDX_ON_BEHALF_OF。

SPDX_CONCLUDED_LICENSE 

覆盖各 SBOM 软件包的 hasConcludedLicense 对象。分析后认定实际许可证与原始许可证字符串不同时可使用。

有两种设置方式：

对整个配方:

SPDX_CONCLUDED_LICENSE = "MIT & Apache-2.0"

对配方生成的单个包:

SPDX_CONCLUDED_LICENSE:${PN} = "MIT & Apache-2.0"

SPDX_CUSTOM_ANNOTATION_VARS 

使用配方变量值，将 SPDX 注释关联到配方:

ANNOTATION1 = "First annotation for recipe"
ANNOTATION2 = "Second annotation for recipe"
SPDX_CUSTOM_ANNOTATION_VARS = "ANNOTATION1 ANNOTATION2"

会在配方 .sdpx.json 输出新增区块:

"annotations": [
  {
    "annotationDate": "2023-04-18T08:32:12Z",
    "annotationType": "OTHER",
    "annotator": "Tool: oe-spdx-creator - 1.0",
    "comment": "ANNOTATION1=First annotation for recipe"
  },
  {
    "annotationDate": "2023-04-18T08:32:12Z",
    "annotationType": "OTHER",
    "annotator": "Tool: oe-spdx-creator - 1.0",
    "comment": "ANNOTATION2=Second annotation for recipe"
  }
],

SPDX_FILE_EXCLUDE_PATTERNS 

空格分隔的 Python 正则表达式列表，启用 SPDX_INCLUDE_SOURCES 时，用 re.search() 匹配路径并从生成的 SBOM 排除相应文件。

默认空，不排除任何文件。

示例:

SPDX_FILE_EXCLUDE_PATTERNS = "\\.patch$ \\.diff$ /test/ \\.pyc$ \\.o$"

另见 SPDX_INCLUDE_SOURCES。

SPDX_GIT_PURL_MAPPINGS 

空格分隔的 domain:purl_type 映射，配置 Git 下载源码的包 URL 生成。

例如 gitlab.example.com:pkg:gitlab 将该域名仓库映射为 pkg:gitlab 类型。

包 URL 的更多信息见 SPDX_PACKAGE_URLS。

SPDX_IMAGE_SUPPLIER 

描述镜像 SBOM 提供组织或个人的变量前缀。设置后通过 suppliedBy 属性关联到镜像 SBOM 的全部根元素。

根据此前缀读取以下主体信息：

SPDX_IMAGE_SUPPLIER_name：显示名称，必需。
SPDX_IMAGE_SUPPLIER_type：organization、person、software 或 agent，可选，默认 agent。
SPDX_IMAGE_SUPPLIER_comment：自由文本注释，可选。
SPDX_IMAGE_SUPPLIER_id_email：联系邮件，可选。

在镜像配方或 configuration file 中设置，例如:

SPDX_IMAGE_SUPPLIER_name = "Acme Corp"
SPDX_IMAGE_SUPPLIER_type = "organization"

也可用 SPDX_IMAGE_SUPPLIER_ref 引用另一变量前缀创建的主体，例如:

SPDX_IMAGE_SUPPLIER_ref = "SPDX_PACKAGE_SUPPLIER"

另见 SPDX_PACKAGE_SUPPLIER 和 SPDX_SDK_SUPPLIER。

SPDX_INCLUDE_BITBAKE_PARENT_BUILD 

为 "1" 时，SPDX 包含表示父 BitBake 调用的 Build 对象，使 SBOM 使用者能追踪触发构建的 CI/CD 作业或编排系统。

SPDX_INVOKED_BY、SPDX_ON_BEHALF_OF 和 SPDX_BUILD_HOST 必须启用此变量才生效。

警告

启用后 SPDX 不再可复现，因为每次运行的构建调用身份不同。

启用方式:

SPDX_INCLUDE_BITBAKE_PARENT_BUILD = "1"

另见 SPDX_BUILD_HOST、SPDX_INVOKED_BY、SPDX_ON_BEHALF_OF。

SPDX_INCLUDE_COMPILED_SOURCES 

类似 SPDX_INCLUDE_SOURCES，但仅包含编译主机工具和目标包所用源码。后者描述源码目录全部文件，此变量仅包含生成交付二进制文件的源码，排除未参与编译的文件。通过 do_package 生成的 debugsource 信息过滤。

外部工具因而可借助 SPDX 忽略未编入软件包的漏洞。

启用方式:

SPDX_INCLUDE_COMPILED_SOURCES = "1"

对 SPDX 2.2（4.1 langdale）而言，为 qemux86-64 构建 core-image-minimal 时，相比 SPDX_INCLUDE_SOURCES，此选项使 tmp/deploy/spdx 从 2GB 降到 1.6GB，因为仅包含已编译对象而不包含原始源码文件。

对 SPDX 3.0.1 JSON，此选项同时包含编译源码和原始源码文件，相当于 SPDX_INCLUDE_SOURCES = "1"，会显著增大 SBOM。例如 qemux86-64 的 core-image-minimal 未压缩 SBOM 可从几百 MB 增至数 GB。

SPDX_INCLUDE_KERNEL_CONFIG 

将 Linux 内核 .config 内容作为独立 build_Build 对象导出到配方 SPDX。每个 CONFIG_* 参数都会记录，并通过 ancestorOf 关联主内核对象。

备注

仅对 SPDX 3.0 输出有效，见 create-spdx。

启用方式:

SPDX_INCLUDE_KERNEL_CONFIG = "1"

独立内核配置对象改善可复现性、合规跟踪和构建时内核功能审计。

SPDX_INCLUDE_PACKAGECONFIG 

将配方 PACKAGECONFIG 功能导出到 SPDX。每项记录为 DictionaryEntry，键为 PACKAGECONFIG:<feature>，值按当前构建状态为 enabled 或 disabled。

备注

仅对 SPDX 3.0 输出有效，见 create-spdx。

启用方式:

SPDX_INCLUDE_PACKAGECONFIG = "1"

SPDX 会记录每个配方的构建配置，改善透明度、可复现性和安全审计，让使用者知道哪些可选功能被启用或禁用。

SPDX_INCLUDE_SOURCES 

向 Build Directory 下 tmp/deploy/spdx/MACHINE/recipes/ 的 spdx.json 添加构建主机工具和目标包所用源码文件的描述。 tmp/deploy/spdx/MACHINE 下 by-namespace 和 packages 子目录中的文件，也会加入对这些描述的引用。

启用方式:

SPDX_INCLUDE_SOURCES = "1"

对 SPDX 2.2（4.1 langdale），为 qemux86-64 构建 core-image-minimal 时，相比仅继承 create-spdx 而无选项， tmp/deploy/spdx 总大小增为 3 倍（此镜像增加 291 MiB）， tmp/deploy/images/MACHINE 中 IMAGE-MACHINE.spdx.tar.zst 增为 130 倍（增加 15 MiB）。

对 SPDX 3.0.1 JSON，包含源码会显著增加 SBOM，典型镜像可能增加数 GB。

SPDX_INCLUDE_VEX 

控制输出 SPDX 中的 VEX 信息。

可选值：

none：禁用全部 VEX。
current（默认）：包含上游源码尚未修复的漏洞。
all：包含所有历史已知漏洞，包括上游已修复项，可能体积大且处理慢。

SPDX_INVOKED_BY 

描述触发构建主体的变量前缀，SPDX 中每个 Build 通过 invokedBy 关联它。要求 SPDX_INCLUDE_BITBAKE_PARENT_BUILD 为 "1"。

子变量遵循 SPDX_IMAGE_SUPPLIER 的主体前缀约定：

SPDX_INVOKED_BY_name：触发主体显示名。
SPDX_INVOKED_BY_type：主体类型，如 CI 系统用 software。

CI 流水线触发构建的示例:

SPDX_INCLUDE_BITBAKE_PARENT_BUILD = "1"
SPDX_INVOKED_BY_name = "GitLab CI"
SPDX_INVOKED_BY_type = "software"

警告

主体身份随构建改变，设置后很可能使 SPDX 不可复现。

另见 SPDX_INCLUDE_BITBAKE_PARENT_BUILD、 SPDX_ON_BEHALF_OF、SPDX_BUILD_HOST。

SPDX_LICENSES 

SPDX 许可证标识符映射 JSON 的路径，将常用名称映射为生成 SBOM 的官方 SPDX 标识符。

默认指向 OpenEmbedded-Core (OE-Core) 中保存的 SPDX 映射副本，来源 https://github.com/spdx/license-list-data。

组织采用不同命名约定时，可覆盖以使用自定义映射。

SPDX_MULTILIB_SSTATE_ARCHS 

收集 SPDX 依赖时考虑的共享状态架构，启用 multilib 时包含其架构。

默认等于 SSTATE_ARCHS。

SPDX 类内部使用它，确保无论是否启用 multilib，都将相关依赖纳入 SBOM。

SPDX_NAMESPACE_PREFIX 

修改 spdxDocument 和 documentNamespace 的前缀，默认 http://spdx.org/spdxdoc。

SPDX_ON_BEHALF_OF 

描述委托主体的变量前缀，调用主体 SPDX_INVOKED_BY 代表它构建。要求 SPDX_INCLUDE_BITBAKE_PARENT_BUILD 为 "1"，若未同时设置 SPDX_INVOKED_BY 则无效。

子变量遵循 SPDX_IMAGE_SUPPLIER 的主体前缀约定：

SPDX_ON_BEHALF_OF_name：委托主体显示名。
SPDX_ON_BEHALF_OF_type：主体类型，例如 organization。

CI 代表客户组织构建的示例:

SPDX_INCLUDE_BITBAKE_PARENT_BUILD = "1"
SPDX_INVOKED_BY_name = "GitLab CI"
SPDX_INVOKED_BY_type = "software"
SPDX_ON_BEHALF_OF_name = "Acme Corp"
SPDX_ON_BEHALF_OF_type = "organization"

警告

主体身份随构建改变，设置后很可能使 SPDX 不可复现。

另见 SPDX_INCLUDE_BITBAKE_PARENT_BUILD、SPDX_INVOKED_BY、 SPDX_BUILD_HOST。

SPDX_PACKAGE_SUPPLIER 

描述构建产物提供者的变量前缀，与 SPDX_IMAGE_SUPPLIER 用法相同，但针对单个包而非镜像 SBOM。

通常在发行版 configuration file 设置以应用全部包，或在配方／bbappend 中设置以仅应用该配方的包。也支持 SPDX_PACKAGE_SUPPLIER:pn-<recipe> 覆盖:

SPDX_PACKAGE_SUPPLIER_name = "Acme Corp"
SPDX_PACKAGE_SUPPLIER_type = "organization"

另见 SPDX_IMAGE_SUPPLIER 和 SPDX_SDK_SUPPLIER。

SPDX_PACKAGE_URL 

供 SPDX 数据创建者按 Package URL 规范记录软件包 URL 字符串 software_packageUrl，默认空字符串。

SPDX_PACKAGE_URLS 

空格分隔的包 URL（PURL）列表。首项作为 packageUrl 属性，全部条目（含首项）列为外部引用。默认根据配方名、版本、层名生成 pkg:yocto URL。覆盖变量可替换默认值，追加或前置则可增加 URL。

SPDX_PACKAGE_VERSION 

控制 SPDX 3.0 JSON 的 software_packageVersion，默认 PV。

SPDX_PRETTY 

通过缩进和换行增强 SPDX 可读性，而非默认单行输出:

SPDX_PRETTY = "1"

文件约增大 20%，但需要用文本编辑器检查时推荐启用。

SPDX_SDK_SUPPLIER 

描述 SDK SBOM 提供者的基础变量名。设置后通过 suppliedBy 关联 SDK SBOM 的全部根元素。

与 SPDX_IMAGE_SUPPLIER 相同，但用于 SDK，包括 bitbake <image> -c populate_sdk 的镜像 SDK 和 bitbake meta-toolchain 的工具链 SDK。

通常在镜像配方或 configuration file 中设置。

未设置则不添加提供者信息。

另见 SPDX_IMAGE_SUPPLIER 和 SPDX_PACKAGE_SUPPLIER。

SPDX_UUID_NAMESPACE 

SPDX UUID 生成的命名空间，应为组织域名或唯一标识，确保不同构建和组织之间的 SPDX ID 全局唯一。

默认是 OpenEmbedded 管理的域名，可覆盖为自己的组织域名。

SPDXLICENSEMAP 

将常用许可证名称映射为 meta/files/common-licenses/ 中的 SPDX 对应名称。默认映射见 meta/conf/licenses.conf。

另见 LICENSE。

SPECIAL_PKGSUFFIX 

构建系统用于创建配方或包变体的 PN 前缀列表。指定在生成 BPN 等情况下应剥离的前缀。

SPL_BINARY 

第二阶段程序加载器（SPL）的文件类型。BeagleBone 等设备从 SPL 启动，可在 U-Boot 配方使用的 u-boot.inc 中声明 SPL 二进制类型。

u-boot.inc 默认设为 null，如下:

# Some versions of u-boot build an SPL (Second Program Loader) image that
# should be packaged along with the u-boot binary as well as placed in the
# deploy directory. For those versions they can set the following variables
# to allow packaging the SPL.
SPL_BINARY ?= ""
SPL_BINARYNAME ?= "${@os.path.basename(d.getVar("SPL_BINARY"))}"
SPL_IMAGE ?= "${SPL_BINARYNAME}-${MACHINE}-${PV}-${PR}"
SPL_SYMLINK ?= "${SPL_BINARYNAME}-${MACHINE}"

此变量帮助构造构建系统使用的各 SPL_* 变量。

更多信息见 BeagleBone 机器配置示例。

SPL_DTB_BINARY 

继承 uboot-sign 时，包含待编译 SPL 二进制文件名。

SPL_MKIMAGE_DTCOPTS 

uboot-sign 创建 FIT 时，通过 mkimage -D 传递的设备树编译器选项。未设置则不向 mkimage 传 -D。

uboot-config 默认设为 ""。

SPL_SIGN_ENABLE 

启用 U-Boot FIT 签名，默认 "0"，由 uboot-sign 使用。

SPL_SIGN_KEYDIR 

uboot-sign 签署 U-Boot FIT 所用 RSA 密钥与证书目录。

SPL_SIGN_KEYNAME 

uboot-sign 用于签署 FIT 的密钥名，文件位于 SPL_SIGN_KEYDIR。例如该目录含 dev.key 和 dev.crt 时，应设为 dev。

SPLASH 

image 用于选择启动画面应用的变量，设为应用的软件包名，默认 psplash。

SPLASH_IMAGES 

psplash 配方用它定制默认启动图像。

指定的 PNG 会转换为 .h 并编入 psplash 二进制，因此根文件系统中找不到原图。

推荐在自定义层定制 psplash，例如 ACME 板的目录结构:

meta-acme/recipes-core/psplash
├── files
│   └── logo-acme.png
└── psplash_%.bbappend

对应 psplash_%.bbappend 内容:

SPLASH_IMAGES = "file://logo-acme.png;outsuffix=default"
FILESEXTRAPATHS:prepend := "${THISDIR}/files:"

也可添加特定配置选项，例如:

EXTRA_OECONF += "--disable-startup-msg --enable-img-fullscreen"

追加文件详情见 “通过自己的层追加其他层元数据”。

SRC_URI 

初始说明见 BitBake 手册的 SRC_URI。

以下功能由 OpenEmbedded 和 Yocto Project 添加。

选项分为标准和配方特定两类。标准选项：

apply：是否应用补丁，默认应用。
striplevel：应用补丁时剥离路径的层级，默认 1。
patchdir：应用补丁的目录，默认 ${S}。

从版本控制系统构建源码的配方专用选项：

mindate：仅在 SRCDATE 大于等于 mindate 时应用。
maxdate：仅在 SRCDATE 不晚于 maxdate 时应用。
minrev：仅在 SRCREV 大于等于 minrev 时应用。
maxrev：仅在 SRCREV 不晚于 maxrev 时应用。
rev：仅在 SRCREV 等于 rev 时应用。
notrev：仅在 SRCREV 不等于 rev 时应用。

备注

若要获取追加文件中 SRC_URI 指定的文件，必须在追加文件通过 FILESEXTRAPATHS 扩展 FILESPATH。

SRC_URI_OVERRIDES_PACKAGE_ARCH 

构建系统默认自动检测 SRC_URI 是否包含机器特定文件，并相应改变 PACKAGE_ARCH。设为 "0" 可禁用。

SRCDATE 

构建软件包所用源码日期，仅适用于从源码管理系统（SCM）获取的源码。

SRCPV 

此变量已弃用。过去用于将源码控制信息加入 PV，使 bitbake 正常工作；现在不再需要。PV 中有 + 时，bitbake 会在打包时自动将源码控制信息加入 PKGV。

备注

过去 OpenEmbedded-Core (OE-Core) 在 meta/conf/bitbake.conf 中定义为:

SRCPV = "${@bb.fetch2.get_srcrev(d)}"

仍可使用 get_srcrev 手动将源码控制信息加入变量。

SRCREV 

构建软件包所用源码修订版本，仅适用于 Subversion、Git 和 Mercurial。若需固定版本并避免每次解析配方都查询远程，应指定完整修订标识（如 Git 完整 SHA），而不是标签。

备注

使用最新修订版本的限制见 AUTOREV 及开发任务手册的 “自动递增软件包版本号”。

SRCREV_FORMAT 

见 BitBake 手册的 SRCREV_FORMAT。

SRCTREECOVEREDTASKS 

使用 externalsrc 构建时通常不相关、因此跳过的任务列表。默认是外部源码很少需要的任务:

SRCTREECOVEREDTASKS ?= "do_patch do_unpack do_fetch"

一个明显例外是 kernel-yocto 定义的外部内核源码处理（为易读而调整格式）:

SRCTREECOVEREDTASKS += "\
  do_validate_branches \
  do_kernel_configcheck \
  do_kernel_checkout \
  do_fetch \
  do_unpack \
  do_patch \
"

另见 EXTERNALSRC 和 EXTERNALSRC_BUILD。

SSTATE_DIR 

共享状态缓存目录。

SSTATE_EXCLUDEDEPS_SYSROOT 

指定系统根目录应排除的间接依赖。例如，依赖某 native 配方可能引入其全部依赖，而其中的构建工具未必与当前配方有关。

忽略无关依赖，可避免它们妨碍共享状态缓存中预构建产物的复用。

按两个正则表达式求值，分别匹配配方和应忽略依赖。 meta/conf/layer.conf 的示例:

# Nothing needs to depend on libc-initial
# base-passwd/shadow-sysroot don't need their dependencies
SSTATE_EXCLUDEDEPS_SYSROOT += "\
    .*->.*-initial.* \
    .*(base-passwd|shadow-sysroot)->.* \
"

-> 表示两个正则表达式之间的依赖关系。

SSTATE_MIRROR_ALLOW_NETWORK 

为 "1" 时，即使 BB_NO_NETWORK 为 "1"，仍允许从 SSTATE_MIRRORS 获取。适用于镜像指向内部共享状态服务器，但需禁用其他网络获取的场景。

SSTATE_MIRRORS 

构建前先从其他镜像位置寻找预构建缓存对象，类似获取器的 MIRRORS 和 PREMIRRORS。

可指定文件系统目录或 HTTP、FTP 等 URL。位置需包含此前构建的 sstate-cache，也可来自其他机器的构建。

Yocto Project 提供 autobuilder 的缓存对象:

SSTATE_MIRRORS ?= "file://.* http://sstate.yoctoproject.org/all/PATH;downloadfilename=PATH"

这些产物面向各 Poky 版本支持的通用 QEMU 机器，对针对特定 CPU 系列优化的实际项目，复用可能性较低。

镜像搭建方法见设置共享状态缓存镜像站。

SSTATE_SCAN_FILES 

控制扫描硬编码安装路径的文件列表。空格分隔文件名（不是路径），允许标准通配符。

构建系统在准备系统根目录的第一阶段创建共享状态对象，并扫描原安装位置的硬编码路径。此变量控制扫描文件。通常配方向其追加需要扫描的文件，而不是完整重设。默认列表由 sstate 指定。

流程详情见 staging。

SSTATE_SIG_KEY 

SSTATE_VERIFY_SIG 为 "1" 时，对共享状态产物签名所用的 GPG 密钥标识。

详情见共享状态签名。

SSTATE_SIG_PASSPHRASE 

SSTATE_VERIFY_SIG 为 "1" 时，对共享状态产物签名的私钥保护口令。

详情见共享状态签名。

SSTATE_SKIP_CREATION 

跳过共享状态压缩包创建。例如，镜像归档并保留在共享状态中会占用大量磁盘，可能适合跳过。

通常不推荐，因为缺失产物会影响构建，尤其处于依赖链中间时。仅当保存产物的空间和时间成本与直接运行任务相近时才合理，通常限于镜像等最终产物。

对单个任务禁用:

SSTATE_SKIP_CREATION:task-image-complete = "1"

对整个配方禁用:

SSTATE_SKIP_CREATION = "1"

SSTATE_VALID_SIGS 

SSTATE_VERIFY_SIG 为 "1" 时，验证共享状态产物签名所用的 GPG 密钥标识列表，空格分隔。

必须包含密钥对的短标识。例如运行 gpg --list-keys 时，见下方粗体：

pub   ed25519 2026-04-17 [SC]
      4049A47E3AAA99D0250966DC5B97632FA7F4E942
uid           [ultimate] Antonin Godard (SState Signing) <antonin.godard@bootlin.com>
sub   cv25519 2026-04-17 [E]

短形式为标识符最后 16 字符，上例为 5B97632FA7F4E942。

备注

若为空（默认），OpenEmbedded Build System 可使用 Build Host 上任意 GPG 密钥验证共享状态产物。

详情见共享状态签名。

SSTATE_VERIFY_SIG 

控制共享状态产物签名功能是否启用。

详情见共享状态签名。

STABLE_VERSION_PARTS 

PV 中以点分隔的前几个部分构成稳定版本前缀，默认 "2"。 upstream-stable-release-point 用它生成 UPSTREAM_STABLE_RELEASE_REGEX。

例如 PV 为 259.5、此变量为 1 时，正则匹配以 259 开头的版本。

STAGING_BASE_LIBDIR_NATIVE 

构建主机系统根目录下 /lib 子目录的路径。

STAGING_BASELIBDIR 

当前配方运行目标的系统根目录 STAGING_DIR_HOST 下 /lib 的路径。

STAGING_BINDIR 

当前配方运行目标的系统根目录 STAGING_DIR_HOST 下 /usr/bin 的路径。

STAGING_BINDIR_CROSS 

包含二进制配置脚本的目录。这些脚本为需要使用对应软件提供的库或头文件的其他软件提供配置信息。

备注

此类配置方式基本由 pkg-config 取代。待链接库若支持 pkg-config，推荐使用它而不是配置脚本。

STAGING_BINDIR_NATIVE 

构建主机系统根目录下 /usr/bin 的路径。

STAGING_DATADIR 

当前配方运行目标的系统根目录 STAGING_DIR_HOST 下 /usr/share 的路径。

STAGING_DATADIR_NATIVE 

构建主机系统根目录下 /usr/share 的路径。

STAGING_DIR 

用于构造暂存阶段的目录树。

配方专属系统根目录的暂存过程见 do_populate_sysroot、 “在配方之间共享文件”、 “配置、编译和暂存” 以及 SYSROOT_DIRS。

备注

配方绝不能直接写入此目录，它由构建系统自动管理。应在 do_install 将文件安装到 ${D}，再由构建系统将其中一部分暂存到系统根目录。

STAGING_DIR_HOST 

配方输入系统根目录的路径，包含供组件运行所在系统使用的文件。多数配方通过 do_populate_sysroot 填充，以在配方间共享文件； native 配方例外，它们的文件复制到 STAGING_DIR_NATIVE。根据配方类型与构建目标，可取：

为目标机器构建时为 ${RECIPE_SYSROOT}，见 RECIPE_SYSROOT。
为 build host 构建的 native 配方，值为空，因为假定使用构建主机自己的目录。

备注

native 文件并不安装到主机 /usr 等路径，而是 STAGING_DIR_NATIVE。编译时设置 CPPFLAGS、CFLAGS 等环境变量，通过 GCC -isystem 等选项同时搜索主机和系统根目录的库与头文件。

STAGING_DIR* 应被 do_configure、do_compile 和 do_install 视为输入变量。 native 使用主机头文件和库，因此真实主机根目录承担 STAGING_DIR_HOST 的角色是合理的。

STAGING_DIR_NATIVE 

配方输入系统根目录的路径，填充 native 配方提供的文件，即在 build host 自身运行的组件。

默认 ${RECIPE_SYSROOT_NATIVE}，见 RECIPE_SYSROOT_NATIVE。

STAGING_DIR_TARGET 

指向组件生成代码所针对系统的系统根目录。多数不生成代码的组件，此值与 STAGING_DIR_HOST 相同。

某些配方构建的程序运行于一个系统，却为另一个系统生成代码，例如 cross-canadian。 GNU 术语中，程序运行的系统称 HOST，生成代码针对的系统称 TARGET。 STAGING_DIR_HOST 指向 HOST 根目录，此变量指向 TARGET 根目录。

STAGING_ETCDIR_NATIVE 

构建主机系统根目录下 /etc 的路径。

STAGING_EXECPREFIXDIR 

当前配方运行目标的系统根目录 STAGING_DIR_HOST 下 /usr 的路径。

STAGING_INCDIR 

当前配方运行目标的系统根目录 STAGING_DIR_HOST 下 /usr/include 的路径。

STAGING_INCDIR_NATIVE 

构建主机系统根目录下 /usr/include 的路径。

STAGING_KERNEL_BUILDDIR 

内核构建产物目录。systemtap-uprobes 等需要这些产物的软件配方，可在内核构建后到此目录查找。

STAGING_KERNEL_DIR 

包含构建树外模块所需内核头文件的目录。

STAGING_LIBDIR 

当前配方运行目标的系统根目录 STAGING_DIR_HOST 下 /usr/lib 的路径。

STAGING_LIBDIR_NATIVE 

构建主机系统根目录下 /usr/lib 的路径。

STAMP 

创建配方戳记文件的基础路径。求值后附加其他信息，得到实际戳记路径。 meta/conf/bitbake.conf 当前默认赋值:

STAMP = "${STAMPS_DIR}/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}"

BitBake 如何用戳记决定是否重跑任务，见 “戳记文件与任务重跑”。

相关变量见 STAMPS_DIR、MULTIMACH_TARGET_SYS、PN、 EXTENDPE、PV、PR。

STAMPCLEAN 

见 BitBake 手册的 STAMPCLEAN。

STAMPS_DIR 

构建系统保存戳记的基础目录，默认 ${TMPDIR}/stamps。

STRIP 

运行剥离符号工具 strip 的最小命令和参数。

SUMMARY 

供 opkg、rpm、dpkg 等打包系统使用的简短包摘要，不超过 72 字符。配方未设置 DESCRIPTION 时，默认用此值定义。

配方未设置此变量时会警告，并使用 meta/conf/bitbake.conf 的默认值。

SVNDIR 

存储 Subversion 检出文件的目录。

SYSLINUX_DEFAULT_CONSOLE 

指定内核默认启动控制台。使用其他控制台时按下例设置，X 为控制台编号:

SYSLINUX_DEFAULT_CONSOLE = "console=ttyX"

syslinux 起初设为 null，之后检查其值。

SYSLINUX_OPTS 

加入 syslinux 文件的额外选项，在配方中设置，多个选项用分号分隔。

syslinux 用它创建选项集合。

SYSLINUX_SERIAL 

指定备用串口或禁用它。在配方中设为空可禁用， syslinux 默认定义:

SYSLINUX_SERIAL ?= "0 115200"

该类按需检查并使用。

SYSLINUX_SERIAL_TTY 

指定备用 console=tty... 内核启动参数，syslinux 默认定义:

SYSLINUX_SERIAL_TTY ?= "console=ttyS0,115200"

该类按需检查并使用。

SYSLINUX_SPLASH 

VGA 启动菜单背景的 .LSS 文件，需在配方中设置。

syslinux 检查此变量，存在时安装启动画面。

SYSROOT_DESTDIR 

工作目录下的临时目录，默认 ${WORKDIR}/sysroot-destdir， do_populate_sysroot 在此组装待填充系统根目录的文件。

SYSROOT_DIRS 

do_populate_sysroot 暂存到系统根目录的目录，默认如下:

SYSROOT_DIRS = " \
    ${includedir} \
    ${libdir} \
    ${base_libdir} \
    ${nonarch_base_libdir} \
    ${datadir} \
    /sysroot-only \
    "

假设配方 A 将 .so.* 共享库安装到非 ${libdir} 或 ${base_libdir} 的自定义目录，例如 /opt/lib。

备注

不推荐这样处理共享库，此处仅用于说明该变量的用途。

配方 B DEPENDS 于 A 时，SYSROOT_DIRS 内容会从 A 的 D 复制到 B 的 SYSROOT_DESTDIR，即 ${WORKDIR}/sysroot-destdir。

/opt/lib 不在列表中，就不会复制到 A 的 RECIPE_SYSROOT （${WORKDIR}/recipe-sysroot），因此链接失败。

应将 /opt/lib 加入:

SYSROOT_DIRS:append = " /opt/lib"

备注

即使加入，链接器仍不知道该位置，因为目标配方的 TARGET_LDFLAGS 未包含它。因此还应添加:

TARGET_LDFLAGS:append = " -L${RECIPE_SYSROOT}/opt/lib"

SYSROOT_DIRS_IGNORE 

do_populate_sysroot 不暂存的目录，可排除 SYSROOT_DIRS 内某些子目录。默认排除:

SYSROOT_DIRS_IGNORE = " \
    ${mandir} \
    ${docdir} \
    ${infodir} \
    ${datadir}/X11/locale \
    ${datadir}/applications \
    ${datadir}/bash-completion \
    ${datadir}/fonts \
    ${datadir}/gtk-doc/html \
    ${datadir}/installed-tests \
    ${datadir}/locale \
    ${datadir}/pixmaps \
    ${datadir}/terminfo \
    ${libdir}/${BPN}/ptest \
    "

SYSROOT_DIRS_NATIVE 

native 配方除 SYSROOT_DIRS 外，由 do_populate_sysroot 额外暂存的目录。默认如下:

SYSROOT_DIRS_NATIVE = " \
    ${bindir} \
    ${sbindir} \
    ${base_bindir} \
    ${base_sbindir} \
    ${libexecdir} \
    ${sysconfdir} \
    ${localstatedir} \
    "

备注

native 程序直接从 STAGING_DIR_NATIVE 运行，因而需要暂存更多包含可执行文件和支持文件的目录。

SYSROOT_PREPROCESS_FUNCS 

文件暂存到系统根目录后执行的函数，通常用于额外处理已暂存文件，或暂存更多文件。

SYSTEMD_AUTO_ENABLE 

继承 systemd 时，指定 SYSTEMD_SERVICE 中服务是否自动启动。默认开机自动启动，类中定义为:

SYSTEMD_AUTO_ENABLE ??= "enable"

设为 disable 可禁用。

SYSTEMD_BOOT_CFG 

EFI_PROVIDER 为 systemd-boot 时，指定所用配置文件。 systemd-boot 默认设置:

SYSTEMD_BOOT_CFG ?= "${S}/loader.conf"

详情见 Systemd-boot 文档。

SYSTEMD_BOOT_ENTRIES 

EFI_PROVIDER 为 systemd-boot 时，指定待安装的 *.conf 条目文件，每个文件包含一个启动项。systemd-boot 默认设置:

SYSTEMD_BOOT_ENTRIES ?= ""

详情见 Systemd-boot 文档。

SYSTEMD_BOOT_TIMEOUT 

EFI_PROVIDER 为 systemd-boot 时，指定启动菜单超时秒数。 systemd-boot 默认设置:

SYSTEMD_BOOT_TIMEOUT ?= "10"

详情见 Systemd-boot 文档。

SYSTEMD_DEFAULT_TARGET 

设置 systemd 启动时默认单元，通常为 multi-user.target 或 graphical.target，通过创建 default.target 符号链接到所选目标文件实现。

详情见 systemd 文档。

core-image-minimal-xfce.bb 使用示例:

SYSTEMD_DEFAULT_TARGET = "graphical.target"

SYSTEMD_PACKAGES 

继承 systemd 时，指定主包之外包含 systemd 单元的包。默认假定单元位于主包:

SYSTEMD_PACKAGES ?= "${PN}"

若不在主包中，需列出实际包含单元文件的包。

SYSTEMD_SERVICE 

继承 systemd 时，指定软件包的 systemd 服务名，多个服务以空格分隔。

必须用包名覆盖表明适用的包，例如 connman:

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

可用覆盖直接对应 SYSTEMD_PACKAGES，未包含在该变量的覆盖会被静默忽略。

SYSVINIT_ENABLED_GETTYS 

使用 SysVinit 且 USE_VT 不为 "0" 时，指定运行 getty 以允许登录的虚拟终端，空格分隔。

默认 "1"，即仅在第一个虚拟终端运行 getty。

T 

BitBake 构建特定配方时放置临时文件的目录，主要为任务日志和脚本，通常设置:

T = "${WORKDIR}/temp"

WORKDIR 是 BitBake 解包和构建配方的目录，默认 bitbake.conf 设置此变量。

不要与 TMPDIR 混淆，后者指向整个构建输出目录树的根。

TARGET_ARCH 

目标机器架构。构建系统支持多种架构，如下例；架构可配置，此列表并不完整：

arm
i586
x86_64
powerpc
powerpc64
mips
mipsel

另见 TUNE_ARCH。

TARGET_AS_ARCH 

目标架构专用汇编器标志，meta/conf/bitbake.conf 默认根据 TUNE_ASARGS 初始化:

TARGET_AS_ARCH = "${TUNE_ASARGS}"

TARGET_CC_ARCH 

目标架构专用 C 编译器标志，默认根据 TUNE_CCARGS 初始化。

备注

目标软件若不遵循导出的 LDFLAGS，常见变通方法是将 LDFLAGS 追加到此变量。

TARGET_CC_KERNEL_ARCH 

针对 CPU 或 ABI 调优的内核专用编译标志，很少使用，仅用于用户空间 TUNE_CCARGS 不兼容内核编译的情况，使内核及相关模块采用不同配置。示例见 OpenEmbedded-Core (OE-Core) 的 meta/conf/machine/include/arm/feature-arm-thumb.inc。

TARGET_CFLAGS 

为目标构建时传给 C 编译器的标志。目标上下文默认将 CFLAGS 设为此值。

SDK 环境设置脚本也将 CFLAGS 设为此值，使 SDK 构建的程序应用相同标志。

TARGET_CPPFLAGS 

为目标构建时传给 C 预处理器（即 C 和 C++ 编译器）的标志。目标上下文默认将 CPPFLAGS 设为此值。

SDK 环境设置脚本也将 CPPFLAGS 设为此值，使 SDK 构建的程序应用相同标志。

TARGET_CXXFLAGS 

为目标构建时传给 C++ 编译器的标志，目标上下文默认将 CXXFLAGS 设为此值。

SDK 环境脚本也设置相同值，使 SDK 构建的程序应用这些标志。

TARGET_DBGSRC_DIR 

目标调试源码路径，默认 /usr/src/debug/${PN}/${PV}。

TARGET_FPU 

指定浮点代码处理方式。无 FPU 的目标（包括多数 ARM CPU）必须设为 soft，否则会使用内核仿真，造成性能损失。

TARGET_LD_ARCH 

目标架构专用链接标志，meta/conf/bitbake.conf 默认由 TUNE_LDARGS 初始化:

TARGET_LD_ARCH = "${TUNE_LDARGS}"

TARGET_LDFLAGS 

为目标构建时传给链接器的标志。目标上下文默认将 LDFLAGS 设为此值。

SDK 环境脚本也设置相同值，使 SDK 构建的程序应用这些标志。

TARGET_OS 

目标操作系统。glibc 系统可设 linux，musl 为 linux-musl； ARM/EABI 目标可为 linux-gnueabi 或 linux-musleabi。

TARGET_PREFIX 

工具链目标工具的二进制前缀。

根据配方和构建目标设置：

目标机器配方："${TARGET_SYS}-"。
native 配方：BUILD_PREFIX。
nativesdk 配方：SDK_PREFIX。

TARGET_SYS 

当前配方构建所针对的系统，包括架构和操作系统。

根据 TARGET_ARCH、TARGET_VENDOR、TARGET_OS 自动设置。

备注

无需自行设置。

例如：

32 位 x86 Linux 主机上的 native 配方：i686-linux。
面向小端 MIPS Linux 目标的配方：可能为 mipsel-linux。

TARGET_VENDOR 

目标供应商名称。

TC_CXX_RUNTIME 

构建时使用的 C/C++ STL 与运行时变体，默认 gnu。

可选 gnu、llvm、android。

TCLIBC 

构建时使用的 GNU 标准 C 库变体。

可选 glibc、musl、newlib、baremetal。

TCMODE 

工具链选择器，通过选择配置控制生成包与镜像的特性。构建系统默认构建自己的内部工具链，值 default 即使用它。

备注

使用其他值时，必须自行确保与默认工具链兼容。组件版本过新或过旧都可能导致问题。具体组件要求见相应版本的发布信息。

类似控制 glibc/musl 选择的 TCLIBC。

添加层可使用预编译外部工具链，例如 Sourcery G++，支持位于 Mentor Graphics 的 meta-sourcery： https://github.com/MentorEmbedded/meta-sourcery/。

层 README 说明用法。需将层加入 build/conf/bblayers.conf，并在 build/conf/local.conf 将 EXTERNAL_TOOLCHAIN 指向工具链位置。

这些原理适用于任何外部工具链，可用 meta-sourcery 作为模板。

除配置外还需要工具链配方，将 libgcc、libstdcc++、区域数据、libc 等预构建对象打包。

TEMPLATECONF 

指定用于生成 build/conf/bblayers.conf 和 build/conf/local.conf 的模板目录。可定制这些文件及加载 oe-init-build-env 时显示的默认 BitBake 目标。

详情见创建自定义模板配置目录。

备注

必须在外部环境设置才有效。

TEST_EXPORT_DIR 

TEST_EXPORT_ONLY 为 "1" 时的测试导出位置，默认 ${TMPDIR}/testimage/${PN}。

TEST_EXPORT_ONLY 

设为 "1" 时仅导出测试，不执行，以便在构建系统外运行。

TEST_LOG_DIR 

保存 QEMU 的 SSH 与启动日志，默认 ${WORKDIR}/testimage。

备注

实际测试结果在 ${WORKDIR}/temp/ 的 log.do_testimage 任务日志中。

TEST_POWERCONTROL_CMD 

自动硬件测试的目标电源控制命令，通常指向操作网络电源插座等设备的脚本。最后一个参数应接受 off、on、cycle，分别表示断电、上电、先断再上。

TEST_POWERCONTROL_EXTRA_ARGS 

自动硬件测试时传给 TEST_POWERCONTROL_CMD 的可选额外参数，例如用于分离机器专属与通用参数。

TEST_QEMUBOOT_TIMEOUT 

自动运行时测试开始前，允许镜像启动到登录提示的秒数，默认 500。可在 configuration file 修改。

详情见“执行自动化运行时测试”。

TEST_SERIALCONTROL_CMD 

自动硬件测试时连接目标串口控制台的命令。只需像普通终端程序一样连接串口并转发标准输入输出。

例如以 115200bps 使用 Picocom 连接 /dev/ttyUSB0:

TEST_SERIALCONTROL_CMD = "picocom /dev/ttyUSB0 -b 115200"

TEST_SERIALCONTROL_CONNECT_TIMEOUT 

用 testexport 自动硬件测试时，首次连接目标的超时秒数。

TEST_SERIALCONTROL_EXTRA_ARGS 

自动硬件测试时传给 TEST_SERIALCONTROL_CMD 的可选额外参数，例如分离机器专属与通用部分。

TEST_SERIALCONTROL_PS1 

用 testexport 自动硬件测试时，匹配目标终端空提示符的正则，例如 root@target:.*#。

TEST_SERVER_IP 

构建主机 IP，通常自动检测；检测失败时需显式设为执行构建的机器地址。

备注

仅少数测试使用，例如 dnf 套件从 WORKDIR/oe-rootfs-repo 下载包时。

TEST_SUITES 

自动运行时测试所运行的测试模块，有序列表。

构建系统提供一组核心镜像测试。

备注

当前仅支持在 QEMU 下运行这些测试。

包括 ping、ssh、df 等。可追加自定义测试:

TEST_SUITES:append = " mytest"

也可使用 auto 运行全部适用测试:

TEST_SUITES:append = " auto"

系统自动选择适用于镜像的测试，跳过其余项。

顺序很重要，依赖其他测试的项必须排在其后。例如 test_B 依赖 test_A 时:

TEST_SUITES = "test_A test_B"

详情见“执行自动化运行时测试”。

TEST_TARGET 

对镜像运行测试所用的目标控制器，默认 qemu:

TEST_TARGET = "qemu"

控制器定义如何部署镜像和启动目标。层可在 /lib/oeqa/controllers 添加模块，继承抽象 BaseTarget 类扩展控制器；BaseTarget 本身不能作为此变量值。

可用值：

qemu：启动 QEMU 镜像并测试，见 “在 QEMU 上启用运行时测试”。
simpleremote：在已启动运行的硬件上测试，可以是联网硬件或 QEMU 设备。还必须设置 TEST_TARGET_IP。

备注

定义于 meta/lib/oeqa/controllers/simpleremote.py。

硬件测试详情见 “在硬件上启用运行时测试”。

TEST_TARGET_IP 

被测硬件 IP。TEST_TARGET 为 qemu 时无效。

可同时指定端口，例如:

TEST_TARGET_IP = "192.168.1.4:2201"

适用于非标准 SSH 端口，或设备位于主机无法直达的防火墙／网络后，需要端口地址转换的情况。

TESTIMAGE_AUTO 

镜像成功构建后自动运行测试。设为 "1" 会自动在 QEMU 启动成功构建的镜像，并添加依赖，使被要求测试的 SDK 也先自动构建。

测试使用 Python unittest，多数通过 SSH 在目标执行命令。在 configuration file 中可设置：

TESTIMAGE_AUTO = "1"

启用、运行与编写方法见 “执行自动化运行时测试” 和“testimage”。

TESTIMAGE_FAILED_QA_ARTIFACTS 

使用 testimage 时，列出应从目标获取到主机的路径，空格分隔。

TESTSDK_SUITES 

使用 testsdk 时控制测试模块列表。默认空字符串，运行所有找到的模块。

THISDIR 

BitBake 当前解析文件所在目录，不要手动设置。

TIME 

构建开始时间，时分秒 HMS 格式，例如 140159 表示 14:01:59。

TMPDIR 

构建系统全部输出和中间文件的基础目录，不含共享状态缓存。默认 Build Directory 中的 tmp。

可在 build/conf/site.conf 指定其他位置:

TMPDIR = "/another/location"

例如构建目录使用 NFS，而 TMPDIR 放在非 NFS 的本地磁盘。

文件系统必须具备标准语义：大小写文件名唯一、POSIX 文件锁、持久 inode。 NFS 存在多种问题及实现错误，不满足要求，因此 TMPDIR 不能位于 NFS。

TOOLCHAIN 

覆盖配方使用的工具链，默认 PREFERRED_TOOLCHAIN，可用值也见该变量。

配方已知仅支持特定工具链时可覆盖，例如 Pseudo 设为 gcc，因为使用了 Clang/LLVM 不提供的 GCC 内建选项。

TOOLCHAIN_HOST_TASK 

SDK 交叉开发环境中在 SDKMACHINE 运行的工具链软件包列表，通常都应带 nativesdk- 前缀。例如构建 SDK 时:

$ bitbake -c populate_sdk imagename

变量已有默认列表，也可追加包，见 “向标准 SDK 添加单个软件包”。

交叉工具链背景见“交叉开发工具链”，环境设置见 Yocto 项目应用开发与软件开发套件（SDK/eSDK）手册。

此变量用于 SDK，不用于 eSDK；后者应使用 TOOLCHAIN_HOST_TASK_ESDK。

TOOLCHAIN_HOST_TASK_ESDK 

扩展 eSDK 主机部分安装的内容，类似标准 SDK 的 TOOLCHAIN_HOST_TASK。

TOOLCHAIN_NATIVE 

覆盖 native 配方的工具链，默认该上下文的 PREFERRED_TOOLCHAIN，可用值见该变量。

配方仅支持特定工具链时可自行覆盖。

TOOLCHAIN_OPTIONS 

非 native 配方传给编译器和链接器的额外选项，使其指向 RECIPE_SYSROOT 的自定义系统根目录:

TOOLCHAIN_OPTIONS = " --sysroot=${RECIPE_SYSROOT}"

native 用本机编译器为主机构建，无需设置。

TOOLCHAIN_OUTPUTNAME 

工具链输出名称，由 populate_sdk_base 设置:

TOOLCHAIN_OUTPUTNAME ?= "${SDK_NAME}-toolchain-${SDK_VERSION}"

另见 SDK_NAME 和 SDK_VERSION。

TOOLCHAIN_TARGET_TASK 

SDK 目标部分的软件包列表，包含为目标硬件构建的库与头文件。可用它逐个添加包，详情见 “向标准 SDK 添加单个软件包”。

交叉工具链背景见“交叉开发工具链”，环境设置见 Yocto 项目应用开发与软件开发套件（SDK/eSDK）手册。

TOPDIR 

见 BitBake 手册的 TOPDIR。

TRANSLATED_TARGET_ARCH 

规范化的 TARGET_ARCH，用于不允许下划线的场合，如包文件名，将下划线替换为连字符。

不要编辑此变量。

TUNE_ARCH 

特定架构的 GNU 规范名称，如 arm、armeb、mips、mips64。 BitBake 用于设置配置。

定义依架构而异，可以静态或动态。CPU 系列详情见对应架构 README，例如 OpenEmbedded-Core (OE-Core) 的 meta/conf/machine/include/mips/README。

与定义目标机器架构的 TARGET_ARCH 紧密关联， meta/conf/bitbake.conf 按如下方式设置后者:

TARGET_ARCH = "${TUNE_ARCH}"

支持的机器架构示例如下，架构可配置，因此并非完整列表：

arm
i586
x86_64
powerpc
powerpc64
mips
mipsel

TUNE_ASARGS 

目标架构专用汇编器标志，基于所选调优功能。通常由 meta/conf/machine/include/ 下的调优文件设置，受 TUNE_FEATURES 影响。例如 x86 的 meta/conf/machine/include/x86/arch-x86.inc:

TUNE_ASARGS += "${@bb.utils.contains("TUNE_FEATURES", "mx32", "-x32", "", d)}"

备注

BSP 选择调优，所选调优又会影响调优变量本身。即调优可提供自己的一组标志。

TUNE_CCARGS 

目标架构专用 C 编译器标志，基于所选调优功能。通常由 meta/conf/machine/include/ 下的调优包含文件设置，受 TUNE_FEATURES 影响。

备注

BSP 选择调优，调优影响变量本身，也可提供自己的一组标志。

TUNE_FEATURES 

针对特定处理器优化编译器的功能，定义于调优文件，根据这些功能动态生成 TUNE_*ARGS 参数。

构建系统验证功能受支持且彼此不冲突。

meta/conf/bitbake.conf 定义如下:

TUNE_FEATURES ??= "${TUNE_FEATURES:tune-${DEFAULTTUNE}}"

另见 DEFAULTTUNE。

TUNE_LDARGS 

目标架构专用链接器标志，基于所选调优功能。通常由 meta/conf/machine/include/ 下的包含文件设置，受 TUNE_FEATURES 影响。例如 x86 的 meta/conf/machine/include/x86/arch-x86.inc:

TUNE_LDARGS += "${@bb.utils.contains("TUNE_FEATURES", "mx32", "-m elf32_x86_64", "", d)}"

备注

BSP 选择调优，调优影响变量本身，也可提供自己的一组标志。

TUNE_PKGARCH 

包管理系统用于表示输出包架构、ABI 和调优的包架构名称。使用 _tune 覆盖定义:

TUNE_PKGARCH:tune-tune = "tune"

这些调优专属架构定义在机器包含文件中，例如 tune-core2.inc 的 core2-32:

TUNE_PKGARCH:tune-core2-32 = "core2-32"

TUNECONFLICTS 

指定与某功能冲突的 CPU 或 ABI 调优功能。

已知冲突定义于 OpenEmbedded-Core (OE-Core) 的机器包含文件。例如 meta/conf/machine/include/mips/arch-mips.inc 将 o32、n64 列为与 n32 冲突:

TUNECONFLICTS[n32] = "o32 n64"

TUNEVALID 

指定有效的 CPU 或 ABI 调优功能，作为标志保存。有效功能定义于机器包含文件，例如 meta/conf/machine/include/arm/arch-arm.inc:

TUNEVALID[bigendian] = "Enable big-endian mode."

具体功能见 OpenEmbedded-Core (OE-Core) 的机器包含文件。

UBOOT_BINARY 

U-Boot 构建的二进制文件名。

UBOOT_CONFIG 

配置要构建的一个或多个 U-Boot 配置，每个必须定义 UBOOT_MACHINE。其他控制变量为 UBOOT_CONFIG_BINARY、UBOOT_CONFIG_FRAGMENTS、 UBOOT_CONFIG_IMAGE_FSTYPES、UBOOT_CONFIG_MAKE_OPTS。

以下为 meta-freescale 更新后的示例:

UBOOT_CONFIG ??= "sdcard-ifc-secure-boot sdcard-ifc sdcard-qspi lpuart qspi secure-boot nor"

UBOOT_CONFIG[nor] = "ls1021atwr_nor_defconfig"
UBOOT_CONFIG[sdcard-ifc] = "ls1021atwr_sdcard_ifc_defconfig"
UBOOT_CONFIG[sdcard-qspi] = "ls1021atwr_sdcard_qspi_defconfig"
UBOOT_CONFIG[lpuart] = "ls1021atwr_nor_lpuart_defconfig"
UBOOT_CONFIG[qspi] = "ls1021atwr_qspi_defconfig"
UBOOT_CONFIG[secure-boot] = "ls1021atwr_nor_SECURE_BOOT_defconfig"
UBOOT_CONFIG[sdcard-ifc-secure-boot] = "ls1021atwr_sdcard_ifc_SECURE_BOOT_defconfig"

UBOOT_CONFIG_BINARY[sdcard-ifc] = "u-boot-with-spl-pbl.bin"
UBOOT_CONFIG_BINARY[sdcard-qspi] = "u-boot-with-spl-pbl.bin"
UBOOT_CONFIG_BINARY[sdcard-ifc-secure-boot] = "u-boot-with-spl-pbl.bin"

此例选择全部七个配置，每个以 ..._defconfig 指定 UBOOT_MACHINE， sd... 配置为 UBOOT_CONFIG_BINARY 分别定义名称。

处理细节见 uboot-config。

UBOOT_CONFIG_BINARY 

不能直接赋值，作为通过标志配置 UBOOT_CONFIG 流程的占位变量:

UBOOT_CONFIG_BINARY[foo] = "binary1"
UBOOT_CONFIG_BINARY[bar] = "binary2"

指定部署到 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。

UBOOT_CONFIG_FRAGMENTS 

不能直接赋值，作为通过标志配置 UBOOT_CONFIG 流程的占位变量:

UBOOT_CONFIG_FRAGMENTS[foo] = "frag1 frag2"
UBOOT_CONFIG_FRAGMENTS[bar] = "frag3"

指定源码树配置片段，在 do_configure() 与 UBOOT_CONFIG 的 defconfig 合并。片段和 defconfig 同位于 ${S}/configs/。

此选项可选，仅对需要的配置设置。

详情见 uboot-config。

UBOOT_CONFIG_IMAGE_FSTYPES 

不能直接赋值，作为通过标志配置 UBOOT_CONFIG 流程的占位变量:

UBOOT_CONFIG_IMAGE_FSTYPES[foo] = "fstype1"
UBOOT_CONFIG_IMAGE_FSTYPES[bar] = "fstype2"

为当前配置向 IMAGE_FSTYPES 追加镜像类型，可构建使用当前配置所生成二进制的额外镜像格式。

可选，仅对需要的配置设置标志。

详情见 uboot-config。

UBOOT_CONFIG_MAKE_OPTS 

不能直接赋值，作为通过标志配置 UBOOT_CONFIG 流程的占位变量:

UBOOT_CONFIG_MAKE_OPTS[foo] = "OPT1=foo OPT2=2"
UBOOT_CONFIG_MAKE_OPTS[bar] = "OPT1=bar"

指定 do_compile() 传给 make 的命令行选项。

可选，仅对需要的配置设置标志。

详情见 uboot-config。

UBOOT_DTB_LOADADDRESS 

U-Boot 所用 dtb 镜像加载地址。 kernel-fit-image 创建 FIT 的 ITS dtb 区段时使用。

UBOOT_DTBO_LOADADDRESS 

U-Boot 所用 dtbo 镜像加载地址。 kernel-fit-image 创建 FIT 的 ITS dtbo 区段时使用。

UBOOT_ENTRYPOINT 

U-Boot 镜像入口点，创建时作为命令行参数传给 uboot-mkimage。

指定 64 位地址时，需要设置：

FIT 镜像的 FIT_ADDRESS_CELLS。
U-Boot FIT 镜像的 UBOOT_FIT_ADDRESS_CELLS。

由 kernel-fit-image、kernel-uimage、 kernel、uboot-config 和 uboot-sign 使用。

UBOOT_ENV 

添加随 U-Boot 安装的环境变量或脚本，通常为 uEnv.txt 或 boot.cmd，安装到 /boot 并复制到 DEPLOYDIR。

需要这些文件的机器，应在 bbappend 中将其加入 U-Boot 的 SRC_URI。

UBOOT_ENV_SUFFIX 为 scr 时通过 mkimage -T script 打包为 uImage，否则原样安装。

例如：

将 boot.cmd 作为 uImage 加入 /boot:

UBOOT_ENV = "boot"
UBOOT_ENV_SUFFIX = "scr"
SRC_URI += "file://${UBOOT_ENV_SRC}"

将 uEnv.txt 作为纯文本加入 /boot:

UBOOT_ENV = "uEnv"
UBOOT_ENV_SUFFIX = "txt"
SRC_URI += "file://${UBOOT_ENV_BINARY}"

UBOOT_ENV_SRC_SUFFIX 

UBOOT_ENV_SUFFIX 为 scr 时，指定 SRC_URI 中纯文本脚本的后缀，默认 cmd。

UBOOT_ENV_SUFFIX 

为 scr 时，UBOOT_ENV 脚本安装前打包为 uImage。默认 txt，即原样安装。

UBOOT_EXTLINUX 

U-Boot 配方继承 uboot-extlinux-config 后还需将此变量设为 "1"，才能启用功能，仅继承不足以启用。

UBOOT_EXTLINUX_CONF_NAME 

继承 uboot-extlinux-config 时，控制启动配置文件名，默认 extlinux.conf。

UBOOT_EXTLINUX_CONSOLE 

继承 uboot-extlinux-config 时，控制内核命令行的 console=，例如:

UBOOT_EXTLINUX_CONSOLE = "console=ttyS0,115200n8"

加入启动 extlinux.conf 的 APPEND 属性。

UBOOT_EXTLINUX_DEFAULT_LABEL 

继承 uboot-extlinux-config 时，指定 UBOOT_EXTLINUX_TIMEOUT 超时后自动启动的标签名。

UBOOT_EXTLINUX_FDT 

继承 uboot-extlinux-config 时，控制 extlinux.conf 的 FDT 属性，选择 Linux 内核设备树，例如:

UBOOT_EXTLINUX_FDT = "../am335x-bone.dtb"

备注

路径相对启动所用的 extlinux.conf，也可以是其所在分区中的绝对路径。

UBOOT_EXTLINUX_FDTDIR 

继承 uboot-extlinux-config 时，控制 extlinux.conf 的 FDTDIR，指定 U-Boot 环境变量 fdtfile 所命名设备树所在目录，例如:

UBOOT_EXTLINUX_FDTDIR = "../"

备注

路径相对启动所用的 extlinux.conf，也可以是其所在分区中的绝对路径。

UBOOT_EXTLINUX_FDTOVERLAYS 

继承 uboot-extlinux-config 时，UBOOT_EXTLINUX_FDT 可控制 extlinux.conf 的 FDTOVERLAYS，指定应用于设备树之上的覆盖，例如:

UBOOT_EXTLINUX_FDTOVERLAYS = "../am335x-bone-wifi.dtbo"

备注

路径相对启动所用的 extlinux.conf，也可以是其所在分区中的绝对路径。

UBOOT_EXTLINUX_INITRD 

继承 uboot-extlinux-config 时的可选变量。 initramfs 位于内核外部时（见 INITRAMFS_IMAGE_BUNDLE），设置 extlinux.conf 的 INITRD，例如:

UBOOT_EXTLINUX_INITRD = "../ramdisk.tar.zst"

备注

路径相对启动所用的 extlinux.conf，也可以是其所在分区中的绝对路径。

UBOOT_EXTLINUX_INSTALL_DIR 

继承 uboot-extlinux-config 时，指定启动 extlinux.conf 的安装目录，相对其所属分区根目录。

UBOOT_EXTLINUX_KERNEL_ARGS 

继承 uboot-extlinux-config 时，向内核命令行添加参数，例如:

UBOOT_EXTLINUX_KERNEL_ARGS = "rootwait ro"

加入 extlinux.conf 的 APPEND 属性。

UBOOT_EXTLINUX_KERNEL_IMAGE 

继承 uboot-extlinux-config 时，指定 extlinux.conf 的 KERNEL 属性，选择 Linux 内核镜像，例如:

UBOOT_EXTLINUX_KERNEL_IMAGE = "../zImage"

备注

路径相对启动所用的 extlinux.conf，也可以是其所在分区中的绝对路径。

小技巧

KERNEL_IMAGETYPE 可获取相应配方当前构建的内核名称。

UBOOT_EXTLINUX_LABELS 

继承 uboot-extlinux-config 时，列出可启动的标签，对应 extlinux.conf 的 LABEL。至少一项，默认 linux。

多标签时，各 UBOOT_EXTLINUX_ 变量应使用覆盖样式赋值。例如标签列表为:

UBOOT_EXTLINUX_LABELS = "compressed uncompressed"

则 UBOOT_EXTLINUX_KERNEL_IMAGE 可设置多次:

UBOOT_EXTLINUX_KERNEL_IMAGE:compressed = "../zImage"
UBOOT_EXTLINUX_KERNEL_IMAGE:uncompressed = "../Image"

每个标签的 KERNEL 属性因而不同。

当前标签无覆盖赋值时使用默认值。例如以下赋值，仅在 UBOOT_EXTLINUX_FDT:compressed 和 UBOOT_EXTLINUX_FDT:uncompressed 都未设置时，同时应用于 compressed 和 uncompressed:

UBOOT_EXTLINUX_FDT = "../am335x-bone-wifi.dtbo"

UBOOT_EXTLINUX_MENU_DESCRIPTION 

继承 uboot-extlinux-config 时，设置 extlinux.conf 的 LABEL 属性。未指定则用标签名作为描述。

UBOOT_EXTLINUX_MENU_TITLE 

继承 uboot-extlinux-config 时，设置 extlinux.conf 的 MENU TITLE。作用于整个文件，不支持 UBOOT_EXTLINUX_LABELS 所述的覆盖语法。

UBOOT_EXTLINUX_ROOT 

继承 uboot-extlinux-config 时的必需变量，包含内核命令行的 root=。例如使用 MMC 块设备 0 的第二分区作为根分区:

UBOOT_EXTLINUX_ROOT = "root=/dev/mmcblk0p2"

UBOOT_EXTLINUX_TIMEOUT 

继承 uboot-extlinux-config 时的可选变量，设置 extlinux.conf 的 TIMEOUT。

UBOOT_FIT_ADDRESS_CELLS 

指定 U-Boot FIT 描述的 #address-cells。

uboot-sign 默认设为 "1"，表示 32 位地址。

UBOOT_LOADADDRESS、UBOOT_ENTRYPOINT 需 64 位地址时，设为 "2"，使用两个 32 位 cell 表示。

加载地址 0x400000000 的示例:

UBOOT_FIT_ADDRESS_CELLS = "2"
UBOOT_LOADADDRESS = "0x04 0x00000000"

见 #address-cells 详情。

UBOOT_FIT_ARM_TRUSTED_FIRMWARE 

Trusted Firmware-A（TF-A）是 Arm A-Profile（Armv8-A、Armv7-A）安全世界软件的参考实现，含 EL3 安全监视器。此变量启用包含 TF-A 二进制的 U-Boot FIT 生成。

默认 "0"，设为 "1" 启用:

UBOOT_FIT_ARM_TRUSTED_FIRMWARE = "1"

UBOOT_FIT_ARM_TRUSTED_FIRMWARE_IMAGE 

TF-A 二进制路径，默认 bl31.bin:

UBOOT_FIT_ARM_TRUSTED_FIRMWARE_IMAGE ?= "bl31.bin"

相对路径基于 U-Boot 的 B，也可用绝对路径，例如:

UBOOT_FIT_ARM_TRUSTED_FIRMWARE_IMAGE ?= "${DEPLOY_DIR_IMAGE}/bl31.bin"

TF-A 若由独立配方构建，需在 U-Boot bbappend 添加依赖。配方 trusted-firmware-a 来自 meta-arm:

do_compile[depends] += "trusted-firmware-a:do_deploy"

UBOOT_FIT_CONF_DESC 

覆盖 U-Boot FIT 配置节点的描述属性。

UBOOT_FIT_CONF_FIRMWARE 

将一个镜像加入 U-Boot ITS 配置节点的 firmware 属性，选择最先启动的镜像:

UBOOT_FIT_CONF_FIRMWARE = "fwa"

未设置时使用 loadables 第一项。

UBOOT_FIT_CONF_USER_LOADABLES 

向 U-Boot ITS 配置节点的 loadables 添加一个或多个自定义镜像。由配方本地 shell 处理，需正确转义，如引号:

UBOOT_FIT_CONF_USER_LOADABLES = '\"fwa\", \"fwb\"'

UBOOT_FIT_DESC 

编入 U-Boot fitImage 的描述字符串，由 uboot-sign 默认设置:

UBOOT_FIT_DESC ?= "U-Boot fitImage for ${DISTRO_NAME}/${PV}/${MACHINE}"

UBOOT_FIT_GENERATE_KEYS 

决定签名密钥不存在时是否在 SPL_SIGN_KEYDIR 生成，默认 "0"。

启用方式:

UBOOT_FIT_GENERATE_KEYS = "1"

由 uboot-sign 使用。

UBOOT_FIT_HASH_ALG 

创建 U-Boot FIT 的哈希算法，uboot-sign 默认 sha256。

UBOOT_FIT_KEY_GENRSA_ARGS 

openssl genrsa 生成签名 RSA 私钥的参数， uboot-sign 默认 -F4。

UBOOT_FIT_KEY_REQ_ARGS 

openssl req 生成签名证书的参数，uboot-sign 默认 -batch -new，分别表示非交互和生成新密钥。

UBOOT_FIT_KEY_SIGN_PKCS 

U-Boot FIT 签名公钥证书格式，uboot-sign 默认 x509。

UBOOT_FIT_SIGN_ALG 

U-Boot FIT 签名算法，uboot-sign 默认 rsa2048。

UBOOT_FIT_SIGN_NUMBITS 

U-Boot FIT 签名私钥位数，uboot-sign 默认 2048。

UBOOT_FIT_TEE 

可信执行环境（TEE）安全执行代码，确保周围系统资产管理的高可信度。此变量启用包含 TEE 二进制的 U-Boot FIT 生成。

默认 "0"，设为 "1" 启用:

UBOOT_FIT_TEE = "1"

UBOOT_FIT_TEE_IMAGE 

TEE 二进制路径，默认 tee-raw.bin:

UBOOT_FIT_TEE_IMAGE ?= "tee-raw.bin"

相对路径基于 U-Boot B，也可指定绝对路径，例如:

UBOOT_FIT_TEE_IMAGE ?= "${DEPLOY_DIR_IMAGE}/tee-raw.bin"

TEE 若由独立配方构建，需在 U-Boot bbappend 添加依赖。配方 optee-os 来自 meta-arm:

do_compile[depends] += "optee-os:do_deploy"

UBOOT_FIT_USER_SETTINGS 

向 U-Boot ITS 添加用户片段，可包含一个或多个自定义 /images 节点。详情见 https://fitspec.osfw.foundation/。

原始 ITS 内容：

images {
    uboot {
        description = "U-Boot image";
        data = /incbin/("u-boot-nodtb.bin");
        type = "standalone";
        os = "u-boot";
        arch = "";
        compression = "none";
        load = <0x80000000>;
        entry = <0x80000000>;
    };
};

用户可在变量中包含自定义片段，例如:

UBOOT_FIT_FWA_ITS = '\
    fwa {\n\
        description = \"FW A\";\n\
        data = /incbin/(\"fwa.bin\");\n\
        type = \"firmware\";\n\
        arch = \"\";\n\
        os = \"\";\n\
        load = <0xb2000000>;\n\
        entry = <0xb2000000>;\n\
        compression = \"none\";\n\
    };\n\
'

UBOOT_FIT_USER_SETTINGS = "${UBOOT_FIT_FWA_ITS}"

由配方本地 shell 处理，需正确转义，如转义引号、用 \n 添加换行。

生成的 ITS 内容：

images {
    uboot {
        description = "U-Boot image";
        data = /incbin/("u-boot-nodtb.bin");
        type = "standalone";
        os = "u-boot";
        arch = "";
        compression = "none";
        load = <0x80000000>;
        entry = <0x80000000>;
    };
    fwa {
        description = "FW A";
        data = /incbin/("fwa.bin");
        type = "firmware";
        arch = "";
        os = "";
        load = <0xb2000000>;
        entry = <0xb2000000>;
        compression = "none";
    };
};

UBOOT_FITIMAGE_ENABLE 

为 U-Boot 生成 FIT 镜像，是实现验证启动的一种方式。

默认 "0"，设为 "1" 启用:

UBOOT_FITIMAGE_ENABLE = "1"

详情见 uboot-sign。

UBOOT_FRAGMENTS 

配置 U-Boot 时，将源码树中的额外配置片段传给 make。片段与 defconfig 同位于 ${S}/configs/。

例如:

UBOOT_MACHINE = "am62x_evm_r5_defconfig"
UBOOT_FRAGMENTS = "am62x_r5_usbdfu.config"

详情见 uboot-config。

UBOOT_INITIAL_ENV_BINARY 

启用二进制格式 U-Boot 初始环境生成，默认 "0"，设为 "1" 启用:

UBOOT_INITIAL_ENV_BINARY = "1"

启用后还必须通过 UBOOT_INITIAL_ENV_BINARY_SIZE 设置环境大小。

由 uboot-config 使用。

结果可通过 WIC 或其他方法刷写到环境偏移，覆盖已有环境。WKS 示例:

part --source rawcopy --sourceparams="file=u-boot-initial-env-sd.bin" --ondisk sda --no-table --offset 4096k

此例将 u-boot-initial-env-sd.bin 刷写到 4096 KiB 偏移。

UBOOT_INITIAL_ENV_BINARY_REDUND 

U-Boot 配置启用冗余环境时，应设置此变量，使输出环境二进制正确包含冗余环境。

默认 "0"，设为 "1" 启用:

UBOOT_INITIAL_ENV_BINARY_REDUND = "1"

还必须将 UBOOT_INITIAL_ENV_BINARY 设为 "1"。

由 uboot-config 使用。

UBOOT_INITIAL_ENV_BINARY_SIZE 

U-Boot 初始环境二进制大小，单位字节，支持十六进制和十进制:

UBOOT_INITIAL_ENV_BINARY_SIZE = "0x4000"

由 uboot-config 使用。

UBOOT_LOADADDRESS 

U-Boot 镜像加载地址，创建时作为命令行参数传给 uboot-mkimage。

64 位地址还需设置：

FIT 镜像的 FIT_ADDRESS_CELLS。
U-Boot FIT 镜像的 UBOOT_FIT_ADDRESS_CELLS。

由 kernel-fit-image、kernel-uimage、 kernel、uboot-config 和 uboot-sign 使用。

UBOOT_LOCALVERSION 

向 U-Boot 本地版本追加字符串。例如构建版本为 2013.10，以下设置使报告的完整版本为 2013.10-yocto:

UBOOT_LOCALVERSION = "-yocto"

UBOOT_MACHINE 

构建 U-Boot 时传给 make 的目标平台配置值，通常在 conf/machine/machine_name.conf 中设置。

有效值见 U-Boot README 的“Selection of Processor Architecture and Board Type”。

UBOOT_MAKE_OPTS 

配置和编译 U-Boot 时传给 make 的额外选项。

详情见 uboot-config。

UBOOT_MAKE_TARGET 

Makefile 调用的目标，默认 all。

UBOOT_MKIMAGE 

kernel-fit-image 组装 FIT 所用 mkimage 命令名，可替换为其他命令、包装脚本或函数，默认 uboot-mkimage。

UBOOT_MKIMAGE_DTCOPTS 

kernel-fit-image 创建 FIT 时通过 mkimage -D 传给设备树编译器的选项。未设置时不传 -D。

uboot-sign 也使用此变量。

UBOOT_MKIMAGE_KERNEL_TYPE 

传给 uboot-mkimage 的内核类型参数，默认 kernel。

UBOOT_MKIMAGE_SIGN 

kernel-fit-image 组装后签署 FIT 的 mkimage 命令名（启用时）。可替换为其他命令、包装脚本或函数，默认 "${UBOOT_MKIMAGE}"。

UBOOT_MKIMAGE_SIGN_ARGS 

kernel-fit-image 签署 FIT 时传给 mkimage 的可选额外参数。

UBOOT_RD_ENTRYPOINT 

RAM 磁盘镜像入口点，kernel-fit-image 创建 FIT 的 Image Tree Source 时使用。

UBOOT_RD_LOADADDRESS 

RAM 磁盘镜像加载地址，kernel-fit-image 创建 FIT 的 Image Tree Source 时使用。

UBOOT_SIGN_ENABLE 

启用 FIT 签名，默认 "0"。

由 uboot-config 定义和使用。

同时作为 kernel-fit-image 所用 FIT_KERNEL_SIGN_ENABLE 的默认值。

为 "1" 时，kernel-fit-image 在构建时使用指定私钥签署 FIT， uboot-sign 将对应公钥注入 U-Boot 设备树。 U-Boot 因而在启动时验证真实性和完整性，防止加载未经授权或被篡改的镜像。

详情见 https://docs.u-boot.org/en/v2025.10/usage/fit/signature.html。

UBOOT_SIGN_KEYDIR 

FIT 签名 RSA 密钥和证书目录，供 kernel-fit-image （经 FIT_KERNEL_SIGN_KEYDIR）和 uboot-sign 使用。

UBOOT_SIGN_KEYNAME 

kernel-fit-image 经 FIT_KERNEL_SIGN_KEYNAME 使用的签名密钥名称，文件位于 UBOOT_SIGN_KEYDIR。若目录包含 dev.key 和 dev.crt，应设为 dev。

UBOOT_SUFFIX 

生成 U-Boot 的扩展名，例如 u-boot.sb 的 .sb，默认 .bin。

UBOOT_TARGET 

构建 U-Boot 的目标，直接作为 make 命令的一部分，如 SPL、AIS。未显式设置时使用 all。

UBOOT_VERSION 

安装和部署文件名包含包版本 PV 及修订 PR。此变量保存这部分信息，可按需覆盖。

UKI_CMDLINE 

继承 uki 时，启动统一内核镜像（UKI）所用的内核命令行，默认 rootwait root=LABEL=root console=${KERNEL_CONSOLE}。

UKI_CONFIG_FILE 

继承 uki 时， ukify 命令的可选配置文件。

UKI_DEVICETREE 

继承 uki 时，要包含到 UKI 的设备树列表。

UKI_FILENAME 

继承 uki 时，生成的 UKI 输出文件名，默认 uki.efi。

UKI_KERNEL_FILENAME 

继承 uki 时，输入内核镜像名，默认 KERNEL_IMAGETYPE。

UKI_SB_CERT 

继承 uki 时，与 UKI_SB_KEY 私钥匹配的可选 UEFI 安全启动证书。

UKI_SB_KEY 

继承 uki 时，用于签署 UKI 的可选 UEFI 安全启动私钥。

UKIFY_CMD 

继承 uki 时，构建 UKI 的 ukify 命令，默认 ukify build。

UNINATIVE_CHECKSUM 

继承 uninative 时，变量标志保存 UNINATIVE_URL 发布的 uninative 压缩包校验和，每种架构的压缩包对应一个校验和。例如:

UNINATIVE_CHECKSUM[aarch64] ?= "812045d826b7fda88944055e8526b95a5a9440bfef608d5b53fd52faab49bf85"
UNINATIVE_CHECKSUM[i686] ?= "5cc28efd0c15a75de4bcb147c6cce65f1c1c9d442173a220f08427f40a3ffa09"
UNINATIVE_CHECKSUM[x86_64] ?= "4c03d1ed2b7b4e823aca4a1a23d8f2e322f1770fc10e859adcede5777aff4f3a"

UNINATIVE_URL 

继承 uninative 时，uninative 压缩包发布 URL。

UNKNOWN_CONFIGURE_OPT_IGNORE 

配置脚本报告无效时，不应在 do_configure 产生警告的选项。通常应不传无效选项，如从 EXTRA_OECONF 或 PACKAGECONFIG_CONFARGS 删除。但某些类会向所有配置脚本传通用选项，部分脚本可能不支持，对此警告没有意义，因此将这些选项加入本变量。

检查属于 insane，仅当配方继承 autotools* 才启用。

UNPACKDIR 

base 使用，指定 do_unpack 解包所获取源码的位置。

UPDATERCPN 

继承 update-rc.d 时，指定包含待启用初始化脚本的软件包。

默认 ${PN}，多数配方把初始化脚本放在主包，因此很少需单独设置。

UPSTREAM_CHECK_COMMITS 

devtool latest-version recipe 可逐配方检查上游最新版本。源码来自 Git 但发布不以标签标识时，设为 1，构建系统会将最新提交与配方当前 SRCREV 比较:

UPSTREAM_CHECK_COMMITS = "1"

UPSTREAM_CHECK_GITTAGREGEX 

devtool latest-version recipe 可逐配方检查上游最新版本。 Git 源码通过全部标签列表中的最新标签确定版本。

默认过滤不正确时，可提供正则表达式仅匹配相关标签:

UPSTREAM_CHECK_GITTAGREGEX = "git_tag_regex"

UPSTREAM_CHECK_REGEX 

包检查系统解析 UPSTREAM_CHECK_URI 页面时，使用此正则代替默认表达式:

UPSTREAM_CHECK_REGEX = "package_regex"

UPSTREAM_CHECK_URI 

devtool latest-version recipe 可逐配方检查最新版本。源码来自压缩包时，获取其目录列表并查找更新的压缩包。此方法无效时，可指定另一个包含最新压缩包链接的 URI:

UPSTREAM_CHECK_URI = "recipe_url"

UPSTREAM_STABLE_RELEASE_REGEX 

版本检查中仅保留同一稳定系列的正则表达式。设置后，BitBake 的 git、wget、crate 获取器过滤发现的上游版本，丢弃不匹配项。

例如当前版本 1.4.2，正则 ^1\.4(\.\d+)*$，则 1.4.7 可升级，1.5.0 不可。

点分隔版本可继承 upstream-stable-release-point 自动生成，其他版本方案可直接设置:

UPSTREAM_STABLE_RELEASE_REGEX = "^10\.2p\d+$"

设置条件见稳定点版本升级。

UPSTREAM_VERSION_UNKNOWN 

devtool latest-version recipe 可逐配方检查最新版本。如果 UPSTREAM_CHECK_URI、UPSTREAM_CHECK_REGEX、 UPSTREAM_CHECK_GITTAGREGEX 和 UPSTREAM_CHECK_COMMITS 的任何组合都无法确定，可设为 1，确认无法执行此检查:

UPSTREAM_VERSION_UNKNOWN = "1"

USE_DEVFS 

决定是否用 devtmpfs 填充 /dev，未设置时默认 "1"。静态填充的 /dev 通常设为 "0"。

详情见“选择设备管理器”。

USE_NLS 

决定支持翻译的配方是否构建翻译。可选：

yes：启用。
no：禁用。

配方可依据此值启用翻译，gettext 等类用它启用 Gettext 支持。

USE_VT 

使用 SysVinit 时，决定是否在虚拟终端运行 getty 以允许登录。

未指定时默认 "1"。没有图形显示器、不需虚拟终端的机器，通常在机器配置中设为 "0"。

USER_CLASSES 

全局继承的类列表，启用构建系统额外功能。

类必须位于 classes-global/ 或 classes/ 子目录。

meta/conf/templates/default/local.conf.sample 的默认列表:

USER_CLASSES ?= "buildstats"

USERADD_DEPENDS 

列出通过 USERADD_PARAM / GROUPADD_PARAM 创建本配方所需用户或组的配方，确保构建时这些用户和组可用。

USERADD_ERROR_DYNAMIC 

为 error 时，uid/gid 若未在 USERADD_UID_TABLES 和 USERADD_GID_TABLES 所列文件中定义，构建系统报错；为 warn 则警告。

系统默认动态分配 uid/gid，因此此变量默认不设置。使用静态 ID 时应在 configuration file 设置:

USERADD_ERROR_DYNAMIC = "error"

覆盖默认行为也意味着要通过 USERADDEXTENSION、 USERADD_UID_TABLES、USERADD_GID_TABLES 设置静态值。

备注

warn 会为所有配方每个未定义的 uid/gid 警告； error 则仅对实际构建的配方报错，避免为永不构建的配方添加静态 ID。

USERADD_GID_TABLES 

指定安装软件包、添加组时获取静态 gid 的密码文件。

构建系统在 BBPATH 查找 files/group 并应用其中的 ID。在 configuration file 设置:

USERADD_GID_TABLES = "files/group"

备注

USERADDEXTENSION 为 useradd-staticids 时使用静态 gid。

USERADD_PACKAGES 

继承 useradd* 时，指定配方中需要添加用户／组的包。

继承该类必须设置，例如为主包添加用户:

USERADD_PACKAGES = "${PN}"

备注

还需设置 USERADD_PARAM、GROUPADD_PARAM、 USERMOD_PARAM 中的至少一个。

USERADD_PARAM 

继承 useradd* 时，指定包安装时添加用户所传给 useradd 的参数。

dbus 示例:

USERADD_PARAM:${PN} = "--system --home ${localstatedir}/lib/dbus \
                       --no-create-home --shell /bin/false \
                       --user-group messagebus"

标准 Linux useradd 命令见 useradd(8)。

USERADD_UID_TABLES 

指定安装软件包、添加用户时获取静态 uid 的密码文件。

系统在 BBPATH 查找 files/passwd 并应用其中的 uid。在 configuration file 设置:

USERADD_UID_TABLES = "files/passwd"

备注

USERADDEXTENSION 为 useradd-staticids 时使用静态 uid。

USERADDEXTENSION 

为 useradd-staticids 时，全部用户和组添加依据 BBPATH 中的静态 passwd、group。

在 configuration file 中这样启用静态 uid/gid:

USERADDEXTENSION = "useradd-staticids"

备注

使用静态 ID 时，构建系统采用 useradd*。

还必须用 USERADD_UID_TABLES 和 USERADD_GID_TABLES 指定 files/passwd、files/group，并应设置 USERADD_ERROR_DYNAMIC。

USERMOD_PARAM 

继承 useradd* 时，指定包安装时修改用户所传给 usermod 的参数。通常用于将用户加入一个或多个组，例如:

USERMOD_PARAM:${PN} = "--append --groups group1,group2 user"

VIRTUAL-RUNTIME 

定义运行时虚拟包的常用前缀，通常用于 RDEPENDS 或镜像定义。

例如 VIRTUAL-RUNTIME_base-utils 可选择 BusyBox 工具:

VIRTUAL-RUNTIME_base-utils = "busybox"

或 GNU Coreutils 等项目的完整实现:

VIRTUAL-RUNTIME_base-utils = "packagegroup-core-base-utils"

两个使用此虚拟运行时包的示例，第一个来自 initramfs-framework_1.0.bb:

RDEPENDS:${PN} += "${VIRTUAL-RUNTIME_base-utils}"

第二个来自 core-image-initramfs-boot 镜像定义:

PACKAGE_INSTALL = "${INITRAMFS_SCRIPTS} ${VIRTUAL-RUNTIME_base-utils} base-passwd"

WARN_QA 

指定失败时作为警告报告的 QA 检查，在发行版配置中设置。可控制的检查列表见“insane”。

WATCHDOG_RUNTIME_SEC 

控制 systemd 配方 /etc/systemd/system.conf 的 RuntimeWatchdogSec，默认空字符串。

WATCHDOG_TIMEOUT 

watchdog-config 及 systemd 重启时使用的超时秒数，默认 60。

WESTON_USER 

定义 Weston 用户名。

WESTON_USER_HOME 

WESTON_USER 定义 Weston 用户主目录路径。

WIC_CREATE_EXTRA_ARGS 

IMAGE_FSTYPES 含 wic 时，BitBake 构建镜像配方会自动生成 Wic 镜像。过程中调用 wic create，此变量追加到命令末尾，以传入额外参数。

例如添加 -D 或 --debug，可增加创建过程中写入 Wic 日志的调试信息。

WIC_SECTOR_SIZE 

警告

已弃用，改用 wic --sector-size 参数，见应将 WIC_SECTOR_SIZE 替换为 --sector-size。

控制 Wic 镜像扇区大小，实际设置传给 parted 的 PARTED_SECTOR_SIZE 环境变量，默认 512。

创建镜像方法见“使用 Wic 创建分区镜像”。

WIRELESS_DAEMON 

为 connman 和 packagegroup-base 指定无线守护程序，默认 wpa-supplicant，注意使用连字符而非下划线。

WKS_FILE 

指定构建系统创建分区镜像 image.wic 的 Wic kickstart 文件位置。创建方法见“使用 Wic 创建分区镜像”，格式见“OpenEmbedded Kickstart（.wks）参考”。

WKS_FILE_DEPENDS 

放在镜像配方中，列出构建时依赖。仅在 IMAGE_FSTYPES 含 Wic 相关条目时有效，不创建 Wic 镜像则无效。

类似 DEPENDS，所列依赖会加入 DEPENDS。

可指定构建 Wic 所需额外依赖，如 native 工具、引导加载程序等，例如:

WKS_FILE_DEPENDS = "some-native-tool"

将 some-native-tool 替换为实际依赖的 native 工具。

WKS_FILES 

创建分区镜像时的候选 Wic kickstart 文件列表，从左到右仅使用找到的第一个。

仅当多个 .wks 都可生成镜像时有用，例如不同硬件平台的多个层各提供不同文件，此时在变量中列出全部候选。

若仅一个文件，改用 WKS_FILE。

WORKDIR 

构建配方的工作目录路径，位于 TMPDIR 树中，专属于当前配方和其构建目标系统。

定义如下:

${TMPDIR}/work/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}

实际目录由以下因素决定：

TMPDIR：顶层构建输出目录。
MULTIMACH_TARGET_SYS：目标系统标识。
PN：配方名。
EXTENDPE：epoch；多数配方未指定 PE，此时为空。
PV：配方版本。
PR：配方修订。

例如源码顶层 bitbake-builds，默认 Build Directory 为 bitbake-builds/build，目标系统 qemux86-poky-linux，配方 foo_1.3.0-r0.bb，工作目录为:

bitbake-builds/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0

XSERVER 

指定为当前机器提供 X 服务器与驱动的软件包。前提是镜像直接包含 packagegroup-core-x11-xserver，或通过 IMAGE_FEATURES 的 x11-base 间接包含。

机器配置未指定时，默认为 "xserver-xorg xf86-video-fbdev xf86-input-evdev"。

XZ_MEMLIMIT 

xz 最大内存用量，占系统内存的百分比。不限制时可能使用大量内存，与其他并行任务冲突。50% 是实践中较合适的值。

XZ_THREADS 

xz 压缩的并行线程数。

默认随核数增长，但至少为 2，确保始终多线程并使输出内容确定。设为 1 也能构建，但输出与多线程不同。

大量任务并行时，限制此值有助于控制系统资源。

ZSTD_COMPRESSION_LEVEL 

ZStandard 压缩级别，1 到 19，按上游默认选择 3。更高级别文件更小，但耗时更长。

ZSTD_THREADS 

ZStandard 压缩的并行线程数。

默认随核数增长，但至少为 2，确保始终多线程并使输出内容确定。设为 1 也能构建，但输出与多线程不同。

大量任务并行时，限制此值有助于控制系统资源。