4.4.3. 根文件系统适配指南

4.4.3.1. 使用 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_2025.02         # 存放下载的 Buildroot 软件包源码，避免多次调试时重复下载
├── build.sh                            # 主脚本程序
├── configs                             # 软件包配置文件
├── framework                           # 输出目录
└── hb_patch_buildroot                  # X5 系统在原始 Buildroot 上打的补丁

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

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

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

预编译的根文件系统

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

# 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

# QT支持包
system/buildroot/prebuilt/dr-system-qt5_0.0.1~gcc11.3.1_all.deb

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

.
├── x5_initramfs_defconfig
├── x5_system_defconfig
├── x5_system_qt5_defconfig
├── x5_system_quickstart_defconfig
└── x5_system_with_docker_defconfig

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

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

制作 system

执行 buildroot 编译操作
```
cd system/buildroot/source
./build.sh build x5_system_defconfig <version number>  # eg: 0.0.1
```
比如：
```
./build.sh build x5_system_defconfig 0.0.1
```
注意： 制作根文件系统命令中最后一个参数为镜像版本号，可以根据需要修改，最终该版本号会拼接到镜像文件名称中，编译出来的根文件系统镜像在 system/buildroot/source/framework/output/images 目录中，比如：
```
dr-system_0.0.1~gcc11.3.1_all.deb
```

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

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

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 --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

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

重新打包

回到工程根目录，执行：
```
./bd.sh system clean
./bd.sh system
```
即可在 out/product/ 目录下得到新的根文件系统镜像 system.img，该镜像可直接用于烧录。

制作 initramfs

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

比如：

./build.sh build x5_initramfs_defconfig 0.0.1

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

制作 QT支持包

如果需要在系统中支持 Qt5，需单独制作带有 Qt 支持的根文件系统（QT 支持包），其制作方法与 system 的制作流程完全一致，仅是在配置文件（defconfig）的选择上使用 Qt5 相关的配置。具体步骤如下：

执行 buildroot 编译操作
```
cd system/buildroot/source
./build.sh build x5_system_qt5_defconfig <version number>  # 例如: 0.0.1
```
比如：
```
./build.sh build x5_system_qt5_defconfig 0.0.1
```
注意： 制作 QT 支持包根文件系统时，命令中最后一个参数为镜像版本号，可以根据需要修改。最终该版本号会拼接到镜像文件名称中，编译出的根文件系统镜像在 system/buildroot/source/framework/output/images 目录中，比如：
```
dr-system-qt5_0.0.1~gcc11.3.1_all.deb
```

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

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

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

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

diff --git a/buildroot/prebuilt/series b/buildroot/prebuilt/series
index 793d99b..0993a86 100644
--- a/buildroot/prebuilt/series
+++ b/buildroot/prebuilt/series
@@ -1,4 +1,4 @@
-dr-system_0.0.30~gcc11.3.1_all.deb
+dr-system-qt5_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

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

重新打包

回到工程根目录，执行：
```
./bd.sh system clean
./bd.sh system
```
即可在 out/product/ 目录下得到新的根文件系统镜像 system.img，该镜像可直接用于烧录。

4.4.3.2. 使用 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

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

注意：
使用 Multistrap 制作根文件系统时需要联网下载软件 deb 包。配置文件默认使用清华大学的镜像源作为 apt 的源。
制作 jammy 的根文件系统时一定要使用 sudo 权限，否则需要第一次烧录镜像后 dpkg --configure -a 逐个安装并配置尚未配置的软件包

4.4.3.3. 使用 APPSDK 进行应用开发

APPSDK（Application SDK，下面简称 SDK）是一套自包含的交叉编译环境。应用开发者无需下载完整项目源码，也无需在主机预装 arm-gnu-toolchain，拿到 SDK deb 包后执行 install.sh 即可安装，source environment-setup 激活环境变量后直接编译 X5 应用（也支持 X5 hbre 中各个库的单独编译）。

sysroot 取自 BSP 解包的 rootfs 运行库（out/deploy/system）+ hbre 产物 + 工具链自带的 crt/libc 头。打包者改了 hbre 后只需 ./bd.sh hbre && ./bd.sh appsdk 即可重打包，无需重编 Buildroot 根文件系统。

SDK 版本号与 BSP 大版本号对齐，便于开发人员快速匹配对应版本。

SDK 内含：

