7 升级配方

上游开发者会不断为层中配方构建的软件发布新版本。建议及时更新配方，跟进上游版本。

升级配方有多种方法，但可以先使用 devtool check-upgrade-status 检查升级状态。更多信息见 Yocto Project 参考手册的 “检查配方的升级状态” 一节。

下文介绍三种升级方法：使用自动升级助手（AUH）自动升级版本，使用 devtool upgrade 半自动升级，或直接编辑配方手动升级。

7 使用自动升级助手（AUH）

AUH 与 OpenEmbedded 构建系统配合，根据上游发布的新版本自动生成配方升级。如果需要运行自动升级服务，并可选地通过邮件接收结果，可以使用 AUH。

AUH 一次可更新多个配方，还可选择使用镜像执行构建和集成测试，将结果保存到硬盘，并可选地向配方维护者发送结果邮件。AUH 还会在层的源码树中，为配方变更创建带有适当说明的 Git 提交。

备注

以下情况不应使用 AUH，而应使用 devtool upgrade 或手动升级：

AUH 无法完成升级流程，通常是配方携带的自定义补丁无法自动变基到新版本。此时 devtool upgrade 允许手动解决冲突。
需要更全面地控制升级过程，例如需要特殊测试安排。

设置 AUH 的步骤如下：

确保开发主机准备就绪： 主机需要能够使用 Yocto Project。设置方法见 “准备构建主机” 一节。
确保 Git 已配置： AUH 用 Git 保存升级，因此必须配置 Git 用户名和邮箱。以下命令显示配置:
```
$ git config --list
```
如果尚未配置，可以运行:
```
$ git config --global user.name some_name
$ git config --global user.email username@domain.com
```

克隆 AUH 仓库： 使用前需将仓库克隆到开发主机，以下命令创建本地副本:

$ git clone https://git.yoctoproject.org/auto-upgrade-helper
Cloning into 'auto-upgrade-helper'... remote: Counting objects: 768, done.
remote: Compressing objects: 100% (300/300), done.
remote: Total 768 (delta 499), reused 703 (delta 434)
Receiving objects: 100% (768/768), 191.47 KiB | 98.00 KiB/s, done.
Resolving deltas: 100% (499/499), done.
Checking connectivity... done.

AUH 不属于 OpenEmbedded-Core (OE-Core) 或 Poky 仓库。

创建专用构建目录： 用 bitbake-setup 创建新的 Setup，或手动运行 oe-init-build-env，创建只用于 AUH 的全新 Build Directory:
```
$ source layers/openembedded-core/oe-init-build-env your_AUH_build_directory
```
不建议复用已有 Build Directory 及其配置，已有设置可能导致 AUH 失败或产生不期望的行为。
配置本地配置文件： 在刚为 AUH 创建的构建目录中，修改 build/conf/local.conf，进行以下设置：
- 如需启用可选的构建历史，在 build/conf/local.conf 中添加:
```
INHERIT =+ "buildhistory"
BUILDHISTORY_COMMIT = "1"
```
  此配置下升级成功后，Build Directory 中会出现构建历史差异文件 upgrade-helper/work/recipe/buildhistory-diff.txt。
- 如需通过 testimage 类启用可选测试，在 build/conf/local.conf 中设置:
```
IMAGE_CLASSES += "testimage"
```
  备注
  
  Poky 默认启用 ptest。如果所用发行版没有默认启用，需在 build/conf/local.conf 中添加:
  DISTRO_FEATURES:append = " ptest"
按需启动 vncserver： 如果运行在没有 X11 会话的服务器上，需要启动 vncserver:
```
$ vncserver :1
$ export DISPLAY=:1
```
创建并编辑 AUH 配置文件： Build Directory 中需要有 upgrade-helper/upgrade-helper.conf。示例配置见 AUH 源码仓库。

通读示例并按需配置。例如，若此前在 build/conf/local.conf 启用了构建历史，还必须在 upgrade-helper.conf 中启用。

如果使用 OpenEmbedded-Core (OE-Core) 提供的默认 maintainers.inc，未在 upgrade-helper.conf 中设置 "maintainers_whitelist" 或 "global_maintainer_override"，又在 AUH 命令行使用 "-e all"，工具会自动向所有默认维护者发送邮件。请避免这种情况。

