Yocto Project 快速构建

欢迎！

这份简短文档将带你完成使用 Yocto Project 构建典型镜像的流程，并介绍如何 为特定硬件配置构建。你将使用 Yocto Project 构建名为 Poky 的参考嵌入式 操作系统。

备注

• 本文示例假定使用原生 Linux 系统，运行 受支持的 Ubuntu Linux 发行版。 如果用于 Yocto Project 镜像构建的机器（ Build Host ）不是原生 Linux 系统，也可以通过 OCI 容器 （使用 Docker 或 Podman）执行这些步骤。

• 可以使用 Windows Subsystem For Linux 第 2 版（WSL 2），在 Windows 10 或更高版本、Windows Server 2019 或更高版本上设置构建主机。更多信息 见 Yocto Project 开发任务手册的 设置 Windows Subsystem For Linux（WSL 2） 一节。

如果希望了解更多 Yocto Project 概念和背景知识，请参阅 Yocto Project 概述与概念手册。

兼容的 Linux 发行版

确保 Build Host 满足以下要求：

• 至少 140 GB 可用磁盘空间。更多空间有助于运行多次构建，并 通过复用构建产物提高性能。

• 至少 32 GB 内存。强烈建议使用具有尽可能多内存和 CPU 核心的现代 构建主机，以获得最佳构建性能。

• 运行受支持的 Linux 发行版，例如较新的 Fedora、openSUSE、CentOS、Debian 或 Ubuntu。支持 Yocto Project 的 Linux 发行版列表见参考手册的 受支持的 Linux 发行版 一节。 准备构建主机的详细信息见开发任务手册的 准备构建主机 一节。

• 确保以下工具满足最低版本要求：

  • Git 2.22.0 或更高版本

  • tar 1.28 或更高版本

  • Python 3.9.0 或更高版本

  • gcc 10.1 或更高版本

  • GNU make 4.0 或更高版本

如果构建主机未满足上述全部版本要求，仍可以通过准备系统来使用 Yocto Project。 相关方法见参考手册的 所需的 Git、tar、Python、make 和 gcc 版本 一节。

构建主机软件包

在运行受支持的 Ubuntu 或 Debian Linux 发行版的无图形界面系统上， 构建镜像需要以下软件包：

sudo apt-get install build-essential chrpath cpio debianutils diffstat file gawk gcc git iputils-ping libacl1 libcrypt-dev locales python3 python3-git python3-jinja2 python3-pexpect python3-pip python3-subunit socat texinfo unzip wget xz-utils zstd

还需要确保已启用 en_US.UTF-8 区域设置:

$ locale --all-locales | grep en_US.utf8

如果尚未启用，可以重新配置 locales 软件包以添加它 （需要交互式 shell）:

$ sudo dpkg-reconfigure locales

备注

• 在非交互式 shell 中，dpkg-reconfigure 无法按预期工作。 要添加此区域设置，需要编辑 /etc/locale.gen 文件，添加 en_US.UTF-8 条目或取消该条目的注释。 一种简单的方法是以 root 身份执行:

  $ echo "en_US.UTF-8 UTF-8" >> /etc/locale.gen
  $ locale-gen
  

• 如果构建系统安装了 oss4-dev 软件包，QEMU 构建可能失败， 原因是该软件包在 Debian 系统中安装了它自己定制的 /usr/include/linux/soundcard.h。遇到这种情况时， 请尝试以下任一种解决方法:

  $ sudo apt build-dep qemu
  $ sudo apt remove oss4-dev
  

备注

所有受支持 Linux 发行版的主机软件包要求，见 Yocto Project 参考手册的 构建主机所需的软件包 一节。

安装并使用 bitbake-setup

完成机器设置后，需要获取 bitbake-setup 工具，以便在 build host 上设置 Poky 参考发行版。使用以下命令在 Python 虚拟环境 中安装该工具：

$ python3 -m venv --clear ./bitbake-setup-venv
$ . ./bitbake-setup-venv/bin/activate
$ pip install bitbake-setup