ARM GNU Toolchain 副本（aarch64-none-linux-gnu-gcc 等）
bin/ 下交叉工具链相对路径软链（指向 arm-gnu-toolchain/bin/，无 wrapper 中间层）
完整 sysroot（glibc crt + 系统库头文件与库，如 OpenSSL 3.x、alsa、dbus、bluez、libdrm 等；来自 rootfs 运行库 + 工具链 libc 合并）
hbre 库（libcam、libvpf、libalog、libhbmem、libdsp、libpowerctl 等的 .so 与头文件，含 versioned runtime 软链 .so.N）
system 域库（libgdcbin、libcjson、libdnn、libgtest、libhpatchz 等，来自 series 引用的 deb）
environment-setup-aarch64-x5-linux 环境脚本（source 后即可使用）
SDK 版 common Makefile（hbre/app Makefile.in 通过 SRC_DEVICE_COMMON_DIR include 该文件）
version-aarch64-x5-linux 版本追溯信息

前置条件

SDK 打包者（产出 SDK 的开发者）

打包 SDK 的机器需要完整的项目源码与已构建的产物：

完整 X5 项目源码
已执行 ./bd.sh lunch <board> 选定板级配置
system 已解包：./bd.sh system unpack（产出 out/deploy/system/，是 sysroot 的 system 域库来源；改了根文件系统重编 dr-system deb 后需重新 unpack 刷新）
hbre 已构建：./bd.sh hbre（产出 out/build/hbre_deps/ 与 out/deploy/hbre/）
外部 toolchain tarball：toolchain/arm-gnu-toolchain-11.3.rel1-x86_64-aarch64-none-linux-gnu.tar.xz

建议先执行一遍 ./bd.sh 完整编译整个工程源码，即可包括上述所有过程。

无需构建 Buildroot——APPSDK 不依赖 Buildroot host sysroot，sysroot 取自 out/deploy/system（rootfs 运行库）+ hbre 产物 + 工具链 libc 合并。打包者改了 hbre 后只需 ./bd.sh hbre && ./bd.sh appsdk 即可重打包。

如果上述产物未就绪，./bd.sh appsdk 会报错并提示对应的前置命令。

SDK 使用者（应用开发者）

应用开发者的开发环境只需要：

Ubuntu 22.04（或其它 Linux 发行版）
build-essential、cmake、file（验收脚本依赖，普通开发也建议装）
无需 /opt/arm-gnu-toolchain（SDK 自包含）

Ubuntu 可通过 apt 一键安装上述依赖：

sudo apt update && sudo apt install -y build-essential cmake file

打包 SDK

在项目根目录执行（需先 ./bd.sh lunch <board> 选板级）：

./bd.sh appsdk

版本号从 BSP 大版本号 HR_V_VER（device/horizon/x5/dr_release_version.mk 导出，如 _V1.1.2）自动提取并小写化（v1.1.2），无需手动指定。

清理 SDK 产物：

./bd.sh appsdk clean       # 清 out/deploy/appsdk/images/ 下的 SDK 产物（等同 distclean）

打包成功后，产物在 out/deploy/appsdk/images/ 目录：

out/deploy/appsdk/images$ ls platform-appsdk-*
platform-appsdk-v1.1.2.deb         # SDK 本体（deb 格式，含 SDK 全部文件）
platform-appsdk-v1.1.2.tar.gz      # 总包（含 deb + install.sh + relocate-paths.sh + test-sdk.sh）

产物名格式 platform-appsdk-<sdk_version>。sdk_version 由 HR_V_VER 提取并小写化（如 _V1.1.2 → v1.1.2），由 BSP 版本管理。

tar.gz 总包内含四件产物：

$ tar tzf platform-appsdk-v1.1.2.tar.gz
platform-appsdk-v1.1.2.deb
install.sh
relocate-paths.sh
test-sdk.sh

应用开发者只需拿到 tar.gz 总包即可。

安装 SDK

把 tar.gz 总包拷到应用开发者的机器，解压并运行安装脚本：

tar xzf platform-appsdk-v1.1.2.tar.gz
./install.sh platform-appsdk-v1.1.2.deb

install.sh 会交互式询问安装模式：

Found platform-appsdk-v1.1.2.deb

