# 根文件系统适配指南

## <span id="buildroot_use"/> 使用 Buildroot 制作根文件系统

X5 的根文件系统通过 Buildroot 制作，支持生成两种类型的根文件系统： initramfs 和 system。

- **initramfs**：包含最简化的根文件系统，与 Linux Kernel 合并打包为 boot.img，主要用于安全启动和恢复系统。
- **system**：用于提供系统运行环境的完整根文件系统。

### Buildroot 源码

源码地址： <https://gitlab.com/buildroot.org/buildroot.git>

版本： 2022.08

在 `system/buildroot/source` 目录下提供了用于下载 Buildroot 和制作 rootfs 的脚本与补丁。

```
.
├── buildroot_packages_2022.08          # 存放下载的 Buildroot 软件包源码，避免多次调试时重复下载
├── build.sh                            # 主脚本程序
├── configs                             # 软件包配置文件
├── framework                           # 输出目录
└── hb_patch_buildroot                  # X5 系统在原始 Buildroot 上打的补丁
```

**说明**：首次使用 Buildroot 制作根文件系统时需要联网下载软件源码 tar 包。`build.sh` 脚本会将下载的源码存储到 `buildroot_packages_2022.08` 目录中（通过设置 `BR2_DL_DIR` 实现）。

如果通过 Buildroot 默认配置下载软件包时遇到网络不稳定、速度慢或下载失败的问题，用户可先从 <https://archive.d-robotics.cc/buildroot/> 下载需要的软件包，并存放到 `buildroot_packages_2022.08` 目录中。

*注意：该网址不包含 Buildroot 所有依赖包，仅收录当前开发中 2022.08 版本所需的部分软件包。如需新增软件支持，请联系 D-Robotics 技术支持，我们会及时更新。*

### 预编译的根文件系统

当前 BSP 提供了预编译的 rootfs，存放目录如下（注意各个镜像文件的版本号以实际版本为准）：

```Shell
# system
system/buildroot/prebuilt/dr-system_0.0.21~gcc11.3.1_all.deb

# initramfs
system/initramfs/dr-initramfs_0.0.1~gcc11.3.1_all.deb
```

对应的 Buildroot 配置文件位于 `system/buildroot/source/configs`：

```Shell
.
├── x5_initramfs_defconfig
├── x5_system_defconfig
└── x5_system_with_docker_defconfig
```

用户可根据需要修改配置文件，增加或删除软件包。通过以下命令进行图形化配置（配置完成后会自动覆盖原配置）：

```bash
cd system/buildroot/source
./build.sh menuconfig x5_initramfs_defconfig
./build.sh menuconfig x5_system_defconfig
```

### 制作 system

1. 执行 buildroot 编译操作

    ```bash
    cd system/buildroot/source
    ./build.sh build x5_system_defconfig <version number>  # eg: 0.0.1
    ```

    比如：

    ```shell
    ./build.sh build x5_system_defconfig 0.0.1
    ```

    **注意：** 制作根文件系统命令中最后一个参数为镜像版本号，可以根据需要修改，最终该版本号会拼接到镜像文件名称中，编译出来的根文件系统镜像在 `system/buildroot/source/framework/output/images` 目录中，比如：

    ```bash
    dr-system_0.0.1~gcc11.3.1_all.deb
    ```

2. 拷贝新镜像到预置目录并更新索引文件

    编译烧录所需的根文件系统镜像的时候，需要将新制作的镜像文件复制到 `system/buildroot/prebuilt/` 目录，也就是前文提到的预编译的 system rootfs 存放目录（注意各个镜像文件的版本号以实际版本为准）：

    ```bash
    system/buildroot/prebuilt$ ls
    boot-utils-runtime                         dr-libgtest_1.14.0~gcc11.3.rel1_arm64.deb   dr-system_0.0.29~gcc11.3.1_all.deb
    dr-initramfs_0.0.1~gcc11.3.1_all.deb       dr-libhpatchz_3.1.1~gcc11.3.rel1_arm64.deb  series
    dr-libdnn_1.24.5~gcc11.3.rel1_arm64.deb    dr-perf_6.1.12~gcc11.3.rel1_arm64.deb
    dr-libgdcbin_1.0.0~gcc11.3.rel1_arm64.deb  dr-system_0.0.1~gcc11.3.1_all.deb
    ```

    此时需要修改同一目录下的 `system/buildroot/prebuilt/series` 文件，把旧版本号改成前面编译所配置的新版本号，例如：

    ```Diff
    diff --git a/buildroot/prebuilt/series b/buildroot/prebuilt/series
    index 42ba771..4617101 100644
    --- a/buildroot/prebuilt/series
    +++ b/buildroot/prebuilt/series
    @@ -1,4 +1,4 @@
    -dr-system_0.0.29~gcc11.3.1_all.deb
    +dr-system_0.0.1~gcc11.3.1_all.deb
    dr-libgtest_1.14.0~gcc11.3.rel1_arm64.deb
    dr-libgdcbin_1.0.0~gcc11.3.rel1_arm64.deb
    dr-perf_6.1.12~gcc11.3.rel1_arm64.deb
    ```

    一般的，建议按顺序递增版本号，以便于维护。

3. 重新打包

    回到工程根目录，执行：

    ```bash
    ./bd.sh system clean
    ./bd.sh system
    ```

    即可在 `out/product/` 目录下得到新的根文件系统镜像 `system.img`，该镜像可直接用于烧录。

### 制作 initramfs

```bash
cd system/buildroot/source
./build.sh build x5_initramfs_defconfig <version number>  # eg: 0.0.1
```

比如：

```shell
./build.sh build x5_initramfs_defconfig 0.0.1
```

关于版本号的说明和制作 system 相同，不再赘述。

## 使用 Multistrap 制作 Ubuntu 根文件系统

X5 支持通过 Multistrap 制作基于 Ubuntu 的根文件系统。目前默认提供基于 Ubuntu 22.04 (Jammy) 的根文件系统。

### 预编译的根文件系统

当前 BSP 提供了预编译的 rootfs，存放目录如下（注意各个镜像文件的版本号以实际版本为准）：

```
system/ubuntu/prebuilt/dr-system-jammy_0.0.1_all.deb
```

对应的 Multistrap 配置文件位于 `system/ubuntu/source/configs`：

```
.
└── x5_system_jammy.conf
```

用户可根据需要修改配置文件，增加或删除软件包。

### 制作 system

```bash
cd system/ubuntu/source
./build.sh clean
sudo ./build.sh build x5_system_jammy.conf 0.0.1
```

<div class="note">
<strong> 注意：</strong> <br>
    使用 Multistrap 制作根文件系统时需要联网下载软件 deb 包。配置文件默认使用<a href="https://mirrors.tuna.tsinghua.edu.cn/help/ubuntu-ports/">清华大学的镜像源</a>作为 apt 的源。<br>
    制作 jammy 的根文件系统时一定要使用 sudo 权限，否则需要第一次烧录镜像后 <code>dpkg --configure -a</code> 逐个安装并配置尚未配置的软件包<br>
</div>
