本文档为初次接触 RDK X5 镜像构建的开发者提供一张「全景地图」。你将快速理解 x5-rdk-gen 工程解决了什么问题、它的核心模块如何协作、以及怎样用一条命令或分步指令得到可烧录的系统镜像。文中不会深入每一行编译参数，但会为你建立足够的上下文，以便后续按需深挖具体环节。

RDK X5 镜像构建是什么

x5-rdk-gen 是 D-Robotics 面向 RDK X5 开发板发布的一站式系统镜像构建工程。它把源码同步、交叉编译、根文件系统构建、Deb 包打包与最终镜像生成串联成一条可分段执行的流水线。主控脚本 build.sh 以子命令形式对外暴露接口，初学者只需记住 sudo ./build.sh all 即可完成从零到一的全量构建，而进阶开发者则可以按需单独触发内核编译、Bootloader 编译或 Deb 包构建，大幅缩短调试周期。

Sources: build.sh

为什么需要这套构建系统

机器人场景对系统有强定制化需求：既需要标准 Linux 内核保证兼容性，又需要 RT 实时内核满足低延迟控制；既要预装多媒体、BPU 推理、摄像头驱动等专用组件，又要保持根文件系统的可裁剪性。RDK X5 构建系统通过**「配置驱动 + 子命令编排」**的设计，把这些复杂度封装在脚本内部。用户只需修改 build_params/ 下的配置文件，即可在无图形界面的 Server 镜像与带桌面的 Desktop 镜像之间切换，也可以在稳定版 Release 与测试版 Beta 通道之间选择，而不必手动干预数十个编译步骤。

Sources: build_params/ubuntu-22.04_desktop_rdk-x5_release.conf

工程架构总览

整个构建系统可抽象为三层：准备层、编译层、打包层。准备层负责安装主机依赖并拉取源码；编译层并行产出内核、Bootloader 与 Deb 软件包；打包层将根文件系统、预编译包与本地编译包合并，写入分区并生成 .img 镜像。

graph TD
    A[build.sh 主控脚本] --> B[setup 环境初始化]
    A --> C[kernel 内核编译]
    A --> D[bootloader 引导程序]
    A --> E[rootfs 根文件系统]
    A --> F[debs 软件包编译]
    A --> G[pack 镜像打包]

    C --> C1[mk_kernel.sh<br/>标准内核 6.1.83]
    C --> C2[mk_kernel_rt.sh<br/>RT内核 6.1.83-rt28]

    E --> E1[make_ubuntu_samplefs.sh<br/>debootstrap 构建]

    F --> F1[mk_debs.sh<br/>17个 hobot-* 包]

    G --> G1[pack_image.sh<br/>分区/烧录/压缩]

    style A fill:#f9f,stroke:#333,stroke-width:2px

在架构中，build.sh 扮演编排器的角色，自身不执行具体编译逻辑，而是按序调用 mk_kernel.sh、mk_debs.sh、pack_image.sh 等专用脚本。这种**「调度与实现分离」**的设计让每个脚本都可以独立运行，也方便开发者在 CI 或容器环境中做更细粒度的步骤拆分。

Sources: build.sh

核心构建流程

从源码到可烧录镜像，流水线会依次经过以下阶段。初学者不必立刻记住每一步，但了解这个顺序有助于在构建出错时快速定位「卡在哪一层」。

flowchart LR
    subgraph 准备阶段
        S1[安装依赖与工具链] --> S2[repo sync 拉取源码]
    end

    subgraph 编译阶段
        K1[编译标准内核] --> K2[编译RT内核]
        K2 --> BL[编译Bootloader]
        BL --> DEB[编译本地Deb包]
    end

    subgraph 打包阶段
        R1[构建Ubuntu rootfs] --> R2[解压并执行定制脚本]
        R2 --> R3[合并三处Deb包并安装]
        R3 --> R4[生成RT内核boot.scr]
        R4 --> R5[创建config+rootfs双分区镜像]
    end

    S2 --> K1
    DEB --> R3

这里有几个值得初学者关注的细节：第一，内核编译阶段会同时产出标准内核 Image 与 RT 内核 Image-rt，但镜像默认使用 RT 内核启动；第二，pack_image.sh 会合并来自三个目录的 Deb 包——官方下载的 deb_packages/、本地编译的 deploy/deb_pkgs/、以及用户自定义的 third_packages/，同名包保留最新版本；第三，最终镜像包含两个分区，一个是 256MB 的 FAT32 配置分区，另一个是 ext4 根文件系统分区。

Sources: pack_image.sh

目录结构导览

理解目录的用途，是避免「找不到编译产物」的第一步。以下是 x5-rdk-gen 的核心目录及职责说明：