APPSDK supports two install modes:

  [1] sudo mode (recommended, requires sudo)
      - Installs to a fixed path /opt/platform-appsdk
      - Managed by dpkg: upgrade (sudo dpkg -i <new>), remove (sudo dpkg -r)
      - Source /opt/platform-appsdk/environment-setup-aarch64-x5-linux from any directory
      - On upgrade, dpkg replaces old files automatically — no manual cleanup

  [2] no-sudo mode (no sudo required)
      - Choose install path interactively (e.g. current directory)
      - Managed by install.sh: upgrade/remove via install.sh --uninstall
      - WARNING: do not place personal files inside platform-appsdk/ (upgrade removes the whole dir)
      - Source <install-path>/environment-setup-aarch64-x5-linux to use

Select [1/2] (default 1):

模式 1：sudo 模式（推荐）

用户选 1 后，install.sh 执行 sudo dpkg -i（sudo 自身会提示输入密码）：

sudo dpkg -i platform-appsdk-v1.1.2.deb

安装到固定路径 /opt/platform-appsdk
用 dpkg 管理升级和卸载
source 路径固定，任意目录均可使用

模式 2：无 sudo 模式

用户选 2 后，install.sh 交互读取安装路径，用 dpkg-deb -x 解包到指定路径：

Install path [./]:
# SDK 解到 ./platform-appsdk/

无需 sudo 权限
安装路径可自定义
注意：不要在 platform-appsdk/ 目录内放置个人文件（升级时整个目录会被删除重装）

升级与卸载

升级

sudo 模式：

sudo dpkg -i platform-appsdk-v2.0.0.deb    # dpkg 自动替换旧文件

dpkg 自动处理新旧文件替换，无需手动清理。如果新版本修改了 environment-setup，dpkg 会通过 conffile 保护机制判断是否覆盖。

无 sudo 模式：

./install.sh platform-appsdk-v2.0.0.deb    # 选模式 2，自动删旧目录 + 解新 deb

实现方式是 rm -rf 整个旧 platform-appsdk/ 目录后重装。因此用户不得在 platform-appsdk/ 内放置任何个人文件——升级时会被一并删除。

卸载

sudo 模式：

sudo dpkg -r platform-appsdk        # 软卸载：保留 conffile（environment-setup）
sudo dpkg -P platform-appsdk        # 彻底卸载：连 conffile 一起删

无 sudo 模式：

./install.sh --uninstall <安装路径>
# 只删 SDK 文件，用户代码（不在 platform-appsdk/ 内的）保留

`dpkg -r` 与 `dpkg -P` 详细对比

维度	`sudo dpkg -r platform-appsdk` (Remove)	`sudo dpkg -P platform-appsdk` (Purge)
普通文件	删除	删除
conffile（environment-setup）	保留	删除
dpkg 数据库信息	`/var/lib/dpkg/info/<pkg>.*` 保留	`/var/lib/dpkg/info/<pkg>.*` 全删
dpkg 状态变化	`ii` → `rc`（removed, config-files remain）	`ii` → `un`/`pn`（unknown/purged, not installed）
postrm 触发	`postrm remove`	`postrm remove` + `postrm purge`
能否再次 `dpkg -i` 装回	支持	支持

关键差异：conffile 保护机制——dpkg 用 conffiles 机制保护用户改过的配置文件：

用 dpkg -r 卸载后：
  /opt/platform-appsdk/environment-setup-aarch64-x5-linux   ← 还在
  /opt/platform-appsdk/sysroot/...                            ← 已删

  dpkg -i platform-appsdk-v1.1.2.deb 重装：
    1. 算 conffile md5
    2. 比对 .dpkg-new（新版本文件）：
       - 用户未改 conffile（md5 一致）→ 用新版本覆盖
       - 用户改过 conffile（md5 不一致）→ 保留用户版本，新版本存为 conffile.dpkg-dist
       - 用户删了 conffile → dpkg 静默处理
    3. dpkg 状态：rc → ii

选用建议：

临时卸载，要重装：sudo dpkg -r（保留 conffile，重装时如果未改则被新版本覆盖）
彻底清理，重新装：sudo dpkg -P（连 conffile 一起删，重装完全等于首次安装）
升级到新版本：sudo dpkg -i <新版.deb>（dpkg 自动 remove + install，行为等同 -r + install）

实际验证建议：

# 1. 装好后看 dpkg 状态
dpkg -l platform-appsdk
# 预期：ii  platform-appsdk  1.1.2