备注

bitbake-setup 工具在 BitBake 仓库中开发和维护，因此也可以 直接从该仓库使用：

$ git clone https://git.openembedded.org/bitbake ./bitbake
$ ./bitbake/bin/bitbake-setup ...

使用以下命令设置构建环境：

$ bitbake-setup init

默认情况下，这会在当前目录中设置顶层目录。

如果希望在其他顶层目录（例如 $HOME/bitbake-builds ）中设置构建， 可以通过 bitbake-setup settings 命令指定：

$ bitbake-setup settings set --global default top-dir-prefix $HOME

备注

使用 bitbake-setup settings list 可查看设置概览。

bitbake-setup init 默认以交互方式运行，会要求你作出 一些选择。根据回答不同，输出可能与以下示例不同。

1. 选择配置，例如 poky-master：

   Available Configuration Templates:
   1. oe-nodistro-master   OpenEmbedded - 'nodistro' basic configuration
   2. oe-nodistro-blacksail  OpenEmbedded - 'nodistro' basic configuration, release 6.1 'blacksail' (supported until ...)
   3. poky-master          Poky - The Yocto Project testing distribution configurations and hardware test platforms
   4. poky-blacksail         Poky - The Yocto Project testing distribution configurations and hardware test platforms, release 6.1 'blacksail' (supported until ...)
   
   Please select one of the above configurations by its number: 3
   

   根据上述选择，可能还会提示新的选项，以进一步确定配置。例如：

   Available bitbake configurations:
   1. poky              Poky - The Yocto Project testing distribution
   2. poky-with-sstate  Poky - The Yocto Project testing distribution with internet sstate acceleration. Use with caution as it requires a completely robust local network with sufficient bandwidth.
   
   Please select one of the above bitbake configurations by its number: 1
   

2. 选择目标 MACHINE，例如 qemux86-64：

   Target machines:
   1. machine/qemux86-64     x86-64 system on QEMU
   2. machine/qemuarm64      ARMv8 system on QEMU
   3. machine/qemuriscv64    RISC-V system on QEMU
   4. machine/genericarm64   Arm64 SystemReady IR/ES platforms
   5. machine/genericx86-64  x86_64 (64-bit) PCs and servers
   
   Please select one of the above options by its number: 1
   

3. 选择 DISTRO，例如 poky：

   Target distributions:
   1. distro/poky         Yocto Project Reference Distro
   2. distro/poky-altcfg  Poky alternative with systemd as init manager
   3. distro/poky-tiny    Poky alternative optimized for size
   
   Please select one of the above options by its number: 1
   

4. 选择 setup 的目录名称：

   Enter setup directory name: [poky-master]
   

   按 Enter 使用方括号中的默认值，或输入自定义目录名称。

备注

如果希望非交互运行，可执行类似以下命令：

$ bitbake-setup init --non-interactive poky-master poky distro/poky machine/qemux86-64

init 命令会在 top directory 中创建新的 Setup。默认名称由上面选择的配置派生。

对于上例选择的选项，名称为：

poky-master

后续各节将使用此示例配置。

该目录包含：

• 名为 build 的 BitBake Build 目录。构建完成后，此 目录包含构建期间创建的所有文件。

  此目录还包含 README，说明当前配置并提供一些操作指引。

• layers 目录，包含构建 Poky 参考发行版所需的 层。

• config 目录，保存此 setup 当前使用的配置。

备注

也可以手动设置 Poky 参考发行版。参阅 Yocto Project 开发任务手册的 手动设置 Poky 参考发行版 一节。

构建镜像

按以下步骤构建镜像。构建过程会从源码创建完整的 Linux 发行版，包括工具链。

备注

• 如果位于防火墙后方，且构建主机未设置代理，获取源码时可能遇到构建问题， 例如获取器失败或 Git 失败。

• 如果不知道代理设置，请向本地网络基础设施管理方咨询。也可以先检查 Web 浏览器设置。更多信息见 Yocto Project Wiki 的 “在网络代理后工作” 页面。

