RDK X5 镜像工程采用了一套双层配置架构来管理构建参数，将"硬件平台识别"与"镜像构建策略"解耦。底层通过 .rdk_config 回答"为目标 SoC 平台是什么"，上层通过 build_params/ 下的 .conf 文件回答"要构建什么样的镜像"。这种分层设计使得同一套构建脚本能够同时支持 X3/X5 双平台、Desktop/Server 双形态、Beta/Release 双通道的排列组合，而无需在脚本内部硬编码任何场景逻辑。

Sources: build.sh, .rdk_config, rdk_env.sh

双层配置架构与职责划分

在深入具体参数之前，有必要先理解两套配置文件的分工边界。.rdk_config 是一个极简的键值对文件，目前仅包含 RDK_SOC_NAME，其作用是回答硬件平台这一根本问题。所有与平台强相关的分支逻辑——例如选择内核源码目录、defconfig 文件名、设备树处理方式、deb 包名称前缀——都依赖这个变量进行决策。该文件通过交互式脚本 rdk_env.sh 生成，开发者执行后选择 x3 或 x5 即可写入配置。

相比之下，build_params/*.conf 是一组完整的 Bash 脚本片段，通过导出多个 RDK_* 环境变量来定义镜像的完整身份：版本命名、Ubuntu 发行版代号、镜像类型、软件源地址、预装包清单及本地目录映射。下述概念图展示了两层配置在构建流水线中的职责划分与影响范围。.rdk_config 主要影响编译阶段（内核与本地 deb 包），而 .conf 主要影响装配阶段（根文件系统下载、外部 deb 包拉取、镜像打包）。

graph TD
    subgraph 编译阶段
        A[.rdk_config<br/>RDK_SOC_NAME=x3/x5] --> B[mk_kernel.sh<br/>内核编译]
        A --> C[mk_kernel_rt.sh<br/>RT 内核编译]
        A --> D[mk_debs.sh<br/>Deb 包本地编译]
    end

    subgraph 装配阶段
        E[build_params/*.conf<br/>RDK_IMAGE_NAME/TYPE/...] --> F[build.sh<br/>主入口]
        E --> G[pack_image.sh<br/>镜像打包]
        E --> H[download_samplefs.sh<br/>根文件系统下载]
        E --> I[download_deb_pkgs.sh<br/>Deb 包下载]
        F -.->|传递 -c 参数| G
        F -.->|传递 -c 参数| H
        F -.->|传递 -c 参数| I
    end

Sources: mk_kernel.sh, mk_kernel_rt.sh, mk_debs.sh, pack_image.sh, build.sh

配置文件矩阵与命名约定

build_params/ 目录中存放了 8 个配置文件，其命名严格遵循 ubuntu-<版本>_<类型>_<平台>_<通道>.conf 的约定。这种命名方式本身就是一种自文档化的参数管理策略，开发者仅通过文件名即可判断该配置适用的场景。下表列出了全部配置文件的维度组合及其核心差异。值得注意的是，X3 与 X5 的软件生态不同，导致 RDK_DEB_PKG_LIST 存在显著差异——X3 包含 BPU 驱动、TROS 机器人操作系统等专有包，而 X5 则包含 xserver-xorg-core 以支持桌面显示栈。

Sources: build_params/

配置传播机制

当执行 sudo ./build.sh pack -c build_params/ubuntu-22.04_server_rdk-x5_release.conf 时，配置文件的传播路径如以下时序图所示。首先，build.sh 通过 getopts 解析 -c 选项并将路径保存到 CONFIG_FILE 变量。随后，在执行 do_pack 阶段，该路径作为参数传递给 pack_image.sh，后者通过 Bash 的 source 命令将 .conf 文件中的 export 变量加载到当前 Shell 环境。同样的传播逻辑也发生在 download_samplefs.sh 和 download_deb_pkgs.sh 中。

需要特别注意的是，mk_kernel.sh、mk_kernel_rt.sh 和 mk_debs.sh 并不接受 -c 参数，而是直接 source "$(dirname "$0")/.rdk_config"。这意味着它们只关心 SoC 平台信息，而不受上层 .conf 中镜像类型或通道的影响。这种隔离设计确保了内核与本地 deb 包的编译结果具有平台一致性，不会因为切换 Beta/Release 而重新编译。

sequenceDiagram
    participant U as 开发者
    participant B as build.sh
    participant P as pack_image.sh
    participant S as download_samplefs.sh
    participant D as download_deb_pkgs.sh
    participant C as .conf 文件

    U->>B: build.sh pack -c <conf>
    B->>B: getopts 解析 -c
    B->>P: pack_image.sh -l -c <conf>
    B->>S: download_samplefs.sh -c <conf>
    B->>D: download_deb_pkgs.sh -c <conf> (非本地构建时)
    P->>C: source "$CONFIG_FILE"
    S->>C: source "$CONFIG_FILE"
    D->>C: source "$CONFIG_FILE"
    P->>P: 消费 RDK_IMAGE_NAME 等变量

Sources: build.sh, pack_image.sh, download_samplefs.sh, download_deb_pkgs.sh

关键构建参数详解

build_params/*.conf 中导出的环境变量构成了镜像的"身份标识"与"物料清单"。下表列出了对构建结果有决定性影响的核心参数，理解这些参数的作用范围是进行自定义配置的前提。

Sources: ubuntu-22.04_desktop_rdk-x5_release.conf, pack_image.sh

Beta 与 Release 通道差异

Beta 与 Release 的核心差异体现在软件供应链的上游而非本地编译逻辑。在 Beta 配置中，RDK_IMAGE_VERSION 会追加 -beta 后缀，使得输出镜像文件名直观反映其测试属性。更重要的是，RDK_ARCHIVE_URL 从 Release 的 ubuntu-rdk-x5（或 X3 的 ubuntu-rdk）切换为带 -beta 后缀的独立仓库。这意味着 download_deb_pkgs.sh 会从 Beta 软件仓库拉取 deb 包，其 Packages 索引中的版本号通常领先于 Release 仓库。除此之外，Beta 与 Release 的本地编译逻辑完全一致，因为 mk_debs.sh 和 mk_kernel.sh 仅依赖 .rdk_config 中的 RDK_SOC_NAME，并不感知通道信息。这种设计允许开发者在不重新编译内核与本地 deb 包的情况下，仅通过切换 .conf 文件快速验证 Beta 软件生态。

Sources: ubuntu-22.04_desktop_rdk-x5_beta.conf, download_deb_pkgs.sh

Desktop 与 Server 镜像差异

Desktop 与 Server 的差异主要体现在预装包列表与根文件系统工作目录两个方面。在包列表层面，desktop 配置包含 xserver-xorg-core，而 server 配置将其移除，这直接决定了镜像是否具备图形显示能力。在目录映射层面，server 配置将 RDK_ROOTFS_DIR 设为 rootfs_${RDK_IMAGE_TYPE}（即 rootfs_server），而 desktop 通常保持为 rootfs。这使得两种形态的 samplefs 压缩包可以共存于工作区而互不覆盖。在 pack_image.sh 中，该变量决定了从哪个目录提取已下载的 samplefs 压缩包，并影响最终镜像的文件系统布局。

Sources: ubuntu-22.04_desktop_rdk-x5_release.conf, ubuntu-22.04_server_rdk-x5_release.conf, pack_image.sh

X3 与 X5 跨平台适配

X3 与 X5 的适配是构建系统中最为复杂的参数化逻辑，因为涉及内核源码、设备树、驱动及软件生态的系统性差异。RDK_SOC_NAME 作为唯一的平台标识符，在内核编译阶段决定了使用 source/x3-kernel 还是 source/kernel，对应的 defconfig 分别为 xj3_perf_ubuntu_defconfig 与 hobot_x5_rdk_ubuntu_defconfig，内核版本也分别为 4.14.87 与 6.1.83。在 RT 内核编译阶段，mk_kernel_rt.sh 还会根据平台选择不同的实时补丁（X5 使用 patch-6.1.83-rt28.patch）并应用 gs_usb.patch。

在 deb 包编译阶段，mk_debs.sh 维护了两份独立的包列表 deb_pkg_list_x3 与 deb_pkg_list_x5，其中 X3 的多个多媒体相关包带有 x3- 前缀（如 x3-hobot-multimedia、x3-hobot-spdev）。在打包阶段，pack_image.sh 针对 X5 会执行 RT 内核启动切换（修改 boot.scr 加载 Image-rt），而针对 X3 则会清理 /usr/lib/aarch64-linux-gnu/dri/ 目录。此外，X3 与 X5 的远程 deb 仓库地址也不同：X3 使用 ubuntu-rdk，X5 使用 ubuntu-rdk-x5，这确保了不同平台的 deb 包不会混淆。

Sources: mk_kernel.sh, mk_kernel_rt.sh, mk_debs.sh, pack_image.sh, ubuntu-22.04_desktop_rdk-x3_release.conf

自定义配置实践

当官方提供的 8 个配置文件无法满足特定需求时——例如内网镜像仓库、裁剪包列表、预发布版本验证——建议基于最接近的场景进行克隆修改。推荐的操作步骤如下：首先复制一份现有配置，例如 cp build_params/ubuntu-22.04_desktop_rdk-x5_release.conf build_params/custom.conf；然后根据需求调整 RDK_ARCHIVE_URL 指向私有仓库，或增删 RDK_DEB_PKG_LIST 数组中的包名；若需要固定 samplefs 版本，可将 RDK_SAMPLEFS_VERSION 从 latest 改为具体的版本号；最后通过 sudo ./build.sh pack -c build_params/custom.conf 验证。

需要特别注意两点：一是 RDK_DEB_PKG_LIST 中的包名必须与远程仓库 Packages 索引中的 Package: 字段严格一致，因为 download_deb_pkgs.sh 通过精确字符串匹配解析依赖关系；二是若修改了 RDK_ROOTFS_DIR，需确保该目录在打包前已包含有效的 samplefs 压缩包，否则 pack_image.sh 会因找不到 samplefs*.tar.gz 而失败。config/hobot_config.sh 当前为空壳脚本，但 pack_image.sh 会将其内容连同 config/ 目录下的其他文件通过 rsync 复制到镜像的 /boot/config 分区，可用于存放设备树覆盖层或其他启动配置。

Sources: build.sh, download_deb_pkgs.sh, pack_image.sh, config/hobot_config.sh

相关阅读

• 如需了解构建脚本的整体编排与子命令的执行顺序，请参阅 全量构建与子命令解析。
• 如需深入内核编译流程及 RT 实时内核的补丁机制，请参阅 双内核编译与实时内核。
• 如需了解 deb 包的本地编译逻辑及并行构建实现，请参阅 Deb 包本地编译与依赖管理。
• 如需理解镜像分区的计算逻辑及 rootfs 定制细节，请参阅 镜像打包与系统定制。