# 2. dpkg -r 后看状态
sudo dpkg -r platform-appsdk
dpkg -l platform-appsdk
# 预期：rc  platform-appsdk  1.1.2    ← rc = removed, config-files
ls /opt/platform-appsdk/environment-setup-aarch64-x5-linux
# 预期：文件还在

# 3. dpkg -P 后看状态
sudo dpkg -P platform-appsdk
dpkg -l platform-appsdk
# 预期：un <无描述>  (或找不到)
ls /opt/platform-appsdk/environment-setup-aarch64-x5-linux
# 预期：No such file or directory

使用 SDK 编译应用

方式一：直接用 gcc 编译

source environment-setup 后，CC、CXX、CFLAGS、LDFLAGS、SDKTARGETSYSROOT 等环境变量都已设好（CC 已含 --sysroot 与 arch 参数），直接用 $CC/$CXX 编译即可：

# source 环境脚本（每个新 shell 都要 source 一次）
source /opt/platform-appsdk/environment-setup-aarch64-x5-linux

# 编译 helloworld
cat > hello.c <<'EOF'
#include <stdio.h>
int main() { printf("hello x5\n"); return 0; }
EOF

$CC hello.c -o hello

# 验证产物架构
file hello
# hello: ELF 64-bit LSB executable, ARM aarch64, ...

# 链接 hbre 库（如 libcam）
$CC app.c -o app -lcam -lvpf -lgdcbin

# 链接系统库（如 OpenSSL）
$CC app.c -o app -lssl -lcrypto

# C++ 项目用 $CXX
$CXX app.cpp -o app -lstdc++

# libdrm：头文件在 include/libdrm 子目录，需显式 -I
$CC app.c -o app -I${SDKTARGETSYSROOT}/usr/include/libdrm -ldrm

CC 的完整值为 aarch64-none-linux-gnu-gcc -mcpu=cortex-a55 -mabi=lp64 --sysroot=<SDK sysroot>，已含交叉编译器、sysroot 与 arch 参数，直接用 $CC 即可。

CFLAGS 跟随 HR_TARGET_MODE：debug 模式用 -O0 -g，release 模式用 -O2，与 BSP build/common/Makefile 一致。

方式二：CMake 项目

source /opt/platform-appsdk/environment-setup-aarch64-x5-linux

mkdir build && cd build
cmake ..
make

APPSDK 无自带 toolchainfile.cmake，CMake 项目用 environment-setup 配好的 $CC。在 CMakeLists.txt 里取环境变量指定 compiler 与 flags：

cmake_minimum_required(VERSION 3.10)
set(CMAKE_C_COMPILER aarch64-none-linux-gnu-gcc)
set(CMAKE_C_FLAGS "-mcpu=cortex-a55 -mabi=lp64 --sysroot=$ENV{SDKTARGETSYSROOT} -isystem $ENV{SDKTARGETSYSROOT}/usr/include -L$ENV{SDKTARGETSYSROOT}/usr/lib")
project(myapp C)
add_executable(myapp main.c)

方式三：autotools 项目

主机需安装 autotools 工具链：sudo apt install -y autoconf automake libtool

source /opt/platform-appsdk/environment-setup-aarch64-x5-linux

./configure --host=aarch64-none-linux-gnu
make

environment-setup 设了 CONFIGURE_FLAGS（含 --target、--host、--build、--with-libtool-sysroot），autotools 项目 ./configure 时会自动用。

若项目用 PKG_CHECK_MODULES([...],[libdrm]) 探测系统库，configure 会因 sysroot 无 libdrm.pc 报 Package 'libdrm' not found。SDK 不带 .pc，设 <PREFIX>_CFLAGS/<PREFIX>_LIBS 环境变量不能旁路该检查（宏仍调 pkg-config --exists）。需按项目自行处理（如预置 cache 变量 pkg_cv_<PREFIX>_CFLAGS/_LIBS、PKG_CONFIG=true ./configure、或 patch configure.ac），机制需实测，本指南不给定配方。

方式四：用 make 编译 X5 项目（platform_samples / hbre 模块）

X5 项目的 platform_samples 与 hbre 下各模块的 Makefile 已适配 SDK 环境：检测到 APPSDK_ROOT（由 environment-setup 设置）即进入 SDK 模式，自动把 -I/-L 路径指向 SDK sysroot，产物落到模块自身 out/。

