5 源码目录结构
Source Directory 包含大量文件、目录和子目录。 了解它们的位置和内容，是高效使用 Yocto Project 的关键。 本章介绍源码目录，以及其中的文件和目录。
备注
OpenEmbedded 构建系统不支持文件名或目录名中的空格。 请确保所用源码目录不包含这类名称。
以下各节假设 Source Directory 的核心组件组织如下：
├── build/
│ └── ...
└── layers/
├── bitbake/
├── meta-yocto/
├── openembedded-core/
└── yocto-docs/
5 顶层核心组件
本节介绍 Source Directory 的顶层组件。
5.1.1 bitbake/
为便于使用，此目录包含一份 BitBake，通常对应 BitBake 项目当前的稳定版本。 BitBake 是 Metadata 解释器，读取 Yocto Project 元数据， 并运行其中定义的任务。故障通常源于元数据错误，而非 BitBake 本身。
运行 bitbake 命令时，会启动位于 bitbake/bin/ 的主可执行文件。
加载环境设置脚本（oe-init-build-env）后，
scripts/ 和 bitbake/bin/ 会按此顺序加入 shell 的 PATH 环境变量。
有关 BitBake 的更多信息，请参阅 BitBake 用户手册。
5.1.2 build/
在源码树和构建输出放在一起的标准配置中，此目录包含用户配置文件
以及 OpenEmbedded 构建系统生成的输出。
首次通过 source 加载 OpenEmbedded 构建环境设置脚本
（oe-init-build-env）时，会创建 Build Directory。
也可以在加载设置脚本时提供目录名称，将输出和配置文件放到 Source Directory 之外。 有关这种通常称为“树外构建”的方式，请参阅“oe-init-build-env”一节。
Build Directory 内容的详细说明见 “构建目录 --- build/”一节。
5.1.3 layers/yocto-docs/
Yocto 文档仓库托管于 https://git.yoctoproject.org/yocto-docs。
此目录包含 Yocto Project 文档源码，以及生成 PDF 和 HTML 版手册的模板与工具。
每份手册都有独立的子目录，例如本参考手册的文件位于 ref-manual/ 中。
使用 BitBake 构建时，此目录不是必需的。
5.1.4 layers/openembedded-core/
OpenEmbedded-Core (OE-Core) 仓库托管于 https://git.openembedded.org/openembedded-core。
5.1.4.1 meta/
此目录包含最基本的 OpenEmbedded-Core (OE-Core) 底层元数据，
包括配方、公共类，以及仅用于模拟目标（qemux86、qemuarm 等）的
机器配置。
5.1.4.2 meta-selftest/
此目录添加 OpenEmbedded 自测试使用的额外配方和追加文件， 用于验证构建系统的行为。除非需要运行自测试， 否则无需将此层加入 build/conf/bblayers.conf。
5.1.4.3 meta-skeleton/
此目录包含用于 BSP 和内核开发的配方模板。
5.1.4.4 scripts/
此目录包含各种集成脚本，在 Yocto Project 环境中实现额外功能，例如 QEMU 脚本。
oe-init-build-env 会将此目录加到 shell 的 PATH 最前面。
scripts 还包含有助于向 Yocto Project 回馈贡献的实用脚本，
例如 create-pull-request 和 send-pull-request。
5.1.4.5 oe-init-build-env
此脚本设置 OpenEmbedded 构建环境。
在 shell 中通过 source 运行它，会根据当前工作目录修改 PATH
并设置其他核心 BitBake 变量。运行 BitBake 命令之前必须先运行环境设置脚本。
主要工作由它调用 scripts 目录中的其他脚本完成。
运行后，Yocto Project 环境被设置好，Build Directory 被创建， 当前工作目录切换到 Build Directory， 并显示下一步操作的简单建议，包括一些可构建目标。例如:
$ source oe-init-build-env
### Shell environment set up for builds. ###
You can now run 'bitbake <target>'
Common targets are:
core-image-minimal
core-image-sato
meta-toolchain
meta-ide-support
You can also run generated QEMU images with a command like 'runqemu qemux86-64'
备注
使用 bitbake-setup
时，加载 Setup 构建目录中的 init-build-env
会间接加载此脚本。不过，与 oe-init-build-env 不同，
bitbake-setup 的 init-build-env 不接收参数，
因为它已位于 Build Directory 中。
oe-init-build-env 的默认输出来自
OpenEmbedded-Core (OE-Core) 的 meta/conf/templates/default
目录中的 conf-summary.txt 和 conf-notes.txt。
设计自定义发行版时，可以提供自己的版本，给出简短概要和详细使用说明，
例如发行版定义的目标列表。
更多信息请参阅《Yocto Project 开发任务手册》的
“创建自定义模板配置目录”
一节。
默认情况下，不传入 Build Directory 参数运行脚本，
会在当前工作目录创建 build/。
通过 source 加载脚本时提供该参数，则可以指定构建目录。
例如，以下命令在 Source Directory 之外创建名为 mybuilds/
的 Build Directory:
$ source oe-init-build-env ~/mybuilds
OpenEmbedded 构建系统使用模板配置文件，默认位于
OpenEmbedded-Core (OE-Core) 的 meta/conf/templates/default。
更多信息请参阅《Yocto Project 开发任务手册》的
“创建自定义模板配置目录”
一节。
备注
OpenEmbedded 构建系统不支持文件名或目录名中的空格。
如果尝试在名称包含空格的 Source Directory 中运行
oe-init-build-env，脚本会返回“没有此文件或目录”的错误。
请确保源码目录中的名称不包含空格。
5.1.5 layers/meta-yocto/
meta-yocto 仓库托管于 https://git.yoctoproject.org/meta-yocto。
5.1.5.1 meta-poky/
此目录依赖 OpenEmbedded-Core (OE-Core) 元数据， 只添加定义 Poky 参考发行版所必需的元数据。
具体来说，它包含 Poky 的发行版 configuration file：
conf/distro/poky.conf。
5.1.5.2 meta-yocto-bsp/
此目录包含 Yocto Project 参考硬件的板级支持包（BSP）。 有关 BSP 的更多信息，请参阅 Yocto Project 板级支持包（BSP）手册。
5 构建目录 --- build/
运行构建环境设置脚本 oe-init-build-env 时，
OpenEmbedded 构建系统创建 Build Directory。
如果未指定名称，则默认使用 build/。
后续解析和处理时，可通过 TOPDIR 获取构建目录名称。
5.2.1 build/buildhistory/
通过 buildhistory 类启用构建历史后， OpenEmbedded 构建系统会创建此目录。 其中按镜像、软件包和 SDK 子目录组织构建信息。 有关构建历史功能，请参阅《Yocto Project 开发任务手册》的 使用 buildhistory 维护构建输出质量 一节。
5.2.2 build/cache/
此目录包含 OpenEmbedded 构建系统使用的若干内部文件。 其路径由 PERSISTENT_DIR 定义。
它还包含文本文件 sanity_info，用于跟踪重要构建信息，
例如 TMPDIR、SSTATE_DIR 的值，以及主机发行版名称和版本。
不应在不同构建之间共享此目录。
备注
当 BB_HASHSERVE 设为 auto 时，
哈希等价 数据库默认位于此目录。
如果需要共享 哈希等价 数据库，
不要共享此文件，而应按照《Yocto Project 开发任务手册》的
设置哈希等价服务器 设置哈希等价服务器。
5.2.3 build/conf/local.conf
此配置文件包含构建环境的本地用户配置。
例如，可以尝试设置或追加 DISTRO_FEATURES、IMAGE_FEATURES， 或为特定配方设置 PACKAGECONFIG 来调整其构建配置。 如果希望发布并共享此文件中的修改，建议将其放入发行版 configuration file，或根据这些修改创建层的 配置片段。
通过 source 加载顶层环境设置脚本 oe-init-build-env 时，
OpenEmbedded Build System 可以根据 local.conf.sample
创建 build/conf/local.conf。
所用 local.conf.sample 取决于 TEMPLATECONF 脚本变量，
其默认值为 OpenEmbedded-Core (OE-Core) 中的
meta/conf/templates/default。
该变量指向样例文件的来源，因此可以在顶层环境设置脚本中按如下方式设置它，
从任意层配置构建环境:
TEMPLATECONF=your_layer/conf/templates/your_template_name
取得样例文件后，构建过程使用 sed 将所有 ##OEROOT##
替换为最终的 ${OEROOT} 值。
备注
可以查看 OpenEmbedded-Core (OE-Core) 中的
layers/openembedded-core/scripts/oe-setup-builddir，
了解 TEMPLATECONF 的使用方式。
5.2.4 build/conf/bblayers.conf
此配置文件定义 BitBake 要遍历的目录树，即 层。 build/conf/bblayers.conf 通过 BBLAYERS 列出 BitBake 应查找的层。
通过 source 加载顶层环境设置脚本 oe-init-build-env 时，
OpenEmbedded 构建系统可以根据 bblayers.conf.sample 创建此文件。
与 build/conf/local.conf 一样，所用的
bblayers.conf.sample 取决于 TEMPLATECONF，
默认值为 meta/conf/templates/default。
它指向样例文件的来源，因此可以在顶层环境设置脚本中按如下方式设置它，
以任意层为基础建立构建:
TEMPLATECONF=your_layer/conf/templates/your_template_name
取得样例文件后，构建过程使用 sed 将所有 ##OEROOT##
替换为最终的 ${OEROOT} 值。
备注
可以查看 OpenEmbedded-Core (OE-Core) 中的
scripts/oe-setup-builddir，了解 TEMPLATECONF 的定义方式。
5.2.5 build/conf/site.conf
此配置文件包含构建环境的站点专用配置。
例如，可以编辑此文件限制 BitBake 使用的线程数 （BB_NUMBER_THREADS），或设置下载文件的存放位置（DL_DIR）。
多个构建目录可以共享此文件。例如， bitbake-setup 将 build/conf/site.conf 设为指向公共 build/conf/auto.conf 文件的符号链接:
├── poky-master-poky-distro_poky-machine_qemux86-64/
│ └── build/
│ └── conf/
│ └── site.conf -> ../../../site.conf
├── poky-master-poky-with-sstate-distro_poky-machine_qemux86-64/
│ └── build/
│ └── conf/
│ └── site.conf -> ../../../site.conf
└── site.conf
这样，多个构建配置可以共用站点设置。
备注
有关 bitbake-setup 的用法，请参阅 Yocto Project 快速构建。
5.2.6 build/conf/bblock.conf
此文件由 bblock 生成，包含其锁定的签名。
默认不存在，首次调用 bblock 时创建。
5.2.7 build/conf/toolcfg.conf
此文件包含由 bitbake-config-build 等工具自动修改的配置变量，不应手动编辑。
5.2.8 build/conf/auto.conf
此文件用于持续集成环境，例如 Yocto Project 的 Autobuilder。 本地构建时不应创建或修改它。
5.2.9 build/downloads/
此目录包含已下载的上游源码压缩包。 可以在多个构建间复用，或移到其他位置。 其位置由 DL_DIR 控制。
5.2.10 build/sstate-cache/
此目录包含共享状态缓存。 可以在多个构建间复用，或移到其他位置。 其位置由 SSTATE_DIR 控制。
5.2.11 build/tmp/
OpenEmbedded 构建系统创建此目录以保存全部构建输出。 TMPDIR 指向此目录。
目录不存在时，BitBake 会创建它。
作为最后的清理手段，如果需要保留下载内容而从头构建，
可以删除 tmp 中的全部内容，或删除整个目录。
此时还应完整删除 build/sstate-cache 目录。
5.2.11.1 build/tmp/buildstats/
此目录保存 buildstats 类生成的构建统计信息。
5.2.11.2 build/tmp/cache/
BitBake 解析元数据（配方和配置文件）时，将结果缓存到 build/tmp/cache/，
以加快后续构建。缓存按机器分别保存。
后续构建中，BitBake 检查每个配方及其包含文件、追加文件等是否修改。 例如，可以通过文件修改时间（mtime）和内容哈希检测变更。 如果未发现修改，就复用缓存中的解析结果；否则重新解析。
5.2.11.3 build/tmp/deploy/
此目录包含 OpenEmbedded 构建过程的最终输出，由 DEPLOY_DIR 指向。 有关其内容的详情，请参阅《Yocto Project 概览与概念手册》的 “镜像”和 “应用开发 SDK”两节。
5.2.11.3.1 build/tmp/deploy/deb/
此目录接收构建生成的 .deb 软件包，按不同架构类型归入对应软件包源。
5.2.11.3.2 build/tmp/deploy/rpm/
此目录接收构建生成的 .rpm 软件包，按不同架构类型归入对应软件包源。
5.2.11.3.3 build/tmp/deploy/ipk/
此目录接收构建生成的 .ipk 软件包。
5.2.11.3.4 build/tmp/deploy/licenses/
此目录接收软件包许可证信息。
例如，它为 bash、busybox、glibc 等软件包设置子目录，
其中保存相应的 COPYING 许可证文件和其他许可信息。
有关许可证的信息，请参阅《Yocto Project 开发任务手册》的
“在产品生命周期中维护开源许可证合规”
一节。
5.2.11.3.5 build/tmp/deploy/spdx/
此目录包含用于创建软件物料清单（SBOM）的 SPDX 格式 JSON 文件。详情见《Yocto Project 开发任务手册》的 “创建软件物料清单”一节。
5.2.11.3.6 build/tmp/deploy/images/
此目录存放构建的基本输出产物，例如引导加载程序镜像、内核、根文件系统等。 若要将构建镜像烧写到设备，可在这里查找所需组件。
删除此目录中的文件时应谨慎。旧镜像（例如 core-image-*）可以安全删除。
但内核（*zImage*、*uImage* 等）、引导加载程序和其他辅助文件
可能早在构建镜像之前就已部署到这里。
它们不是镜像直接生成的，因此删除后再次构建镜像并不会自动重建。
如果意外删除了这些文件，需要强制重新创建， 为此必须知道哪个目标生成了它们。 例如，以下命令重新构建并创建内核文件:
$ bitbake -c clean virtual/kernel
$ bitbake virtual/kernel
5.2.11.3.7 build/tmp/deploy/sdk/
OpenEmbedded 构建系统创建此目录保存工具链安装脚本。 执行这些脚本可安装与目标硬件匹配的系统根目录。 更多信息请参阅《Yocto Project 应用开发与可扩展软件开发工具包（eSDK）手册》的 “构建 SDK 安装程序”一节。
5.2.11.4 build/tmp/hosttools/
OpenEmbedded 构建系统在此目录创建符号链接，指向任务中允许调用的主机组件。 这些基本组件列于 构建主机所需的软件包 一节， 也列在 HOSTTOOLS 中。 可用主机组件被限制在此列表范围内，以防止主机环境污染构建。
5.2.11.5 build/tmp/pkgdata/
此目录保存 do_packagedata 生成的软件包元数据。 文件包含 OpenEmbedded 构建系统生成的各输出软件包的信息， 供构建系统用于多种用途，例如 “使用 oe-pkgdata-util 查看软件包信息”。
5.2.11.6 build/tmp/sstate-control/
此目录保存共享状态清单。 共享状态代码通过清单记录每个共享状态任务安装的文件， 以便在清理配方或安装新版本前删除这些文件。 构建系统还利用清单检测一个任务的文件是否覆盖另一任务的文件， 并在发现覆盖时发出警告。
5.2.11.7 build/tmp/sysroots-components/
此目录保存系统根目录内容。
do_prepare_recipe_sysroot 针对 DEPENDS 中的每个配方，
将相应内容链接或复制到配方专用的系统根目录。
此目录通过共享状态机制填充，路径由 COMPONENTS_DIR 指定。
除少数特殊情况外，其处理应自动完成，
配方不应直接引用 build/tmp/sysroots-components。
5.2.11.8 build/tmp/sysroots/
旧版 OpenEmbedded 构建系统曾为每台机器创建全局共享系统根目录，
并创建一个 native 系统根目录。
从 Yocto Project 2.3 起，系统根目录位于各配方专用的 WORKDIR 中，
因此不再使用 build/tmp/sysroots/。
备注
仍可通过 bitbake build-sysroots 填充 build/tmp/sysroots/，
在某些场景下用于兼容。不过通常不建议这样做，
应使用各配方专用的系统根目录。
5.2.11.9 build/tmp/stamps/
此目录保存 BitBake 用于记录哪些任务已运行及其运行时间的信息。 目录按架构、软件包名称和版本细分。例如:
stamps/all-poky-linux/distcc-config/1.0-r0.do_build-2fdd....2do
虽然文件内容为空，BitBake 仍利用文件名和时间戳进行跟踪。
有关 BitBake 如何通过时间戳文件判断任务是否应重新运行， 请参阅《Yocto Project 概览与概念手册》的 “戳记文件与任务重跑”一节。
5.2.11.10 build/tmp/log/
此目录保存未放在软件包 WORKDIR 中的通用日志，
例如 do_check_pkg 或 do_distro_check 的输出。
运行构建不一定会创建此目录。
5.2.11.11 build/tmp/work/
此目录包含 BitBake 所构建软件包的、按架构划分的工作子目录。 全部任务都在相应工作目录中执行。 例如，某个软件包的源码在自己的工作目录内解包、应用补丁、配置和编译。 目录内部依据 WORKDIR 定义，按正在编译的软件包组和版本组织。
可以通过一个典型工作目录了解其结构。
例如，在 Yocto Project 中为 qemux86 构建 linux-yocto-kernel-3.0 时，
会创建 tmp/work/qemux86-poky-linux/linux-yocto/3.0+git1+<.....>，
即 WORKDIR。源码解包到其中的 sources/linux-qemux86-standard-build，
再由 Quilt 应用补丁。有关 Quilt 的更多信息，见《Yocto Project 开发任务手册》的
“在工作流程中使用 Quilt”一节。
linux-qemux86-standard-build 中会创建标准 Quilt 目录
linux-3.0/patches 和 linux-3.0/.pc，可以使用标准 Quilt 命令。
WORKDIR 中还会生成其他目录。
最重要的是 WORKDIR/temp/，其中保存各任务的日志（log.do_*.pid）
以及 BitBake 为各任务运行的脚本（run.do_*.pid）。
make install 将输出放入 WORKDIR/image/，
随后在 WORKDIR/packages-split/ 中拆分为子软件包。
5.2.11.11.1 build/tmp/work/tunearch/recipename/version/
配方工作目录，即 ${WORKDIR}。
如“build/tmp/sysroots/”一节所述，
从 Yocto Project 2.3 起，OpenEmbedded 构建系统在各配方自己的工作目录
（WORKDIR）中构建它们。
路径由构建架构（例如 TUNE_PKGARCH、MACHINE_ARCH
或“allarch”）、配方名称及版本
（PE:PV-PR）组成。
每个配方工作目录中的主要子目录如下：
${WORKDIR}/temp：包含配方各任务的日志、包含实际执行代码的“run”文件， 以及列出任务执行顺序的log.task_order。${WORKDIR}/image：包含 do_install 的输出， 对应任务中的${D}变量。${WORKDIR}/pseudo：包含配方在 pseudo 下执行任务时使用的数据库和日志。${WORKDIR}/sysroot-destdir：包含 do_populate_sysroot 的输出。${WORKDIR}/package：包含 do_package 尚未拆分为 各软件包之前的输出。${WORKDIR}/packages-split：包含 do_package 已拆分为 各软件包之后的输出，为配方创建的每个软件包设置单独子目录。${WORKDIR}/recipe-sysroot：填充了配方目标端依赖的目录， 结构类似目标文件系统，包含配方可能需要链接的库，例如 C 库。${WORKDIR}/recipe-sysroot-native：填充了配方 native 依赖的目录， 包含构建所需工具，例如编译器、Autoconf、libtool 等。${WORKDIR}/build：仅适用于支持源码与构建产物分离的配方。 OpenEmbedded 构建系统将其作为独立构建目录， 即${B}。
5 OpenEmbedded-Core（OE-Core）元数据 --- meta/
如前所述，OpenEmbedded-Core (OE-Core) 的 metadata 是 Yocto Project 的核心，包含以下重要部分。
5.3.1 meta/classes*/
这些目录包含 *.bbclass 文件。
类文件用于抽象公共代码，以便多个软件包复用。
每个软件包都会继承 base。
其他重要类包括 autotools*，理论上它可使任何使用
Autotools 的软件包以很少改动适配 Yocto Project；
以及 kernel，包含处理 Linux 内核的公共代码和函数。
镜像生成和打包等功能也有各自的类文件，例如 image、
rootfs* 和 package*.bbclass。
类的参考信息见“类”章。
5.3.2 meta/conf/
此目录包含核心配置文件集，从 bitbake.conf 开始包含其他所有配置文件。
查看 bitbake.conf 末尾的 include 语句会发现，
连 build/conf/local.conf 也从这里加载。
bitbake.conf 设置默认值，通常可以在
build/conf/local.conf、机器配置文件或发行版配置文件中覆盖。
5.3.2.1 meta/conf/machine/
此目录包含所有机器配置文件。
如果设置 MACHINE = "qemux86"，构建系统就在这里查找 qemux86.conf。
include 目录包含多个机器共用的数据。
若要为 Yocto Project 添加新机器支持，可以参考此目录。
5.3.2.2 meta/conf/distro/
此目录的内容控制发行版专用配置。
对 Yocto Project 而言，这里的主要文件是 defaultsetup.conf。
目录包含相关应用的版本及 SRCDATE 定义。
另一种配置的示例是 poky-bleeding.conf，不过它主要继承 Poky 配置。
5.3.2.3 meta/conf/machine-sdk/
OpenEmbedded 构建系统在此查找与 SDKMACHINE 对应的配置文件。 Yocto Project 默认提供 32 位和 64 位 x86 配置，支持部分 SDK 主机。 也可以在其他层的此子目录中添加配置文件，将支持扩展到其他 SDK 主机。
5.3.3 meta/files/
此目录包含通用许可证文件、构建系统使用的若干文本文件， 以及定义生成镜像布局的 Wic 文件。 文本文件包含最基本的设备信息，以及具有已知权限的文件和目录列表。
5.3.4 meta/lib/
此目录包含构建过程中使用的 OpenEmbedded Python 库代码，
通过 meta/conf/layer.conf 中的 addpylib 指令启用。
更多信息见
Extending Python Library Code。
5.3.5 meta/recipes-bsp/
此目录包含与特定硬件或硬件配置有关的内容，例如“u-boot”和“grub”。
5.3.6 meta/recipes-connectivity/
此目录包含与其他设备通信有关的库和应用。
5.3.7 meta/recipes-core/
此目录包含构建基本可运行 Linux 镜像所需的内容，包括常用依赖。
5.3.8 meta/recipes-devtools/
此目录包含主要供构建系统使用的工具，也可以在目标上使用它们。
5.3.9 meta/recipes-extended/
此目录包含非必需应用，相比 core 中的替代项提供更多功能。 如果需要工具的完整功能，可能会用到此目录。
5.3.10 meta/recipes-gnome/
此目录包含与 GTK+ 应用框架有关的内容。
5.3.11 meta/recipes-graphics/
此目录包含 X 及其他图形相关系统库。
5.3.12 meta/recipes-kernel/
此目录包含内核，以及强依赖内核的通用应用和库。
5.3.13 meta/recipes-multimedia/
此目录包含音频、图像和视频的编解码器及辅助工具。
5.3.14 meta/recipes-rt/
此目录包含用于使用和测试 PREEMPT_RT 内核的软件包配方和镜像配方。
5.3.15 meta/recipes-sato/
此目录包含 Sato 演示／参考 UI/UX，以及相关应用和配置数据。
5.3.16 meta/recipes-support/
此目录包含其他配方使用、但不直接纳入镜像的配方，即其他配方的依赖。
5.3.17 meta/site/
此目录包含各种架构的缓存测试结果。 交叉编译时，某些“autoconf”测试无法在实际系统上运行，因而无法确定结果； 此目录中的信息会按架构传给“autoconf”。
5.3.18 meta/recipes.txt
此文件描述 recipes-* 的内容。