4.4.3. Root Filesystem Adaptation Guide

4.4.3.1. Creating Root Filesystem with Buildroot

The X5 root filesystem is built using Buildroot, which supports generating two types of root filesystems: initramfs and system.

initramfs: Contains a minimal root filesystem, merged with the Linux Kernel into boot.img. It is mainly used for secure boot and system recovery.
system: A complete root filesystem providing the runtime environment for the system.

Buildroot Source Code

Source repository: https://gitlab.com/buildroot.org/buildroot.git
Version: 2022.08

The system/buildroot/source directory provides scripts and patches for downloading Buildroot and building the rootfs.

.
├── buildroot_packages_2025.02          # Stores downloaded Buildroot package source tarballs to avoid re-downloading during repeated builds
├── build.sh                            # Main script
├── configs                             # Package configuration files
├── framework                           # Output directory
└── hb_patch_buildroot                  # Patches applied by the X5 system on top of the original Buildroot

Note: When using Buildroot for the first time to build a root filesystem, an internet connection is required to download source tarballs. The build.sh script stores these downloaded sources in the buildroot_packages_2025.02 directory (achieved by setting BR2_DL_DIR).

If network instability, slow speed, or download failures occur when downloading packages via default Buildroot configurations, users can manually download required packages from https://archive.d-robotics.cc/buildroot/ and place them into the buildroot_packages_2025.02 directory.

Note: This URL does not contain all Buildroot dependencies, only a subset of packages required for the current development using version 2022.08. For additional software support, please contact D-Robotics technical support, who will update the archive promptly.

Prebuilt Root Filesystems

The current BSP provides prebuilt rootfs images, located at (please note that the version numbers of each image file are subject to the actual version):

# 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 support package
system/buildroot/prebuilt/dr-system-qt5_0.0.1~gcc11.3.1_all.deb

Corresponding Buildroot configuration files are located in system/buildroot/source/configs:

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

Users can modify these configuration files to add or remove packages as needed. Use the following commands for graphical configuration (the original config will be overwritten after saving):

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

Building system

Execute buildroot compilation operation
```
cd system/buildroot/source
./build.sh build x5_system_defconfig <version number> # eg: 0.0.1
```
For example:
```
./build.sh build x5_system_defconfig 0.0.1
```
Note: The last parameter in the create root file system command is the image version number, which can be modified as needed. Finally, the version number will be spliced into the image file name. The compiled root file system image is in the system/buildroot/source/framework/output/images directory, for example:
```
dr-system_0.0.1~gcc11.3.1_all.deb
```

Copy the new image to the preset directory and update the index file When compiling the root file system image required for burning, you need to copy the newly created image file to the system/buildroot/prebuilt/ directory, which is the precompiled system rootfs storage directory mentioned above (note that the version number of each image file is subject to the actual version):

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

At this time, you need to modify the system/buildroot/prebuilt/series file in the same directory and change the old version number to the new version number configured in the previous compilation, for example:

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

Generally, it is recommended to increment the version number in order to facilitate maintenance.

Repackage

Return to the project root directory and execute:
```
./bd.sh system clean
./bd.sh system
```
You can get the new root file system image system.img in the out/product/ directory, which can be used for burning directly.

Building initramfs

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

For example:

./build.sh build x5_initramfs_defconfig 0.0.1

The version description is the same as for building system and will not be repeated.

Building QT Support Package

If Qt5 support is needed in the system, a root filesystem with Qt support (QT Support Package) must be built separately. The build process is identical to that of building system, except that the Qt5-related defconfig is used. The specific steps are as follows:

Execute buildroot compilation operation
```
cd system/buildroot/source
./build.sh build x5_system_qt5_defconfig <version number>  # e.g.: 0.0.1
```
For example:
```
./build.sh build x5_system_qt5_defconfig 0.0.1
```
Note: The last parameter in the build command is the image version number, which can be modified as needed. Finally, the version number will be appended to the image file name. The compiled root filesystem image is in the system/buildroot/source/framework/output/images directory, for example:
```
dr-system-qt5_0.0.1~gcc11.3.1_all.deb
```

Copy the new image to the preset directory and update the index file

When compiling the root filesystem image required for burning, you need to copy the newly created image file to the system/buildroot/prebuilt/ directory, which is the precompiled system rootfs storage directory mentioned above (note that the version number of each image file is subject to the actual version):

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