source /opt/platform-appsdk/environment-setup-aarch64-x5-linux

# 编译 platform_samples 下的某个样例
cd platform_samples/sample_dsp
make clean && make
# 产物 sample_dsp（ELF 64-bit, ARM aarch64）

# 编译 hbre 下的某个模块
cd hbre/dsp
make clean && make
# 产物 out/src/libdsp.so.1.0.0（ELF 64-bit, ARM aarch64）

适用范围：

platform_samples：除 sunrise_camera（有独立 config 机制）和 multi_pipe_stereo_infer/client（源码含 -Werror 下不过的 warning）外，其余样例均可在 SDK 环境编译。
hbre：camsys/libcam、camsys/libvpf、dsp、hbutils、libefuse、libhbmem、libipc/libipcfhal、liblog、libmm、libspi/spi-hal、openssl-engine、otaupdate、power-ctl、secure_storage、viotool/libhbplayer 共 15 个模块均可 make 产出 .so 或可执行文件到模块自身 out/。

SDK 模式与原项目模式互斥：未 source environment-setup 时走原项目逻辑，SDK 改动不影响 ./bd.sh 流程。

hbre 模块裸 `make` 的 install 行为

hbre 多数模块的 Makefile.in 把 deb: 设为默认目标且 deb: install，所以裸 make（不带参数）会触发 install。install 产物（dev 软链 libxxx.so + 头文件 xxx.h）写到 $OUTPUT_HBROOTFS_DIR——SDK 模式下指向 ${PWD}/deploy（source 时的当前工作目录下的 deploy/），不污染只读的 SDK sysroot。

# source 时 PWD 决定 deploy 落点
cd ~/myproject && source /opt/platform-appsdk/environment-setup-aarch64-x5-linux
# 此时 OUTPUT_HBROOTFS_DIR=~/myproject/deploy，install 产物落这里

cd hbre/dsp && make
# 编译产物 → hbre/dsp/out/src/libdsp.so.1.0.0
# install 产物 → ~/myproject/deploy/usr/lib/libdsp.so（软链→out/）
#               ~/myproject/deploy/include/xxx.h（软链→源码 include/）

deploy/ 是用户工作区可写目录，可随时 rm -rf deploy/ 清理，不影响 SDK。若不需要 install 产物，用 make src/make build 只编译不安装。

验收 SDK

SDK 自带验收脚本 test-sdk.sh（在总包里），用于确认 SDK 是否完整可用：

bash ./test-sdk.sh /opt/platform-appsdk

预期输出：

[PASS] 1. sysroot points to SDK
[PASS] 2. compile helloworld
[PASS] 2b. helloworld is aarch64
[PASS] 3. link hbre (libcam)
[PASS] 4. link system libssl
[PASS] 5. cmake project builds
[PASS] 6a. version file exists
...
[PASS] 6f. version has Timestamp

Results: 12 passed, 0 failed

全 PASS 说明 SDK 完整可用。

SDK 目录结构

/opt/platform-appsdk/                   # sudo 模式固定路径（无 sudo 模式为用户选的路径下/platform-appsdk/）
├── environment-setup-aarch64-x5-linux   # source 入口（导出 APPSDK_ROOT/SDKTARGETSYSROOT/$CC 等）
├── version-aarch64-x5-linux             # 版本追溯信息
├── Makefile                             # SDK 版 common（hbre/app Makefile.in 通过 SRC_DEVICE_COMMON_DIR include）
├── bin/                                 # 交叉工具链相对路径软链（→ ../arm-gnu-toolchain/bin/，无 wrapper）
├── arm-gnu-toolchain/                   # ARM GNU Toolchain 副本
│   └── bin/
└── sysroots/
    └── aarch64-x5-linux/                # sysroot（编译时 --sysroot 指向这里）
        ├── lib -> usr/lib               # 根级软链（rootfs 布局）
        ├── lib64 -> lib
        ├── include -> usr/include
        └── usr/
            ├── include/                  # 头文件（X5 + libc 合并）
            ├── lib/                      # 库（hbre .so/.so.N + system .so + rootfs 运行库）
            └── lib64/                    # crt 启动文件 + libc（来自工具链 libc）

version 文件

version-aarch64-x5-linux 记录 SDK 的来源追溯信息：

