【yocto】Yocto Project 核心：深入了解.inc文件

    【关不关注无所谓，最主要的是开心...】

引言

    在 Yocto 项目（一个用于构建定制化 Linux 系统的框架）中，.inc 文件扮演着至关重要的角色。它们不是一种独特的语法或语言，而是 Yocto 社区和 BitBake 构建系统所采用的一种约定俗成的代码组织和复用机制。理解 .inc 文件是掌握 Yocto 项目结构和工作原理的关键。

1. 作用 (Purpose)

  .inc 文件的核心作用是代码复用和模块化。它们通常被称为“包含文件”（Include Files）。

    具体来说，它的作用包括：

• 封装通用配置和功能：将多个食谱（.bb 文件）或配置文件（.conf）中共享的通用变量、函数（如 do_install、do_compile 等任务）、配置片段剥离出来，放在一个单独的文件中。

• 减少代码冗余：通过在不同食谱中包含同一个 .inc 文件，可以避免重复编写相同的代码，遵循 DRY（Don‘t Repeat Yourself）原则。

• 提高可维护性：当需要修改通用逻辑时，只需修改一个 .inc 文件，所有引用它的食谱都会自动生效，极大地降低了维护成本和出错风险。

• 实现逻辑分离：将复杂的食谱逻辑分解到多个 .inc 文件中，使得主食谱文件（.bb）更加简洁、清晰，只关注于该食谱特有的部分。

    一个类比：将 .bb 文件看作一个程序的主函数（main），而 .inc 文件就像是这个程序所引用的头文件（Header Files）或库文件（Library Files），其中包含了各种共享的定义和函数。

2. 原理 (Principle)

.inc 文件的工作原理完全依赖于 BitBake 的 include 和 require 指令。

• 解析阶段：当 BitBake 解析一个食谱（.bb 文件）或配置文件时，遇到 include 或 require 指令，它会立即暂停当前文件的解析。

• 内容插入：BitBake 会定位到指令指定的 .inc 文件，并将其内容一字不差地、原地插入到指令所在的位置。

• 继续解析：插入完成后，BitBake 会继续解析插入后的完整内容。

    这个过程发生在 BitBake 的解析早期，远在任务执行（如 do_fetch, do_compile）之前。因此，最终被 BitBake 执行的文件，实际上是原始 .bb 文件与其所有包含的 .inc 文件内容合并后的结果。

include vs require:
虽然两者都用于包含文件，但有一个关键区别：

• include：如果指定的文件不存在，BitBake 会产生一个警告但会继续解析当前文件。

• require：如果指定的文件不存在，BitBake 会产生一个错误并立即停止解析。

    通常，如果被包含的文件是当前食谱必不可少的（例如，继承了一个重要的类），则使用 require。如果文件是可选的或可能不存在，则使用 include。

3. 引用方式 (How to Include)

    在 .bb 文件或其它 .conf 文件中，使用以下语法来引用 .inc 文件：

# 使用 include 指令
include recipes-core/package/common.inc# 使用 require 指令
require recipes-core/package/common.inc# 使用变量来构造路径（更常见、更灵活）
require ${COREBASE}/meta/recipes-core/package/common.inc

路径解析：
BitBake 会在 BBPATH 环境变量所定义的目录列表中搜索目标文件。BBPATH 通常包含了所有层（layer）的路径（如 poky/meta， poky/meta-poky， 以及你自己添加的层 ~/mylayer）。因此，你通常只需要提供相对于 BBPATH 中某个目录的路径即可。

例如，如果 BBPATH 中包含 /home/user/poky/meta，那么 recipes-core/package/common.inc 会被解析为 /home/user/poky/meta/recipes-core/package/common.inc。

4. 语法规则 (Syntax Rules)

    至关重要的一点是：.inc 文件没有自己独特的语法。它的语法与包含它的父文件（通常是 .bb 文件）的语法完全一致。

.inc 文件可以包含任何有效的 BitBake 语法：

• 变量赋值：

  DESCRIPTION = "My common description"
  LICENSE = "MIT"
  DEPENDS = "zlib openssl"

• 重写任务：

  do_install_prepend() {# 在所有食谱的 do_install 任务本应执行的操作之前，先执行这个操作oe_runmake install DESTDIR=${D} PREFIX=${prefix} SPECIAL_OPTION="y"
  }do_install_append() {# 在所有食谱的 do_install 任务本应执行的操作之后，再执行这个操作install -d ${D}${sysconfdir}/myappinstall -m 644 ${S}/configfile ${D}${sysconfdir}/myapp/
  }

• 函数定义：

  my_custom_function() {echo "This is a shared function"# 一些复杂操作
  }

• 继承类：

  inherit cmake pkgconfig

• 包含其它文件：

  # 一个 .inc 文件可以继续包含另一个 .inc 文件
  include common-utils.inc

关键注意事项：

• 上下文相关：由于 .inc 文件的内容是被直接插入的，因此它必须在其被包含的上下文中是有效的。例如，如果一个 .inc 文件使用了变量 S（源代码目录），那么包含它的 .bb 文件必须正确定义了 S，否则会出错。
• 变量作用域：在 .inc 文件中定义的变量会融入到包含它的 .bb 文件的作用域中，可能会覆盖之前定义的同名变量，也可能被之后定义的同名变量覆盖。需要小心管理变量的覆盖顺序。
• 条件语句：.inc 文件中可以使用 BitBake 的条件语法（如 OVERRIDES、python 条件赋值等），但其行为取决于包含它的文件的上下文（例如 MACHINE， DISTRO 等变量的值）。

5. 最佳实践和常见用法 (Best Practices and Common Uses)

• 命名约定：虽然不强制，但通常 .inc 文件名会暗示其用途，例如 common.inc， ${PN}-${PV}.inc（用于拆分版本相关的配置）， definitions.inc 等。

• 与 .bbappend 文件结合：.bbappend 文件经常使用 include 或 require 来添加额外的补丁、文件或修改任务，从而扩展原始食谱的功能。

• 经典示例：Linux 内核：linux-yocto 食谱是一个绝佳的例子。它有一个主文件 linux-yocto_6.6.bb，然后包含了大量的 .inc 文件来处理不同架构的特性（features/ 目录下的 .inc 文件）、配置文件（cfg/ 目录）等，实现了高度的模块化。

总结