1. BitBake 的 do_fetch 不是「下载一下」那么简单
BitBake 属于典型的代码开发工具:它自己不编译一行代码,却决定了代码从哪来、解到哪个目录、被哪套架构的构建复用。很多人第一次碰 Yocto,注意力全在配方语法上,直到某次 bitbake -c unpack 跑完,去 build/tmp/work 底下翻半天找不到源码,才发现 fetch 和 unpack 这两个任务背后的目录规则和变量关系,才是真正卡人的地方。下面按「先看清目录底座、再手动跑一遍 fetch 与 unpack、最后把变量取值和常见现象对上号」的顺序写。适合已经在跑 BitBake、但还没把 TMPDIR、WORKDIR、PN、PV 这条链路理顺的人,也适合接手别人构建目录、需要快速定位源码落在哪的人。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 从 parse 到 do_fetch:源码落地前 BitBake 已经定好三件事
2.1 目录底座:TMPDIR 之下按包架构和机器分两套层次
OpenEmbedded 构建系统执行所有工作的基目录由 TMPDIR 决定,默认就是构建目录下的 tmp。这个值不写在某个配方里,而是由构建配置拼出来的,所以想确认当前构建到底把东西扔哪了,最稳的办法是让 BitBake 自己把展开后的环境吐出来,而不是去翻配置文件猜。
bash复制# 展开 demoapp 这个 recipe 的完整环境变量,只保留 TMPDIR 这一行
bitbake -e demoapp | grep ^TMPDIR
# 典型输出
TMPDIR="/home/dev/build/tmp"
-e 的含义是把配方解析完之后的环境完整展开,包含所有变量、追加、覆盖的最终结果。^TMPDIR 前面的 ^ 是锚定行首,这一点很关键:BitBake 的展开输出里会出现不少名字以 TMPDIR 开头或包含 TMPDIR 的派生变量与注释行,不加锚定你会 grep 出一屏无关内容,然后误以为自己看到了好几个不同的值。后面那个 recipe 名要和 PN 一致,名字敲错时 -e 直接失败,输出为空,新手很容易把「没输出」当成「变量未定义」。
真正要留心的是 TMPDIR 下面那层目录结构。这里存在两种层次:一种基于包架构(PACKAGE_ARCH),一种基于机器(MACHINE)。两者的基础结构是相同的,区别只在于你把什么当作构建目标——通用架构、构建主机、SDK,还是某一台具体机器。这意味着同一份配方在不同 MACHINE 下会落到 work 下不同的子目录里,源码、解包产物、临时文件各有一套。我第一次排查「源码找不到」的问题,就是因为默认以为 work 底下只有一份 demoapp 目录,实际按当前 MACHINE 分了好几份,翻错了那棵树。
2.2 do_fetch 与 do_unpack 各管一段,别混着看
do_fetch 任务负责下载或者读取源文件。注意「读取」这两个字:来源不一定是远端仓库,也可能是本地目录或归档文件,具体走哪条路径由配方里的源地址声明决定。do_fetch 只负责把东西弄到本地缓存,它不管解压、不管打补丁、更不管编译。
do_unpack 任务负责把取回来的源文件解压到 build/tmp/work/ 下面相应的目录。这一步才是源码真正出现在 WORKDIR 里的时刻。很多人把「源码没出现」归咎于网络,其实 do_fetch 早就成功了,卡住的是 unpack 之后的目标目录不对,或者 unpack 根本被跳过。
理解这条边界有个直接好处:出错时能立刻判断该看哪一段。如果是取不到,看源地址声明和本地缓存;如果是取到了但目录里空空,看 WORKDIR 的取值和 unpack 的执行结果。两者混在一起排查,时间全浪费在互相怀疑上。
还有一层前置条件常被忽略:do_fetch 之前,BitBake 要先完成配方解析、依赖关系梳理和共享状态检查。也就是说 fetch 之前已经有一批任务跑过了,日志里前面那些行不是噪音,配方解析报错、依赖缺失这类问题都会在 fetch 之前暴露出来。看到 fetch 失败先别急着怀疑网络,往上翻日志,很多时候是更早的阶段就已经断了。
2.3 手动复现:把两个任务单独拎出来跑
验证目录规则的唯一办法是亲手跑一遍,而且只跑这两个任务,不要一上来就整个镜像构建,那会把时间全花在编译上。
bash复制# 1. 只执行取源任务,观察源码被放到哪里
bitbake -c fetch demoapp
# 2. 只执行解包任务,观察 work 目录下的产物
bitbake -c unpack demoapp
-c 用来指定要执行到哪个任务。这里要建立一个正确预期:-c 不是「只跑这一个任务」,任务之间的依赖关系照样成立。所以 bitbake -c unpack demoapp 会先把 fetch 及其前置任务补完,再执行 unpack。第一次跑和第二次跑的耗时差别很大,第二次大量任务命中缓存直接跳过,如果你用耗时来判断「有没有真的执行」,很容易得出相反结论。
跑完之后不要凭记忆去猜路径,直接从变量里取:
bash复制# 拿到当前 recipe 的构建目录,再进去看
WORKDIR=$(bitbake -e demoapp | grep ^WORKDIR= | cut -d'"' -f2)
ls "$WORKDIR"
cut -d'"' -f2 是把 WORKDIR="..." 这行里的引号内容切出来。这个写法依赖输出格式稳定,所以一定要带 ^WORKDIR= 锚定,否则可能切到别的变量的引号内容,得到一个看起来像路径、实际不存在的字符串——这种错误最难查,因为 ls 只会告诉你目录不存在,不会告诉你路径是从哪来的。
3. 用 bitbake -e 摸清变量:PN、PV、PR、WORKDIR 到底谁决定谁
3.1 -e 输出的是展开后的结果,不是配方原文
先纠正一个高频误解:bitbake -e 打印的不是配方文件的内容,而是解析、继承、追加、覆盖全部完成之后的最终环境。配方里写的是 PV = "1.0+git${SRCPV}" 这种形式,你看到的却是展开后的完整字符串。这个区别决定了排查思路——不要去配方文件里逐行对照找「为什么值不对」,因为值可能是从别的配置、别的继承层追加进来的,配方里根本看不到。
正因为是展开后的结果,输出会非常长,直接重定向到文件里再查比在终端里翻要靠谱得多。查的时候务必用「变量名 + 等号 + 行首锚定」三件套,例如 ^PV=,不要只写 PV,否则你会同时命中 PV、PV_append、注释里提到的 PV,最后不知道该信哪一条。
3.2 五条 grep 把整条链路串起来
把关键变量一次性抓出来,比一个一个试快得多:
bash复制# 一次性抓取 fetch/unpack 相关的核心变量
bitbake -e demoapp | grep -E '^(TMPDIR|TARGET_OS|PN|PV|PR|WORKDIR)='
典型输出大致是这样:
text复制TMPDIR="/home/dev/build/tmp"
TARGET_OS="linux"
PN="demoapp"
PV="1.0+gitAUTOINC+cac0e57e2f"
PR="r0"
WORKDIR="/home/dev/build/tmp/work/core2-64-linux/demoapp/1.0+gitAUTOINC+cac0e57e2f-r0"
现在把这条链路读一遍就清楚了。TMPDIR 是所有工作的基目录,它构成 WORKDIR 的前缀。往下一层 core2-64-linux 是目标架构与系统的组合段,其中后半段与 TARGET_OS 的取值是对得上的,TARGET_OS 表示目标设备的操作系统,典型值就是 linux。再往下一层 demoapp 就是 PN,也就是配方名。最末一层 1.0+gitAUTOINC+cac0e57e2f-r0 是 PV 加 PR 拼起来的:PV 是配方版本,PR 是配方修订号,默认 r0,所以路径末尾那个 -r0 并不是随机后缀。
这里有个容易被忽略的细节:PV 里带 AUTOINC 和一个哈希值时,说明版本号里嵌了源码版本信息。源码分支的 HEAD 一变,这个哈希就变,PV 跟着变,WORKDIR 的名字整个跟着变。这个机制本身是合理的,它保证不同源码版本不会互相污染,但对排查的人来说是个陷阱——昨天还在的目录,今天换了个名字,你以为东西被删了,其实只是路径变了。
3.3 一次导出、多次查询的抓取脚本
反复调 bitbake -e 代价不小,尤其是配方依赖多的时候。更省事的做法是导出一份环境快照,后续所有查询都对着文件做:
bash复制#!/usr/bin/env bash
# 用法: ./dump_env.sh demoapp
recipe="$1"
out="${recipe}_env.txt"
# 只跑一次解析,把完整环境落盘
bitbake -e "$recipe" > "$out" || { echo "解析失败,先看 $out"; exit 1; }
# 逐个变量精确取值,-m1 只取第一条,找不到时给出明确提示
for v in TMPDIR TARGET_OS PN PV PR WORKDIR; do
grep -m1 "^${v}=" "$out" || echo "${v}=<未定义>"
done
几个参数值得说明。-m1 表示匹配到第一条就停,避免同名变量出现多次时把整段输出都打出来。^${v}= 里的等号不能省,否则 PV 会匹配到 PV_append 之类的派生变量。|| echo "${v}=<未定义>" 是给「变量在这份快照里压根不存在」这种情况一个明确出口——比什么都不打印强,因为空输出和变量为空值在肉眼看来是一样的,但原因完全不同。最后那个 exit 1 也不是摆设:解析失败时快照文件可能是空的或只有报错,如果继续往下 grep,你会得到一串「未定义」,然后误判成配置问题。
我一般会把这份快照连同当次的修改一起留着。配方改完之后再导一份,两份一 diff,PV、PR、WORKDIR 有没有变一目了然,比凭记忆回忆「上次是什么值」可靠得多。
4. unpack 之后找不到源码:四类现象与排查
4.1 现象:WORKDIR 指向的目录根本不存在
这是最常见的一类。命令跑完没报错,ls 却说目录不存在,第一反应往往是「unpack 失败了」,但实际可能是路径本身就是错的。
原因通常有三种:一是拿的是旧快照里的 WORKDIR,中间改过 MACHINE 或配方版本,路径早就变了;二是从头到尾没跑过 unpack,work 下的目标目录还没被创建;三是 TMPDIR 被改过,比如换了构建目录,而查询用的还是老的构建环境。
解决办法是先对齐前缀,再判断:
bash复制# 先确认当前 TMPDIR 与 WORKDIR 的前缀是否一致
bitbake -e demoapp | grep -E '^(TMPDIR|WORKDIR)='
如果 WORKDIR 不是以当前 TMPDIR 开头,说明你查的和跑的不是同一套环境,先把构建目录切对。前缀一致但目录不存在,那就老老实实跑一次 bitbake -c unpack demoapp,再确认一次。别在目录不存在的情况下继续往下改配方,那是在错误的前提下做判断。
4.2 现象:昨天手动改过的文件,今天不见了
这个坑踩过的人不少,血泪经验基本都来自这里。表现是:明明在 work 下某个文件里加了几行调试代码,今天重新构建,改动没了。
原因是 PV 里嵌了源码版本信息。源码更新后 PV 变化,WORKDIR 的目录名整体变化,新目录是根据新源码解出来的干净副本,旧目录还在,只是名字不同,你打开的是新目录,自然看不到旧改动。
解决思路不是「找回那个文件」,而是改掉工作方式:任何需要保留的改动都不要放在 work 目录下。work 下的内容是构建产物,随 PV、PR 变化而被重建,把它当草稿纸用迟早翻车。临时验证可以,但验证完要么落成补丁文件、要么写进配方层的追加内容里,否则下次构建一定丢。如果只是想确认改动到底去哪了,先用快照对比两次的 WORKDIR,确认是不是路径变了,再决定要不要去旧目录里捞。
4.3 现象:切换 MACHINE 后,看着像复用了缓存但结果不对
表现比较隐晦:构建没报错,但产物行为和预期不一致,或者某些任务的日志显示被跳过。
原因在于 work 目录按架构和机器分成两套层次结构,基础结构虽然相同,但用不同目标构建时会落到不同子目录里。切换 MACHINE 之后,你看到的可能是另一棵树的内容,或者共享状态里已有对应任务的结果而被直接跳过。这时候「缓存命中」不等于「结果对应当前目标」。
解决方法是先明确当前目标再动手:
bash复制# 确认当前构建的机器与目标系统
bitbake -e demoapp | grep -E '^(MACHINE|TARGET_OS)='
把 MACHINE 和 WORKDIR 里的架构段对照一下,两者对不上就说明你在看错误的目录树。切换目标之后重新验证时,不要只看「跑得快不快」,要看关键任务的日志有没有真的执行。
4.4 现象:grep 出来一堆,或者一行都没有
两种极端,原因往往是同一个:匹配写得太宽松。不带 ^ 和 = 的 grep 会把注释、派生变量、帮助文本一起捞出来,输出几十行,你不知道该信哪个;而变量名写错、recipe 名写错、-e 本身失败时,又是一行都没有。
解决办法是固定查询模板:^变量名= 加 -m1,先看命令有没有正常退出,再看值。一行都没有时,先单独跑一次 bitbake -e demoapp | head,确认解析是否成功,再怀疑变量名。这个顺序能省掉大量「变量不存在」的误判——大多数时候变量好得很,只是查询姿势不对。
5. 把 fetch 与 unpack 固化成可复现的检查动作
排查到后面会发现,真正省时间的不是记住每个变量的含义,而是把「查环境」这件事变成一个固定动作。我的习惯是:任何一次要动配方的修改之前,先导一份环境快照;改完再导一份;两份 diff 一下,只看和源码位置相关的几个变量。
bash复制# 改配方前后各导一份,只看路径相关变量有没有漂移
bitbake -e demoapp > /tmp/env_before.txt
# ... 修改配方 ...
bitbake -e demoapp > /tmp/env_after.txt
diff /tmp/env_before.txt /tmp/env_after.txt | grep -E '(TMPDIR|PN|PV|PR|WORKDIR)='
这段的价值在于把「我觉得没变」换成「我看过确实没变」。PV 里带 AUTOINC 哈希时,改动的实际影响经常超出预期,diff 出来一眼就能看到 WORKDIR 整行变了,也就能提前预判哪些临时文件会失效。
回过头把几个变量的位置关系整理成一张表,查问题时对着看比逐个试要快:
| 变量 | 作用 | 在 WORKDIR 里的体现 |
|---|---|---|
| TMPDIR | 构建工作的基目录,默认 build/tmp | WORKDIR 的前缀部分 |
| TARGET_OS | 目标设备的操作系统,典型值 linux | 架构与系统组合段的后半 |
| PN | 用于构建包的配方名 | work 下的一级目录 |
| PV | 配方版本,含 AUTOINC 时随源码变化 | 末级目录中 -r0 之前的部分 |
| PR | 配方修订号,默认 r0 | 末级目录的 -r0 后缀 |
| WORKDIR | 构建该配方的位置 | 整体 |
再补一个具体的技巧:想确认某个源码文件到底是哪个任务放进去的,不要在整个构建日志里搜文件名,先定位 WORKDIR,再看这个目录的时间戳和内容结构——解包产物和补丁后的结果通常有明显层次,能反推出卡在了哪一步。如果目录里只有压缩包没有解开的树,问题在 unpack;如果连压缩包都没有,问题在 fetch 或更早的解析阶段。
从那以后我每次动配方之前,都强制先导一份环境快照再改,改完 diff 一遍才继续往下构建。这个动作多花不到一分钟,但省掉的往往是半小时的「东西怎么不见了」。希望帮到你。