At this time, you need to modify the system/buildroot/prebuilt/series file in the same directory and change the old version number to the new version number configured in the previous compilation, for example:

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

Generally, it is recommended to increment the version number in order to facilitate maintenance.

Repackage

Return to the project root directory and execute:
```
./bd.sh system clean
./bd.sh system
```
You can get the new root filesystem image system.img in the out/product/ directory, which can be used for burning directly.

4.4.3.2. Use Multistrap to create Ubuntu root file system

X5 supports making Ubuntu-based root file systems via Multistrap. A root file system based on Ubuntu 22.04 (Jammy) is currently provided by default.

Precompiled root file system

The current BSP provides precompiled rootfs, and the storage directory is as follows (note that the version number of each image file is subject to the actual version):

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

The corresponding Multistrap configuration file is located in system/ubuntu/source/configs:

.
└── x5_system_jammy.conf

Users can modify the configuration file and add or delete software packages as needed.

Make system

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

NOTE:
When using Multistrap to create a root file system, you need to connect to the Internet to download the software deb package. By default, the configuration file uses Tsinghua University mirror source as the apt source.
Be sure to use sudo permissions when making jammy's root file system, otherwise you need to install and configure unconfigured software packages one by one after burning the image for the first timedpkg --configure -a

4.4.3.3. Using APPSDK for Application Development

APPSDK (Application SDK, hereafter “SDK”) is a self-contained cross-compilation environment. Application developers do not need to download the full project source code or pre-install arm-gnu-toolchain on the host. After obtaining the SDK deb package, run install.sh to install it, then source environment-setup to activate the environment variables and directly compile X5 applications (it also supports compiling individual libraries in X5 hbre).

The sysroot is taken from the BSP-unpacked rootfs runtime libraries (out/deploy/system) + hbre artifacts + the crt/libc headers shipped with the toolchain. After modifying hbre, the packager only needs to run ./bd.sh hbre && ./bd.sh appsdk to repackage, without rebuilding the Buildroot root filesystem.

The SDK version is aligned with the BSP major version, making it convenient for developers to quickly match the corresponding version.

The SDK contains:

ARM GNU Toolchain copy (e.g. aarch64-none-linux-gnu-gcc)
Cross-toolchain relative symlinks under bin/ (pointing to arm-gnu-toolchain/bin/, no wrapper layer)
Complete sysroot (glibc crt + system library headers and libraries, e.g. OpenSSL 3.x, alsa, dbus, bluez, libdrm, etc.; merged from rootfs runtime libraries + toolchain libc)
hbre libraries (.so and headers for libcam, libvpf, libalog, libhbmem, libdsp, libpowerctl, etc., including versioned runtime symlinks .so.N)
System-domain libraries (libgdcbin, libcjson, libdnn, libgtest, libhpatchz, etc., from the debs referenced by series)
environment-setup-aarch64-x5-linux environment script (use after source)
SDK-version common Makefile (included by hbre/app Makefile.in via SRC_DEVICE_COMMON_DIR)
version-aarch64-x5-linux version tracing information

Prerequisites

SDK Packager (developers producing the SDK)

The machine packaging the SDK requires the full project source and built artifacts:

Full X5 project source code
Already executed ./bd.sh lunch <board> to select the board configuration
system unpacked: ./bd.sh system unpack (produces out/deploy/system/, the source of system-domain libraries for the sysroot; after modifying the root filesystem and rebuilding the dr-system deb, re-run unpack to refresh)
hbre built: ./bd.sh hbre (produces out/build/hbre_deps/ and out/deploy/hbre/)
External toolchain tarball: toolchain/arm-gnu-toolchain-11.3.rel1-x86_64-aarch64-none-linux-gnu.tar.xz

It is recommended to run ./bd.sh once to fully build the entire project source. This can include all the processes mentioned above.

No Buildroot build required — APPSDK does not depend on the Buildroot host sysroot; the sysroot is taken from out/deploy/system (rootfs runtime libraries) + hbre artifacts + toolchain libc merge. After modifying hbre, the packager only needs to run ./bd.sh hbre && ./bd.sh appsdk to repackage.

If the above artifacts are not ready, ./bd.sh appsdk will report an error and prompt the corresponding prerequisite command.

SDK User (application developers)

The application developer’s environment only needs:

Ubuntu 22.04 (or other Linux distributions)
build-essential, cmake, file (required by the verification script; recommended for general development too)
No /opt/arm-gnu-toolchain needed (the SDK is self-contained)