$ cat /opt/platform-appsdk/version-aarch64-x5-linux
Toolchain: arm-gnu-toolchain-11.3.rel1 (gcc 11.3.1)
APPSDK Version: v1.1.2
SDK Pack Timestamp: 20260722134800
HR_TARGET_MODE: debug
system debs (from series):
  dr-system_1.0.0~gcc11.3.1_all.deb
  ...
hbre modules git hashes:
  camsys: fdc59db7
  dsp: 2fa6940
  ...

各字段含义：

Toolchain：SDK 内置的工具链版本与 gcc 版本
APPSDK Version：与 BSP HR_V_VER 对齐的大版本号
SDK Pack Timestamp：SDK 打包时刻（UTC）
HR_TARGET_MODE：打包时的板级模式（debug/release），影响 CFLAGS
system debs (from series)：SDK 的 system 域库来自的 deb 文件名清单
hbre modules git hashes：各 hbre 仓库打包时的 git commit hash

排查”这个 SDK 是从哪个版本打包的”时看这个文件——把内容贴给 SDK 提供方即可定位来源。

常见问题

`source environment-setup` 报错 “must be sourced, not executed”

environment-setup 必须用 source（或 .）加载，不能用 bash 直接执行：

# 错误
bash /opt/platform-appsdk/environment-setup-aarch64-x5-linux

# 正确
source /opt/platform-appsdk/environment-setup-aarch64-x5-linux

用 `sh` source 报错 “requires bash, not sh”

environment-setup 用了 bash 语法，必须用 bash source：

# 错误（dash/sh 不支持）
sh -c '. /opt/platform-appsdk/environment-setup-aarch64-x5-linux'

# 正确
bash -c 'source /opt/platform-appsdk/environment-setup-aarch64-x5-linux'

链接 hbre 库报错 “cannot find -lxxx”

先跑 test-sdk.sh 确认 SDK 完整。若新增应用链接某个 SDK 未包含的库，需联系 SDK 提供方确认该库是否纳入。

SDK 升级后旧版本残留

sudo 模式：sudo dpkg -i <新版本.deb> 自动替换旧文件，无需手动清理
无 sudo 模式：./install.sh <新版本.deb>（选模式 2）自动删旧 platform-appsdk/ 整目录后重装

SDK 移动到别的路径后不能用

sudo 模式装到 /opt/platform-appsdk 是固定路径，不要手动移动。无 sudo 模式如需换路径，在新的路径重新跑 install.sh 即可。

`dpkg -r` 后 environment-setup 还在

这是 dpkg 标准的 conffile 保护机制——conffile（environment-setup-aarch64-x5-linux）被显式标记为配置文件，dpkg -r 时保留它。重新 dpkg -i 安装时：

如果没改过这个文件，dpkg 会用新版本覆盖（看起来像”全新安装”）
如果改过这个文件（比如改了 CFLAGS），dpkg 会保留版本，新版本存为 .dpkg-dist，需要手动合并

如果希望连 conffile 一起彻底删干净，用 sudo dpkg -P platform-appsdk。

重装/升级时 dpkg 询问 environment-setup 如何处理（conffile 冲突）

症状：sudo 模式重装或升级 SDK（sudo dpkg -i platform-appsdk-vX.X.X.deb）时，dpkg 交互式提示：

Configuration file '/opt/platform-appsdk/environment-setup-aarch64-x5-linux'
 ==> Modified (by you or by a script) since installation.
 ==> Package distributor has shipped an updated version.
   What would you like to do about it ?  Your options are:
    Y or I  : install the package maintainer's version
    N or O  : keep your currently-installed version
      D     : show the differences between the versions
      Z     : start a shell to examine the situation
 The default action is to keep your current version.
*** environment-setup-aarch64-x5-linux (Y/I/N/O/D/Z) [default=N] ?

根因：environment-setup-aarch64-x5-linux 被 deb 标记为 conffile（配置文件），dpkg 对 conffile 有保护机制——检测到磁盘文件被修改（md5 与 dpkg 记录不符）且新 deb 带了新版本时，交互式询问如何处理。常见触发场景：

手动编辑过 /opt/platform-appsdk/environment-setup-aarch64-x5-linux（如调 CFLAGS、改路径变量）
旧版 SDK 装着，新版 deb 的 environment-setup 内容有变化

选项含义：