1. 初始化构建环境： 在当前 Shell 中加载 BitBake build 目录下的 init-build-env 环境设置脚本， 在主机上设置 BitBake 构建环境：

   $ source poky-master/build/init-build-env
   Poky reference distro build
   

2. 检查当前配置： 设置构建环境时，BitBake build 目录 的 conf/ 子目录中会出现名为 toolcfg.conf 的配置文件。 bitbake-config-build 命令行工具会自动修改此文件。使用该工具列出 当前启用的 配置片段：

   $ bitbake-config-build list-fragments
   

   此配置默认使用两个 内置片段：

   • distro/poky 将 DISTRO 设为 Poky （ distro/ 片段）。

   • machine/qemux86-64 将 MACHINE 设为 qemux86-64 （ machine/ 片段）。

   这些片段值对应运行 bitbake-setup init 时所作的选择。

   备注

   这些片段设置的环境与过去使用本地配置文件 local.conf 时类似，而现在该 文件基本为空。要按过去的方式设置构建，参阅 Yocto Project 开发任务 手册的 手动设置 Poky 参考发行版 一节。

   当前配置不允许 root 用户登录。开发时可能需要这种能力，可启用 core/yocto/root-login-with-empty-password 片段：

   $ bitbake-config-build enable-fragment core/yocto/root-login-with-empty-password
   

   备注

   使用 共享状态缓存 镜像站并启用 哈希等价，可显著加快构建， 并减少获取器失败的影响。这样可直接使用预构建产物，无需重新构建。 只有网络和所用服务器下载产物的速度快于本地构建时，这种方式才有意义。

   要使用此类镜像站，请启用 core/yocto/sstate-mirror-cdn 片段:

   $ bitbake-config-build enable-fragment core/yocto/sstate-mirror-cdn
   

   哈希等价服务器需要 9.1 或更高版本的 Python websockets 模块。 Debian GNU/Linux 12（Bookworm）及更高版本、Fedora、CentOS Stream 9 及更高版本、Ubuntu 22.04（LTS）及更高版本都提供足够新的软件包。其他 受支持发行版需要通过软件包源之外的渠道获取该模块，例如 pip。 也可以按 Yocto Project 参考手册 所需的 Git、tar、Python、make 和 gcc 版本 一节安装 Buildtools 归档包。

3. 开始构建： 运行以下命令，为目标构建操作系统镜像；本例使用 core-image-sato：

   $ bitbake core-image-sato
   

   bitbake 命令的用法见 Yocto Project 概述与概念手册的 BitBake 一节，或 BitBake 用户手册的 The BitBake Command。

4. 使用 QEMU 模拟镜像： 此镜像构建完成后，可以启动 Yocto Project 附带的快速模拟器 QEMU（Quick EMUlator）：

   $ runqemu snapshot
   

   更多 QEMU 运行信息见 Yocto Project 开发任务手册的 使用快速模拟器（QEMU） 一章。

5. 退出 QEMU： 点击关机图标，或在启动 QEMU 的终端窗口中输入 Ctrl-C。

为特定硬件定制构建

目前只是快速构建了一个适用于模拟环境的镜像。本节介绍如何向 Yocto Project 开发环境添加硬件层，为特定硬件定制构建。

通常，层是包含相关指令和配置集合的仓库，用于告诉 Yocto Project 应执行 哪些操作。将相关元数据隔离到按功能划分的层，有助于模块化开发，也更便于 复用层元数据。

备注

按惯例，层名称以 "meta-" 开头。

按以下步骤添加 BSP 层：

1. 查找层： 有许多 BSP 层可供使用，可通过 层索引 查找。本例添加 meta-raspberrypi BSP 层。

   首先，将该层克隆到其他层旁边:

   git clone -b blacksail https://git.yoctoproject.org/meta-raspberrypi ../layers/meta-raspberrypi
   