On Ubuntu, install the above dependencies with one apt command:

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

Packaging the SDK

Run in the project root directory (after ./bd.sh lunch <board> to select the board):

./bd.sh appsdk

The version is automatically extracted from the BSP major version HR_V_VER (exported by device/horizon/x5/dr_release_version.mk, e.g. _V1.1.2) and lower-cased (v1.1.2), no manual specification needed.

Clean SDK artifacts:

./bd.sh appsdk clean       # Clean SDK artifacts under out/deploy/appsdk/images/ (equivalent to distclean)

After a successful build, the artifacts are in the out/deploy/appsdk/images/ directory:

out/deploy/appsdk/images$ ls platform-appsdk-*
platform-appsdk-v1.1.2.deb         # SDK body (deb format, contains all SDK files)
platform-appsdk-v1.1.2.tar.gz      # Bundle (contains deb + install.sh + relocate-paths.sh + test-sdk.sh)

Artifact name format: platform-appsdk-<sdk_version>. sdk_version is extracted from HR_V_VER and lower-cased (e.g. _V1.1.2 → v1.1.2), managed by the BSP version.

The tar.gz bundle contains four artifacts:

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

Application developers only need the tar.gz bundle.

Installing the SDK

Copy the tar.gz bundle to the application developer’s machine, extract it, and run the install script:

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

install.sh interactively asks for the install mode:

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

Mode 1: sudo mode (recommended)

After the user selects 1, install.sh runs sudo dpkg -i (sudo itself will prompt for the password):

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

Installed to the fixed path /opt/platform-appsdk
Managed by dpkg for upgrade and uninstall
source path is fixed, usable from any directory

Mode 2: no-sudo mode

After the user selects 2, install.sh interactively reads the install path and uses dpkg-deb -x to extract to the specified path:

Install path [./]:
# SDK extracted to ./platform-appsdk/

No sudo permission required
Install path is customizable
Note: Do not place personal files inside the platform-appsdk/ directory (the entire directory is deleted and reinstalled on upgrade)

Upgrade and Uninstall

Upgrade

sudo mode:

sudo dpkg -i platform-appsdk-v2.0.0.deb    # dpkg automatically replaces old files

dpkg automatically handles new/old file replacement, no manual cleanup needed. If the new version modified environment-setup, dpkg uses the conffile protection mechanism to decide whether to overwrite it.

no-sudo mode:

./install.sh platform-appsdk-v2.0.0.deb    # Select mode 2, automatically deletes the old directory + extracts the new deb

The implementation removes the entire old platform-appsdk/ directory with rm -rf and then reinstalls. Therefore, users must not place any personal files inside platform-appsdk/ — they will be deleted during upgrade.

Uninstall

sudo mode:

sudo dpkg -r platform-appsdk        # Soft uninstall: keeps conffile (environment-setup)
sudo dpkg -P platform-appsdk        # Full uninstall: removes conffile too

no-sudo mode:

./install.sh --uninstall <install path>
# Only deletes SDK files; user code (not inside platform-appsdk/) is preserved

`dpkg -r` vs `dpkg -P` Detailed Comparison

Dimension	`sudo dpkg -r platform-appsdk` (Remove)	`sudo dpkg -P platform-appsdk` (Purge)
Regular files	Deleted	Deleted
conffile (environment-setup)	Kept	Deleted
dpkg database info	`/var/lib/dpkg/info/<pkg>.*` kept	`/var/lib/dpkg/info/<pkg>.*` all deleted
dpkg state change	`ii` → `rc` (removed, config-files remain)	`ii` → `un`/`pn` (unknown/purged, not installed)
postrm trigger	`postrm remove`	`postrm remove` + `postrm purge`
Can `dpkg -i` reinstall	Yes	Yes

Key difference: conffile protection mechanism — dpkg uses the conffiles mechanism to protect user-modified configuration files:

After uninstalling with dpkg -r:
  /opt/platform-appsdk/environment-setup-aarch64-x5-linux   ← still present
  /opt/platform-appsdk/sysroot/...                            ← deleted

  Reinstall with dpkg -i platform-appsdk-v1.1.2.deb:
    1. Compute conffile md5
    2. Compare with .dpkg-new (new version file):
       - User unchanged conffile (md5 matches) → overwrite with new version
       - User modified conffile (md5 mismatch) → keep user version, new version saved as conffile.dpkg-dist
       - User deleted conffile → dpkg handles silently
    3. dpkg state: rc → ii