以下示例说明 AUH 的用法：

升级指定配方： 使用以下形式:
```
$ upgrade-helper.py recipe_name
```
例如，升级 xmodmap:
```
$ upgrade-helper.py xmodmap
```
将指定配方升级到特定版本： 使用以下形式:
```
$ upgrade-helper.py recipe_name -t version
```
例如，将 xmodmap 升级到 1.2.3:
```
$ upgrade-helper.py xmodmap -t 1.2.3
```
升级全部配方并禁止邮件通知： 将所有配方升级到最新版本且不发送邮件:
```
$ upgrade-helper.py all
```
升级全部配方并发送邮件通知： 将所有配方升级到最新版本，为每个尝试升级的配方向维护者发送邮件，并发送状态邮件:
```
$ upgrade-helper.py -e all
```

运行 AUH 后，可在其 Build Directory 中找到结果:

${BUILDDIR}/upgrade-helper/timestamp

AUH 还会在层的源码树中，为成功升级的配方创建更新提交。

可以使用 cron 作业定期运行 AUH。示例见工具附带的 weeklyjob.sh。

7 使用 `devtool upgrade`

另一种升级配方的方法是使用 devtool upgrade。一般介绍见 Yocto Project 应用程序开发与可扩展软件开发工具包（eSDK）手册的 “使用 devtool upgrade 创建支持新版软件的配方” 一节。

查看 devtool upgrade 的全部命令行选项:

$ devtool upgrade -h

如果只想查询配方的上游最新版本，而不尝试升级本地配方，使用:

$ devtool latest-version recipe_name

与前文所述 AUH 相比，devtool upgrade 自动化程度较低：只处理命令行指定的单个配方，不执行基于镜像的构建和集成测试，也不自动为源码树变更生成提交。不过，它会把配方更新到新的上游版本，并按需尝试将自定义补丁变基。

备注

AUH 内部大量使用 devtool upgrade，可以视为其包装应用。

典型场景是已经用 Git 克隆了构建所用的上游仓库。由于此前构建过配方，对应层很可能已加入配置。如果没有，可以使用 “bitbake-layers” 添加。例如，使用 meta-openembedded 仓库中 meta-oe 层的 nano.bb，假定仓库已克隆到:

/home/scottrif/bitbake-builds/layers/meta-openembedded

在 Build Directory 运行以下命令，将层加入构建配置 ${BUILDDIR}/conf/bblayers.conf:

$ bitbake-layers add-layer /home/scottrif/bitbake-builds/layers/meta-openembedded/meta-oe
NOTE: Starting bitbake server...
Parsing recipes: 100% |##########################################| Time: 0:00:55
Parsing of 1431 .bb files complete (0 cached, 1431 parsed). 2040 targets, 56 skipped, 0 masked, 0 errors.
Removing 12 recipes from the x86_64 sysroot: 100% |##############| Time: 0:00:00
Removing 1 recipes from the x86_64_i586 sysroot: 100% |##########| Time: 0:00:00
Removing 5 recipes from the i586 sysroot: 100% |#################| Time: 0:00:00
Removing 5 recipes from the qemux86 sysroot: 100% |##############| Time: 0:00:00

假设上游 nano.bb 版本为 2.9.3，本地版本为 2.7.4。在构建目录运行以下命令，即可自动升级配方:

$ devtool upgrade nano -V 2.9.3
NOTE: Starting bitbake server...
NOTE: Creating workspace layer in /home/scottrif/bitbake-builds/build/workspace
Parsing recipes: 100% |##########################################| Time: 0:00:46
Parsing of 1431 .bb files complete (0 cached, 1431 parsed). 2040 targets, 56 skipped, 0 masked, 0 errors.
NOTE: Extracting current version source...
NOTE: Resolving any missing task queue dependencies
       .
       .
       .
NOTE: Executing SetScene Tasks
NOTE: Executing RunQueue Tasks
NOTE: Tasks Summary: Attempted 74 tasks of which 72 didn't need to be rerun and all succeeded.
Adding changed files: 100% |#####################################| Time: 0:00:00
NOTE: Upgraded source extracted to /home/scottrif/bitbake-builds/build/workspace/sources/nano
NOTE: New recipe is /home/scottrif/bitbake-builds/build/workspace/recipes/nano/nano_2.9.3.bb

