4. Recipe文件结构

在 Yocto 项目中，.bb 文件是 BitBake 的核心构建描述文件，它定义了一个软件包从哪里获取源码、如何配置编译、安装哪些文件、依赖哪些组件，以及最终生成什么包。理解 .bb 文件的基本语法，是编写可维护 Recipe 的第一步。本节围绕变量赋值、操作符、注释规范和一个最小可运行 Recipe 展开，帮助建立对 Recipe 文件结构的整体认知。

一、.bb 文件的基本组成

一个典型的 .bb 文件通常由若干逻辑区域组成：文件头注释、基础元数据变量、源码获取变量、依赖变量、配置与编译任务、安装任务以及打包相关变量。BitBake 按顺序解析这些内容，但变量赋值并不完全等同于传统脚本的“顺序执行”，因为 BitBake 存在延迟展开和覆盖机制。

基础元数据包括 SUMMARY、DESCRIPTION、LICENSE、LIC_FILES_CHKSUM、SECTION 等；源码获取通常使用 SRC_URI；依赖分为 DEPENDS（构建时依赖）和 RDEPENDS:${PN}（运行时依赖）；构建行为由 do_configure、do_compile、do_install 等任务函数描述。

二、变量赋值与操作符

BitBake 的变量赋值有多种操作符，它们决定了赋值时机、是否展开以及是否追加。理解这些操作符是避免 Recipe 行为异常的关键。

其中 :append、:prepend、:remove 属于“覆盖语法”，常用于 .bbappend 文件中，对原始 Recipe 进行非侵入式修改。它们不会立即改变变量，而是在解析完成后统一应用，因此顺序和优先级需要特别注意。

三、注释规范

BitBake 支持两种注释形式：以 # 开头的行注释，以及行尾注释。注释不会参与变量展开，也不会影响任务执行。良好的注释应说明“为什么这样写”，而不是重复“写了什么”。

# 文件头：说明 Recipe 用途、维护者和上游版本
SUMMARY = "Example hello recipe"
LICENSE = "MIT"                 # 行尾注释：许可证类型
LIC_FILES_CHKSUM = "file://LICENSE;md5=..."

# 以下变量用于描述源码位置
SRC_URI = "file://hello.c"

在团队协作中，建议对非直观的 SRC_URI、补丁用途、PACKAGECONFIG 选项和自定义任务进行注释。避免在注释中保留过期信息，否则会误导后续维护者。

四、最小可运行 Recipe 示例

下面是一个最小但可运行的 Recipe，它从本地文件获取源码，编译一个简单的 C 程序，并安装到目标镜像中。

SUMMARY = "Minimal hello world recipe"
DESCRIPTION = "A minimal recipe used to demonstrate .bb syntax"
LICENSE = "MIT"
LIC_FILES_CHKSUM = "file://${COMMON_LICENSE_DIR}/MIT;md5=0835ade698e0bcf8506ecda2f7b4f302"

SRC_URI = "file://hello.c"

S = "${WORKDIR}"

do_compile() {
    ${CC} ${CFLAGS} ${LDFLAGS} hello.c -o hello
}

do_install() {
    install -d ${D}${bindir}
    install -m 0755 hello ${D}${bindir}/hello
}

该 Recipe 中，S 指向源码工作目录；do_compile 使用交叉编译器变量 ${CC} 编译；do_install 将可执行文件安装到 ${D}${bindir}。BitBake 会自动完成打包、依赖分析和镜像集成。

五、常见误区与复盘

• 误用 = 与 :=：在需要延迟展开的场景使用 :=，会导致变量被过早固定，无法被后续覆盖层修改。
• 混淆 += 与 :append：+= 在解析时追加，:append 在解析结束后追加；在 .bbappend 中应优先使用覆盖语法。
• 忽略 LIC_FILES_CHKSUM：缺少或错误的校验值会导致构建失败，必须与许可证文件内容匹配。
• 在 do_install 中直接写死路径：应使用 ${D}、${bindir} 等变量，保证安装路径符合 Yocto 规范。
• 注释与实现不一致：修改 Recipe 后未同步更新注释，导致后续排障困难。