目录
[放进 recipe:目录约定与 SRC_URI](#放进 recipe:目录约定与 SRC_URI)
[上下文漂移:git am 失败之后怎么办](#上下文漂移:git am 失败之后怎么办)
什么时候该做补丁
只要改动落在"上游源码文件"上(C 源码、头文件、Makefile、设备树、配置模板),就应该做成补丁;如果只需要改配方的变量、追加文件、加编译选项,用 bbappend 即可,不必碰补丁。判断标准很简单:改动最终要出现在"别人 recipe 解出来的源码树"里,就是补丁;只改变 recipe 自身行为,就是 bbappend。
表1-1
|---------------------------------|------------|--------------------|-------------------------------|
| 改动类型 | 采用方式 | 落点 | 本项目实例 |
| 改配方的变量 / 追加文件 / 编译选项 | bbappend | meta 层同名 .bbappend | ebmc.cfg 追加 CONFIG_EXAMPLES=y |
| 改上游 C 源码 / 头文件 / Makefile / dts | 补丁(.patch) | recipe 同名子目录 | 0009 修复 macb warm reset 网络挂死 |

图 1-1 Yocto 补丁工作流:源码改动 → patch 文件 → recipe 自动应用
三种生成补丁的方式
|----------------------|------------------|----------------------------------------|-------------------------------------|
| 方式 | 适用场景 | 关键命令 | 特点 |
| git format-patch(推荐) | 源码本身是 git 仓库 | git commit 后 git format-patch -1 | 自带作者/日期/完整提交说明,可 git am 重新应用 |
| diff -Nur | tar 包解出、非 git 源码 | diff -Nur 原目录 新目录 > 0001-xxx.patch | 简单直接,需手工补头部;-N 才能包含新增文件 |
| quilt | 多补丁并行、频繁刷新 | quilt new / add / refresh / push / pop | Yocto do_patch 的内部实现就是 quilt,逐层栈式管理 |
bash
git format-patch 的标准操作(源码是 git 仓库时):
cd 源码目录
git add 改动的文件
git commit -m "arm64: dts: add phytium e2000 bmc device tree"
git format-patch -1 # 导出最近一次提交为 0001-xxx.patch
git format-patch --root -1 # 需要导出"新增文件"的完整补丁时用 --root
diff -Nur 用于源码不是 git 仓库(或是 tar 包)的场景,用两份目录做差:
diff -Nur 原始目录 修改后目录 改动文件路径 > 0001-xxx.patch
quilt 的价值在"多补丁栈式管理"。它把补丁组织成一个栈:push 逐个应用、pop 逐个撤销、refresh 把工作区改动固化回栈顶补丁。典型操作流:
quilt new 0003-qspi-update-tool.patch # 在补丁系列顶部新建补丁
quilt add drivers/spi/phytium_qspi.c # 声明该文件归当前补丁管
...修改文件...
quilt refresh # 把改动固化进当前补丁
quilt push / quilt pop # 应用/撤销栈顶补丁
quilt series # 列出全部补丁及当前栈顶
与 Yocto 的关系要特别说明:bitbake 执行 do_patch 时,workdir 下的 patches/ 目录与 quilt 系列命令就是补丁落地的现场------进入 devshell 后可以直接用 quilt push/pop/refresh 调试补丁上下文,改完 refresh 后退出,do_patch 即可复现同样结果。这也是排查"补丁在本地能打、bitbake 里打不上"这类问题的标准手段。
放进 recipe:目录约定与 SRC_URI
补丁一般放在与配方同名的子目录里:
bash
recipes-bsp/u-boot/u-boot-phytium-sdk.bbappend
recipes-bsp/u-boot/u-boot-phytium-sdk/
0001-arm64-dts-add-phytium-e2000-bmc-device-tree-source.patch
0002-...patch
再由 bbappend 声明文件搜索路径并追加到 SRC_URI:
FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:"
SRC_URI:append:ebmc = " \
file://0001-arm64-dts-add-phytium-e2000-bmc-device-tree-source.patch \
file://0002-...patch \
"
补丁顺序是有语义的:SRC_URI 里的补丁按出现顺序依次应用------例如如果 0004 把设备树里的 lpc_snoop 改名为 snoop,而 0007 新增的 dts 引用了 snoop,那么 0007 必须排在 0004 之后,否则打补丁阶段就会因为引用不存在而失败。
上下文漂移:git am 失败之后怎么办
上游文件变动会导致 hunk 上下文对不上,典型报错是 patch does not apply。实测遇到的一次是补丁改的是 MAINTAINERS,而上游恰好在该文件头部新增了条目,前几行上下文全部变化。
处理顺序:先中止,再退回 patch 命令带模糊匹配:
bash
git am --abort
git checkout -- . patch -p1 --forward --fuzz=3 --no-backup-if-mismatch -i 0004-xxx.patch
三个参数各有作用:--forward 跳过已应用的 hunk;--fuzz=3 允许最多 3 行上下文偏移;--no-backup-if-mismatch 避免留下 .orig 备份。即便如此仍可能残留个别失败文件,需要手工合并 .rej。
另一个坑:打完补丁提交时不要用 git add -A。内核源码目录里常有 .config.baseline、.kernel-meta 之类的构建产物,一把梭会把它们塞进补丁提交。正确做法是只提交补丁涉及的文件:
git add -- 文件1 文件2 文件3
这也是 devtool-sync 脚本内部的做法:先解析补丁的 diff --git / --- / +++ 行得到目标文件列表,再按列表 add。
版本迭代时的补丁维护
新增补丁沿用连续编号,放在同一目录,文件名带上前缀保持可读(0001-、0002-...)。基线升级后补丁上下文会漂移,此时不要直接改 .patch 文本,而是重新解源码、合入改动、重新生成补丁(devtool modify 后再 devtool update-recipe 是最省事的方式)。已经合入上游的补丁要及时删除,否则要么报 already exists! Skipping,要么在判断"是否已应用"时被误判。改动多个包时,先跑一遍 devtool update-recipe -N 干跑,确认没有意外的补丁导出。
自检清单
补丁文件名与 SRC_URI 中的引用完全一致,且子目录在 FILESEXTRAPATHS 覆盖范围内。
补丁顺序与依赖关系一致(先改名、后引用)。
补丁里不含构建产物、备份文件(.orig/.rej/.config 等)。
补丁头部保留完整的 From/Date/Subject,便于后续 refresh 与追溯。
新增文件类补丁用 git format-patch --root 生成,不要用 diff -Nur 手工拼。