x5-rdk-gen/
├── build.sh                    # 主控脚本（子命令入口）
├── build_params/               # 构建配置文件（desktop/server/release/beta）
├── config/                     # 系统配置模板（如 hobot_config.sh）
├── samplefs/                   # rootfs 构建脚本与 Ubuntu 包列表
│   ├── make_ubuntu_samplefs.sh
│   └── jammy/                  # Ubuntu 22.04 包列表
├── source/                     # repo 同步后的源码目录
│   ├── kernel/                 # Linux 内核源码
│   ├── kernel-rt/              # RT 补丁内核源码
│   ├── bootloader/             # U-Boot + miniboot 源码
│   └── hobot-*/                # 各官方 deb 包源码
├── rootfs/                     # 构建好的 rootfs tar.gz 存放处
├── deploy/                     # 编译产物输出目录
│   ├── kernel/                 # 内核、设备树、模块
│   ├── deb_pkgs/               # 本地编译的 deb 包
│   └── *.img / *.zip           # 最终系统镜像
├── mk_kernel.sh                # 标准内核编译脚本
├── mk_kernel_rt.sh             # RT 内核编译脚本
├── mk_debs.sh                  # 本地 deb 包编译脚本
├── pack_image.sh               # 镜像打包主脚本
└── hobot_customize_rootfs.sh   # rootfs 定制化脚本

deploy/ 是开发者最关心的目录，内核编译产物、本地 deb 包与最终 .img 镜像都会落在这里。source/ 下的源码由 repo sync 拉取，首次构建前必须先执行 ./build.sh setup。

Sources: README_CN.md

构建子命令速查

build.sh 提供 8 个子命令，覆盖从环境准备到镜像生成的完整生命周期。下表按「从少到多」的依赖顺序排列：

对于急于看到成果的初学者，推荐先执行 sudo ./build.sh all 走通一次全流程；当进入日常迭代时，更常用的是 sudo ./build.sh image，它会跳过环境初始化和 rootfs 构建，直接复用已有的 rootfs/ 目录。

Sources: build.sh

镜像类型与配置

build_params/ 目录下预置了 4 份配置文件，覆盖两种系统形态与两种版本通道：

切换配置的方法是在任意子命令后追加 -c 参数。例如，要使用 Server 配置执行打包：

sudo ./build.sh pack -c build_params/ubuntu-22.04_server_rdk-x5_release.conf

Desktop 与 Server 的差异主要体现在 rootfs 构建阶段：Desktop 会额外安装桌面环境与图形相关软件包，而 Server 仅保留基础系统服务。Release 与 Beta 的差异则体现在镜像命名与部分预装包的版本策略上。

Sources: build_params/ubuntu-22.04_server_rdk-x5_release.conf

三种典型使用场景

以下三种模式覆盖了绝大多数开发者的日常需求。

场景一：从零开始完整构建

适用于首次搭建环境或更换主机后的全新构建。该命令会下载工具链、同步源码、编译所有组件并生成镜像：

sudo ./build.sh all

执行前请确保主机为 Ubuntu 22.04 x86_64，具备 root 权限，且有 50GB 以上可用磁盘空间。

场景二：修改源码后的增量构建

假设你已修改了 source/hobot-io/ 中的源码，希望快速验证改动。由于 rootfs 无需重建，只需执行：

sudo ./build.sh image

它会依次触发 kernel → bootloader → debs → pack，跳过耗时的 setup 与 rootfs 步骤。

场景三：仅打包镜像（使用预制 rootfs）

如果你已经从其他渠道获得了 samplefs_desktop_*.tar.gz 并放入 rootfs/ 目录，只想重新调整 deb 包或配置并生成镜像：

sudo ./build.sh pack -c build_params/ubuntu-22.04_desktop_rdk-x5_release.conf

此模式在调试 hobot_customize_rootfs.sh 或验证第三方 deb 包时非常有用。

Sources: build.sh

下一步学习路线

本页仅提供「速览」级别的全景认知。若你已准备好深入某一具体环节，可按以下路径继续阅读：

• 想理解每个子命令的内部调用链与脚本编排细节 → 全量构建与子命令解析
• 想了解标准内核与 RT 实时内核的编译差异 → 双内核编译与实时内核
• 想从源码编译 hobot- deb 包并管理依赖* → Deb 包本地编译与依赖管理
• 想定制 rootfs、修改分区策略或调试镜像打包 → 镜像打包与系统定制
• 想理解配置文件的每个变量含义与参数管理 → 构建配置与参数管理

如果你尚未完成环境搭建，建议先回到 快速开始 确认主机依赖与网络环境，再返回此处执行构建。