2. 将层加入层配置文件： 使用之前，必须将该层及其依赖加入 Build Directory 的 conf/ 目录中的 build/conf/bblayers.conf 文件。

   可以使用 bitbake-layers add-layer 命令：

   $ bitbake-layers add-layer ../layers/meta-raspberrypi
   

   添加层的更多信息见 使用 bitbake-layers 脚本添加层 一节。

3. 修改配置以面向特定机器构建： MACHINE 变量由 machine/ 片段定义。本例中， meta-raspberrypi 层提供 raspberrypi5 机器，通过 bitbake-config-build 将其设为构建使用的 MACHINE：

   $ bitbake-config-build enable-fragment machine/raspberrypi5
   

   备注

   构建配置的更多信息见前面的“检查当前配置”步骤。

   raspberrypi5 构建依赖包含 Synaptics 许可证的非自由固件 （https://github.com/RPi-Distro/firmware-nonfree）。更多信息见 ipcompliance.md 文档。在构建目录的 build/conf/local.conf 文件中，为 LICENSE_FLAGS_ACCEPTED 变量添加 synaptics-killswitch 值:

   LICENSE_FLAGS_ACCEPTED = "synaptics-killswitch"
   

4. 开始构建： 现在已配置为面向 Raspberry Pi 5 构建。再次启动构建：

   $ bitbake core-image-sato
   

完成以上步骤后，meta-raspberrypi 层已加入 Yocto Project 开发环境， 并配置为面向 raspberrypi5 机器构建。

备注

上述步骤仅用于演示。实际尝试为 raspberrypi5 机器构建镜像前，应阅读 meta-raspberrypi 中的 README.md 文件。

创建自己的通用层

如果有应用程序或一组特定行为需要隔离，可以用 bitbake-layers create-layer 命令创建自己的通用层。该工具自动创建层目录，其中包含 layer.conf 配置 文件、带有 example.bb 配方的 recipes-example 子目录、许可证文件 以及 README。

以下命令调用该工具，创建名为 meta-mylayer 的层：

$ bitbake-layers create-layer ../layers/meta-mylayer
NOTE: Starting bitbake server...
Add your new layer with 'bitbake-layers add-layer ../layers/meta-mylayer'

备注

按惯例，各层并列存放。

关于层及其创建方法的更多信息，见 Yocto Project 开发任务手册的 创建自己的层 一节。

下一步

体验过 Yocto Project 后，你可能会想接下来做什么。Yocto Project 提供了 网站、Wiki 页面、用户手册等多种信息来源：

• 网站： Yocto Project 网站 提供背景信息、最新构建、 最新消息、完整的开发文档，以及参与活跃的 Yocto Project 开发社区的入口。

• 视频讲座： Yocto Project 与 BitBake 入门，第 1 部分 和 Yocto Project 与 BitBake 入门，第 2 部分 介绍了使用 Yocto Project 开发定制嵌入式 Linux 发行版时最重要的内容。

• Yocto Project 概述与概念手册： Yocto Project 概述与概念手册 是了解 Yocto Project 的良好起点，介绍项目及其开发环境，并解释项目各方面的概念。

• Yocto Project Wiki： Yocto Project Wiki 提供进阶 学习方向、发行信息、项目规划和质量保证等补充信息。

• Yocto Project 邮件列表： 相关邮件列表用于讨论、提交补丁和发布公告， 按主题划分为多个列表。完整列表见 Yocto Project 参考手册的 邮件列表 一节。

• 完整链接及其他文档列表： Yocto Project 参考手册的 链接与相关文档 一节提供了 所有相关链接和其他用户文档的完整列表。

---

Yocto 项目中文文档

<docs@lists.yoctoproject.org>

允许按照 Creative Commons 发布的 知识共享署名—相同方式共享 2.0 英国：英格兰及威尔士许可 条款复制、分发和／或修改本文档。

如发现本手册或其他 Yocto 项目手册存在不准确之处或问题，或希望提交补充和修改， 请向 Yocto 项目文档邮件列表 docs@lists.yoctoproject.org 发送邮件或补丁， 也可以加入 Libera Chat 的 #yocto 频道。