Usage recommendations:

Temporary uninstall, will reinstall: sudo dpkg -r (keeps conffile; on reinstall, if unchanged, it is overwritten by the new version)
Full cleanup, fresh install: sudo dpkg -P (removes conffile too; reinstall equals first-time install)
Upgrade to a new version: sudo dpkg -i <new.deb> (dpkg automatically does remove + install, equivalent to -r + install)

Verification suggestions:

# 1. Check dpkg state after install
dpkg -l platform-appsdk
# Expected: ii  platform-appsdk  1.1.2

# 2. Check state after dpkg -r
sudo dpkg -r platform-appsdk
dpkg -l platform-appsdk
# Expected: rc  platform-appsdk  1.1.2    ← rc = removed, config-files
ls /opt/platform-appsdk/environment-setup-aarch64-x5-linux
# Expected: file still present

# 3. Check state after dpkg -P
sudo dpkg -P platform-appsdk
dpkg -l platform-appsdk
# Expected: un <no description>  (or not found)
ls /opt/platform-appsdk/environment-setup-aarch64-x5-linux
# Expected: No such file or directory

Compiling Applications with the SDK

Method 1: Compile directly with gcc

After source environment-setup, environment variables such as CC, CXX, CFLAGS, LDFLAGS, and SDKTARGETSYSROOT are all set (CC already includes --sysroot and arch parameters). Just compile with $CC/$CXX:

# source the environment script (run source once per new shell)
source /opt/platform-appsdk/environment-setup-aarch64-x5-linux

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

$CC hello.c -o hello

# Verify the artifact architecture
file hello
# hello: ELF 64-bit LSB executable, ARM aarch64, ...

# Link hbre libraries (e.g. libcam)
$CC app.c -o app -lcam -lvpf -lgdcbin

# Link system libraries (e.g. OpenSSL)
$CC app.c -o app -lssl -lcrypto

# C++ project uses $CXX
$CXX app.cpp -o app -lstdc++

# libdrm: headers are in the include/libdrm subdirectory, needs explicit -I
$CC app.c -o app -I${SDKTARGETSYSROOT}/usr/include/libdrm -ldrm

The full value of CC is aarch64-none-linux-gnu-gcc -mcpu=cortex-a55 -mabi=lp64 --sysroot=<SDK sysroot>, which already includes the cross-compiler, sysroot, and arch parameters — just use $CC directly.

CFLAGS follows HR_TARGET_MODE: debug mode uses -O0 -g, release mode uses -O2, consistent with the BSP build/common/Makefile.

Method 2: CMake projects

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

mkdir build && cd build
cmake ..
make

APPSDK does not ship a toolchainfile.cmake; CMake projects use the $CC configured by environment-setup. Specify the compiler and flags via environment variables in CMakeLists.txt:

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)

Method 3: autotools projects

The host needs the autotools toolchain: 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 sets CONFIGURE_FLAGS (including --target, --host, --build, --with-libtool-sysroot), which autotools projects automatically use when running ./configure.

If a project uses PKG_CHECK_MODULES([...],[libdrm]) to detect system libraries, configure will fail with Package 'libdrm' not found (the sysroot has no libdrm.pc). The SDK ships no .pc; setting <PREFIX>_CFLAGS/<PREFIX>_LIBS env does NOT bypass the check (the macro still calls pkg-config --exists). Handle per-project (e.g., preset cache variables pkg_cv_<PREFIX>_CFLAGS/_LIBS, PKG_CONFIG=true ./configure, or patch configure.ac); the mechanism must be tested — this guide gives no fixed recipe.

Method 4: Build X5 projects with make (platform_samples / hbre modules)

The Makefiles of X5’s platform_samples and modules under hbre are adapted for the SDK environment: upon detecting APPSDK_ROOT (set by environment-setup), they enter SDK mode, automatically point -I/-L paths to the SDK sysroot, and place artifacts in the module’s own out/.

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

# Build a sample under platform_samples
cd platform_samples/sample_dsp
make clean && make
# Artifact sample_dsp (ELF 64-bit, ARM aarch64)

# Build a module under hbre
cd hbre/dsp
make clean && make
# Artifact out/src/libdsp.so.1.0.0 (ELF 64-bit, ARM aarch64)