备注

-V 不是必需的。省略版本号时，devtool upgrade 会升级到最新版本。

随后可以通过 devtool build 构建刚升级的配方:

$ devtool build nano
NOTE: Starting bitbake server...
Loading cache: 100% |################################################################################################| Time: 0:00:01
Loaded 2040 entries from dependency cache.
Parsing recipes: 100% |##############################################################################################| Time: 0:00:00
Parsing of 1432 .bb files complete (1431 cached, 1 parsed). 2041 targets, 56 skipped, 0 masked, 0 errors.
NOTE: Resolving any missing task queue dependencies
       .
       .
       .
NOTE: Executing SetScene Tasks
NOTE: Executing RunQueue Tasks
NOTE: nano: compiling from external source tree /home/scottrif/bitbake-builds/build/workspace/sources/nano
NOTE: Tasks Summary: Attempted 520 tasks of which 304 didn't need to be rerun and all succeeded.

在 devtool upgrade 流程中，可以部署并测试重新构建的软件。本例接着使用 devtool finish，在工作区源码树干净后清理工作区。这通常需要先用 Git 暂存并提交升级过程产生的变更。

源码树干净后，在 ${BUILDDIR}/workspace/sources/nano 中运行以下命令完成本例的清理:

$ devtool finish nano meta-oe
NOTE: Starting bitbake server...
Loading cache: 100% |################################################################################################| Time: 0:00:00
Loaded 2040 entries from dependency cache.
Parsing recipes: 100% |##############################################################################################| Time: 0:00:01
Parsing of 1432 .bb files complete (1431 cached, 1 parsed). 2041 targets, 56 skipped, 0 masked, 0 errors.
NOTE: Adding new patch 0001-nano.bb-Stuff-I-changed-when-upgrading-nano.bb.patch
NOTE: Updating recipe nano_2.9.3.bb
NOTE: Removing file /home/scottrif/bitbake-builds/layers/meta-openembedded/meta-oe/recipes-support/nano/nano_2.7.4.bb
NOTE: Moving recipe file to /home/scottrif/bitbake-builds/layers/meta-openembedded/meta-oe/recipes-support/nano
NOTE: Leaving source tree /home/scottrif/bitbake-builds/build/workspace/sources/nano as-is; if you no longer need it then please delete it manually

devtool finish 清理工作区，并根据提交创建补丁文件。本例将所有补丁放回源码目录下名为 nano 的子目录。

7 手动升级配方

如果不选择使用自动升级助手（AUH）或使用 devtool upgrade，也可以手动编辑配方文件以升级版本。

备注

手动更新多个配方效率较低，涉及步骤很多。建议使用 AUH 或 devtool upgrade，它们能自动完成部分步骤，并为仍需手动处理的步骤提供指导。

手动升级的一般步骤如下：

修改版本： 重命名配方，适当修改名称中的版本，即 PV 部分。如果版本不在文件名中，则修改配方内部设置的 PV。
按需更新 SRCREV：如果源码来自 Git 或其他版本控制系统，将 SRCREV 更新为与新版本对应的提交哈希。
构建软件： 尝试用 BitBake 构建。常见失败包括：
- 新版本更新了许可证声明。需要审阅许可证变化，并按需更新 LICENSE 和 LIC_FILES_CHKSUM。
  
  备注
  
  许可证变化往往不影响实际条款，例如仅更新版权年份。
- 旧配方携带的自定义补丁无法应用到新版本。需要检查失败原因；如果新版已修复相关问题，补丁可能不再需要。如果仍需补丁，则将其变基到新版本。
按需尝试多个架构： 某个架构构建成功后，可以修改 MACHINE 并重新构建，测试其他架构。如果配方要公开发布，这一步尤其重要。
检查上游变更日志或发行说明： 确认是否有破坏向后兼容性的新功能，若有则采取措施缓解或消除影响。
按需创建可启动镜像并测试： 可以将新软件启动到实际硬件上测试。
在层仓库提交变更： 所有构建和测试成功后，为包含升级配方的层中的变更创建提交。

7 升级配方

7 使用自动升级助手（AUH）

7 使用 devtool upgrade

7 手动升级配方

7 使用 `devtool upgrade`