选项	行为	适用场景
`Y` / `I`	用 deb 里的新版本覆盖磁盘版本	没改过 conffile，或想放弃本地修改用新版
`N` / `O`（默认）	保留磁盘上的本地版本	改过 conffile 想保留（如自定义了 CFLAGS）
`D`	显示两版本差异	想先看改了哪些内容再决定
`Z`	启动 shell 检查	想深入排查

解决方案：

没改过 / 想用新版：输入 Y（推荐，确保用最新 environment-setup）
改过想保留：输入 N（默认），保留你的本地修改；之后可手动对比新版本合并需要的部分
想先看差异：输入 D 看清楚再选 Y/N

避免交互式询问：用 DEBIAN_FRONTEND=noninteractive 或 dpkg --force-confold/--force-confnew 跳过提示：

# 保留本地 conffile 版本（非交互，等价默认 N）
sudo DEBIAN_FRONTEND=noninteractive dpkg -i platform-appsdk-v1.1.2.deb
# 或显式指定
sudo dpkg -i --force-confold platform-appsdk-v1.1.2.deb   # 保留旧版本
sudo dpkg -i --force-confnew platform-appsdk-v1.1.2.deb   # 用新版本覆盖

中断安装的恢复：如果在询问处 Ctrl+C 中断，dpkg 会留在 iU（已解包未配置）半安装状态。检查并恢复：

dpkg -l platform-appsdk | tail -1
# 若显示 iU（Unpacked-not-configured）= 半安装，需重新配置：
sudo dpkg --configure platform-appsdk
# 或直接重装一次（这次正常回答 Y/N）：
sudo dpkg -i platform-appsdk-v1.1.2.deb

conffile 保护是 dpkg 标准机制。conffile 被标记为配置文件，重装/升级时 dpkg 比较 md5 判断是否用户改过，改过则交互式询问——不是 bug。

升级 SDK 后需重新 source

升级 SDK（重装 deb）或改动 environment-setup 后，之前已 source 过的 shell 不会自动更新——环境变量在 source 时固化，旧 shell 里 $OUTPUT_HBROOTFS_DIR 还是旧值，继续 make 会用旧变量。验证当前 shell：

echo $OUTPUT_HBROOTFS_DIR
# 应显示 .../deploy；若显示 .../sysroots/aarch64-x5-linux 则是旧环境
# 旧环境需重新 source：
source /opt/platform-appsdk/environment-setup-aarch64-x5-linux

注意事项

工具链版本：SDK 内置 arm-gnu-toolchain-11.3.rel1，工具链升级时需重新打包 SDK。
路径固定：sudo 模式装到 /opt/platform-appsdk 是固定路径，不要手动移动；如需换路径，在新路径重新跑 install.sh。

4.4.3. 根文件系统适配指南

4.4.3.1. 使用 Buildroot 制作根文件系统

Buildroot 源码

预编译的根文件系统

制作 system

制作 initramfs

制作 QT支持包

4.4.3.2. 使用 Multistrap 制作 Ubuntu 根文件系统

预编译的根文件系统

制作 system

4.4.3.3. 使用 APPSDK 进行应用开发

前置条件

SDK 打包者（产出 SDK 的开发者）

SDK 使用者（应用开发者）

打包 SDK

安装 SDK

模式 1：sudo 模式（推荐）

模式 2：无 sudo 模式

升级与卸载

升级

卸载

dpkg -r 与 dpkg -P 详细对比

使用 SDK 编译应用

方式一：直接用 gcc 编译

方式二：CMake 项目

方式三：autotools 项目

方式四：用 make 编译 X5 项目（platform_samples / hbre 模块）

hbre 模块裸 make 的 install 行为

验收 SDK

SDK 目录结构

version 文件

常见问题

source environment-setup 报错 “must be sourced, not executed”

用 sh source 报错 “requires bash, not sh”

链接 hbre 库报错 “cannot find -lxxx”

SDK 升级后旧版本残留

SDK 移动到别的路径后不能用

dpkg -r 后 environment-setup 还在

重装/升级时 dpkg 询问 environment-setup 如何处理（conffile 冲突）

升级 SDK 后需重新 source

注意事项

`dpkg -r` 与 `dpkg -P` 详细对比

hbre 模块裸 `make` 的 install 行为

`source environment-setup` 报错 “must be sourced, not executed”

用 `sh` source 报错 “requires bash, not sh”

`dpkg -r` 后 environment-setup 还在