Applicable scope:

platform_samples: Except sunrise_camera (has an independent config mechanism) and multi_pipe_stereo_infer/client (source contains warnings that fail under -Werror), all other samples can be built in the SDK environment.
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 modules in total — can all make produce .so or executables into the module’s own out/.

SDK mode and the original project mode are mutually exclusive: without sourcing environment-setup, the original project logic is used; SDK changes do not affect the ./bd.sh flow.

Install behavior of bare `make` for hbre modules

Most hbre modules’ Makefile.in sets deb: as the default target with deb: install, so a bare make (no arguments) triggers install. Install artifacts (dev symlinks libxxx.so + headers xxx.h) are written to $OUTPUT_HBROOTFS_DIR — in SDK mode this points to ${PWD}/deploy (the deploy/ under the working directory at source time), not polluting the read-only SDK sysroot.

# PWD at source time determines where deploy lands
cd ~/myproject && source /opt/platform-appsdk/environment-setup-aarch64-x5-linux
# Now OUTPUT_HBROOTFS_DIR=~/myproject/deploy; install artifacts land here

cd hbre/dsp && make
# Build artifact → hbre/dsp/out/src/libdsp.so.1.0.0
# Install artifact → ~/myproject/deploy/usr/lib/libdsp.so (symlink → out/)
#                    ~/myproject/deploy/include/xxx.h (symlink → source include/)

deploy/ is a writable user-workspace directory; you can rm -rf deploy/ at any time without affecting the SDK. If you don’t need install artifacts, use make src/make build to compile without installing.

Verifying the SDK

The SDK ships a verification script test-sdk.sh (in the bundle) to confirm the SDK is complete and usable:

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

Expected output:

[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

All PASS means the SDK is complete and usable.

SDK Directory Structure

/opt/platform-appsdk/                   # Fixed path for sudo mode (no-sudo mode: <chosen path>/platform-appsdk/)
├── environment-setup-aarch64-x5-linux   # source entry (exports APPSDK_ROOT/SDKTARGETSYSROOT/$CC, etc.)
├── version-aarch64-x5-linux             # Version tracing info
├── Makefile                             # SDK-version common (included by hbre/app Makefile.in via SRC_DEVICE_COMMON_DIR)
├── bin/                                 # Cross-toolchain relative symlinks (→ ../arm-gnu-toolchain/bin/, no wrapper)
├── arm-gnu-toolchain/                   # ARM GNU Toolchain copy
│   └── bin/
└── sysroots/
    └── aarch64-x5-linux/                # sysroot (--sysroot points here at compile time)
        ├── lib -> usr/lib               # Top-level symlinks (rootfs layout)
        ├── lib64 -> lib
        ├── include -> usr/include
        └── usr/
            ├── include/                  # Headers (X5 + libc merged)
            ├── lib/                      # Libraries (hbre .so/.so.N + system .so + rootfs runtime libs)
            └── lib64/                    # crt startup files + libc (from toolchain libc)

version File

version-aarch64-x5-linux records the SDK’s source tracing info:

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

Field meanings:

Toolchain: Toolchain version and gcc version built into the SDK
APPSDK Version: Major version aligned with the BSP HR_V_VER
SDK Pack Timestamp: SDK packaging time (UTC)
HR_TARGET_MODE: Board mode at packaging time (debug/release), affects CFLAGS
system debs (from series): List of deb file names that the SDK’s system-domain libraries come from
hbre modules git hashes: Git commit hash of each hbre repository at packaging time

When investigating “which version this SDK was packaged from”, check this file — paste its content to the SDK provider to locate the source.

FAQ

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

environment-setup must be loaded with source (or .), not executed directly with bash:

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

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

Using `sh` to source reports “requires bash, not sh”

environment-setup uses bash syntax and must be sourced with bash:

# Wrong (dash/sh unsupported)
sh -c '. /opt/platform-appsdk/environment-setup-aarch64-x5-linux'

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

Linking hbre libraries reports “cannot find -lxxx”

Run test-sdk.sh first to confirm the SDK is complete. If a new application links a library not included in the SDK, contact the SDK provider to confirm whether that library is included.

Old version residue after SDK upgrade

sudo mode: sudo dpkg -i <new-version.deb> automatically replaces old files, no manual cleanup needed
no-sudo mode: ./install.sh <new-version.deb> (select mode 2) automatically deletes the old platform-appsdk/ directory and reinstalls

SDK does not work after moving to another path

sudo mode installs to /opt/platform-appsdk, a fixed path — do not move it manually. For no-sudo mode, to change the path, re-run install.sh at the new path.

environment-setup still present after `dpkg -r`

This is dpkg’s standard conffile protection mechanism — the conffile (environment-setup-aarch64-x5-linux) is explicitly marked as a configuration file, and dpkg keeps it during -r. When reinstalling with dpkg -i:

If you did not modify this file, dpkg overwrites it with the new version (looks like a “fresh install”)
If you modified this file (e.g. changed CFLAGS), dpkg keeps your version and saves the new version as .dpkg-dist, requiring manual merge

If you want to completely remove the conffile too, use sudo dpkg -P platform-appsdk.

dpkg asks how to handle environment-setup during reinstall/upgrade (conffile conflict)

Symptom: When reinstalling or upgrading the SDK in sudo mode (sudo dpkg -i platform-appsdk-vX.X.X.deb), dpkg interactively prompts:

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

Root cause: environment-setup-aarch64-x5-linux is marked as a conffile (configuration file) in the deb. dpkg has a protection mechanism for conffiles — when it detects the on-disk file was modified (md5 mismatch with dpkg’s record) and the new deb ships a new version, it interactively asks how to handle it. Common trigger scenarios:

Manually edited /opt/platform-appsdk/environment-setup-aarch64-x5-linux (e.g. tuned CFLAGS, changed path variables)
An old SDK version is installed and the new deb’s environment-setup content differs

Option meanings:

Option	Behavior	Applicable scenario
`Y` / `I`	Overwrite the disk version with the new version from the deb	You didn't modify the conffile, or want to discard local changes and use the new version
`N` / `O` (default)	Keep the local on-disk version	You modified the conffile and want to keep it (e.g. customized CFLAGS)
`D`	Show the diff between the two versions	Want to see what changed before deciding
`Z`	Start a shell to inspect	Want to investigate further

Solutions:

Didn’t modify / want the new version: Enter Y (recommended, ensures the latest environment-setup)
Modified and want to keep: Enter N (default) to keep your local changes; afterwards you can manually diff against the new version and merge needed parts
Want to see the diff first: Enter D to review, then choose Y/N

Avoiding the interactive prompt: Use DEBIAN_FRONTEND=noninteractive or dpkg --force-confold/--force-confnew to skip the prompt:

# Keep the local conffile version (non-interactive, equivalent to default N)
sudo DEBIAN_FRONTEND=noninteractive dpkg -i platform-appsdk-v1.1.2.deb
# Or specify explicitly
sudo dpkg -i --force-confold platform-appsdk-v1.1.2.deb   # Keep the old version
sudo dpkg -i --force-confnew platform-appsdk-v1.1.2.deb   # Overwrite with the new version

Recovery from an interrupted install: If you Ctrl+C at the prompt, dpkg stays in the iU (unpacked-not-configured) half-installed state. Check and recover:

dpkg -l platform-appsdk | tail -1
# If it shows iU (Unpacked-not-configured) = half-installed, reconfigure:
sudo dpkg --configure platform-appsdk
# Or just reinstall once (answer Y/N normally this time):
sudo dpkg -i platform-appsdk-v1.1.2.deb

conffile protection is a standard dpkg mechanism. The conffile is marked as a configuration file; on reinstall/upgrade, dpkg compares md5 to determine whether the user modified it — if modified, it prompts interactively. This is not a bug.

Need to re-source after upgrading the SDK

After upgrading the SDK (reinstalling the deb) or modifying environment-setup, shells that were previously sourced do not auto-update — environment variables are fixed at source time. In an old shell, $OUTPUT_HBROOTFS_DIR still holds the old value; continuing to make uses the old variable. Verify the current shell:

echo $OUTPUT_HBROOTFS_DIR
# Should show .../deploy; if it shows .../sysroots/aarch64-x5-linux, it's the old environment
# For the old environment, re-source:
source /opt/platform-appsdk/environment-setup-aarch64-x5-linux

Notes

Toolchain version: The SDK ships arm-gnu-toolchain-11.3.rel1; when the toolchain is upgraded, the SDK must be repackaged.
Fixed path: sudo mode installs to /opt/platform-appsdk, a fixed path — do not move it manually; to change the path, re-run install.sh at the new path.