Platform: RK3128 / RK3288 / RK3399 / RK3566 / RK3568 | OS: Android 7.1 / 11 / 14 / 16, Linux Buildroot / Debian | Module: Build System / Toolchain / Dependencies / Repositories

I. Background

Both Rockchip's Android and Linux SDKs are assembled from multi-layered build systems. The top layer consists of build.sh, envsetup.sh and lunch, which select the SoC, board and build variant; the middle layer is Buildroot's package framework or Android's Soong/Ninja; the bottom layer invokes the kernel, U-Boot, Debian or Ubuntu packaging scripts. If any layer is missing a host tool, cannot download a source package, or has an incomplete source tree, the failure ultimately surfaces as a failing recipe.

A characteristic of such errors is that on-site logs usually only show the last failed command, while the real cause lies in an earlier dependency-check or code-sync stage. The cases summarized in this document span Android 7.1 to Android 16 and the Buildroot and Debian build lines, and are categorized into five types: missing dependencies, download failures, incomplete source trees, wrong configuration, and version incompatibility—so that during troubleshooting you can locate the layer first instead of modifying source code directly.

II. Problem Symptoms

The most common symptom on the Buildroot side is that a command is reported missing during the install stage. Some RK3288 projects stall at "Installing to target" when building libmali, with "patchelf: command not found" appearing repeatedly in the log, followed by failure of the .stamp_target_installed target with Error 127. After switching to the "Installing to staging" stage the error location changes, but the cause is the same.

Another frequent symptom is download failure. When building the rootfs for RK3568 and RK3399, packages such as noto-sans-sc, source-han-sans-cn and linux-HEAD repeatedly return 404; accessing raw.githubusercontent.com even resolves to 0.0.0.0 and the connection is refused. Some projects manually place the source package into the build directory, but it still fails because Buildroot only recognizes the cached files under the dl directory.

In the kernel and Debian stages, the symptom is missing header files or tools. Building the Linux kernel on RK3588 reports a missing gmp header; when building the 6.1 kernel for RK3566 Android 14, the libbpf code in resolve_btfids cannot find libelf.h or gelf.h. The Debian packaging stage also reports live-build version mismatch, qemu-aarch64-static not registered, debootstrap command not found, and the bookworm directory not existing.

Wrong configuration causes build errors that appear unrelated to configuration. An RK3128 tablet project mistakenly used the rk3128_box lunch, so NATIVE_HANDLE_TYPE was undefined in the Camera HAL; after modifying the kernel on RK3288 and running make recovery-rebuild directly, it reported curl.h not found and could not find lcurl, whereas running build.sh recovery alone worked fine. The Android 16 merge flow reports an incompatible outputmanager HAL instance at the check_target_files_vintf stage. Another project deleted .repo and rebuilt the git repository, after which Soong reported that the module source path for multiple Android.bp files does not exist.

III. Root Cause Analysis

The first type is missing host dependencies. Each Buildroot package runs in a fixed order of configure, build and install; any tool invoked by the install hook must already be in the host's PATH. libmali's packaging script uses patchelf to modify the SONAME and dependency names; when it is not installed on the host, the script exits at the first loop, and Buildroot treats this non-zero return value as a package install failure.

/* W:/external/libmali/scripts/normalize.sh */
SONAME=libmali.so.1
LIBS=$(find optimize_*/ -name "*.so")

for lib in $LIBS; do
    DEPS=$(readelf -d $lib)
    for dep in libffi.so libcrypto.so; do
        DEP=$(echo $DEPS | grep -oE "$dep.[0-9]*")
        [ -z "$DEP" ] || patchelf $lib --replace-needed $DEP $dep
    done
    echo $DEPS | grep -q "Library soname: \[$SONAME\]" ||
        patchelf --set-soname $SONAME $lib
done

Buildroot's target install target only executes these commands in order and stops when a command fails; it does not automatically supply the missing tool. Therefore the Error 127 seen in the log is a result, not the root cause. The check-package.sh provided by the Linux SDK follows the same idea: it first uses which to check the command, then gives an apt install hint, and exits directly if the check fails.

/* W:/buildroot/package/pkg-generic.mk */
$(BUILD_DIR)/%/.stamp_target_installed:
    $(Q)touch $($(PKG)_DIR)/.stamp_installed
    @$(call step_start,install-target)
    @$(call MESSAGE,"Installing to target")
    $(Q)$(call run_commands,target_install, PRE_INSTALL_TARGET \
        $($(PKG)_PRE_INSTALL_TARGET_HOOKS) \
        $(PKG)_INSTALL_TARGET_CMDS \
        $($(PKG)_POST_INSTALL_TARGET_HOOKS) POST_INSTALL_TARGET)

The second type is an unreachable download source. Buildroot's download logic tries PRIMARY_SITE, the package's own SITE, and BACKUP_SITE in order; when one address fails it does not stop and wait for manual handling, but continues to the next candidate. The problem is that some packages' SITE points to an overseas server; when it cannot be reached from the domestic network, there is also no usable mirror in the candidate list, and it finally ends with 404 or a connection refusal. The SITE for the font package noto-sans-sc is Google's storage address.

/* W:/buildroot/package/noto/noto-sans-sc/noto-sans-sc.mk */
NOTO_SANS_SC_VERSION = 1.1
NOTO_SANS_SC_SOURCE = NotoSansSC.zip
NOTO_SANS_SC_SITE = https://noto-website-2.storage.googleapis.com/pkgs
NOTO_SANS_SC_LICENSE = OFL-1.1

After Buildroot finishes downloading, it places the file into DL_DIR, and subsequent builds only consult this directory; it does not re-recognize content manually extracted into the build directory. Therefore, extracting NotoSansSC.zip, renaming it to noto-sans-sc-1.1 and placing it into output/.../build still triggers a re-download and failure; the correct location is buildroot/dl. Once the caching semantics of DL_DIR are understood, this kind of 404 can be resolved by placing the source package offline.

The third type is an incomplete source tree. When Android's Soong parses Android.bp, it checks whether each module's declared source file path exists, and reports "module source path does not exist" if it does not. Some projects deleted .repo in order to migrate the repository, and after re-running git init only committed the non-ignored files; the .git directory of librga, the third-party source of angle, and a large number of prebuilt files excluded by .gitignore never entered the new repository, so Soong fails immediately when it resolves these paths.

/* Z:/rk3588_android12/build/soong/android/paths.go */
func (p Path) checkExists() {
    if _, err := os.Stat(p.String()); err != nil {
        if os.IsNotExist(err) {
            ReportPathErrorf(ctx, "module source path %q does not exist", p)
        }
    }
}

Missing header files on the kernel side belong to the same category, except the check happens on the kernel's own host tools. When compiling the 6.1 kernel, resolve_btfids links libbpf; the Makefile queries libelf's compile flags and link libraries via pkg-config. When the libelf dev package is not installed on the host, the query returns empty and the source file containing libelf.h fails to compile directly. gmp headers, and Debian's live-build and debootstrap follow the same dependency chain.

/* W:/kernel-6.1/tools/bpf/resolve_btfids/Makefile */
LIBELF_FLAGS := $(shell $(HOSTPKG_CONFIG) libelf --cflags 2>/dev/null)
LIBELF_LIBS  := $(shell $(HOSTPKG_CONFIG) libelf --libs 2>/dev/null || echo -lelf)

HOSTCFLAGS_resolve_btfids += -g \
          -I$(srctree)/tools/include \
          -I$(srctree)/tools/include/uapi \
          -I$(LIBBPF_INCLUDE) \
          -I$(SUBCMD_INCLUDE) \
          $(LIBELF_FLAGS)

LIBS = $(LIBELF_LIBS) -lz

The fourth type is wrong configuration. lunch determines TARGET_PRODUCT, which in turn determines which set of BoardConfig, device.mk and Camera HAL to load. After an RK3128 tablet mistakenly selected the box configuration, the Camera HAL got a different set of macro definitions, NATIVE_HANDLE_TYPE was not introduced, and the build naturally failed. The Linux SDK's recovery build is similar: envsetup.sh selects the entire rootfs configuration, and after selecting the wrong one Buildroot uses a different defconfig; the curl that recovery depends on is not compiled into the sysroot, resulting in a missing curl.h and an inability to find lcurl.

The fifth type is version incompatibility. Android 16 maintains the device manifest and the framework compatibility matrix separately; when merge_target_files merges system and vendor it runs check_target_files_vintf. The device side declares an IRkOutputManager instance of rockchip.hardware.outputmanager, but there is no corresponding entry in the framework compatibility matrix, so the check judges it INCOMPATIBLE. The patch must be added as a complete hal section; changing only one line or writing it in the wrong place triggers an assemble_vintf format parsing error, indicating that the root element is not a manifest or the version cannot be parsed. The local source tree is Android 12 and does not include Android 16's rockchip_generic directory; here we only reference the generic assemble_vintf entry point to explain its validation mechanism.

 IV. Remediation

For dependency-missing issues, install the package directly based on the command name in the log. patchelf can be installed via apt; when the kernel reports missing gmp, install libgmp-dev, and when it reports missing libelf.h or gelf.h, install libelf-dev. Debian packaging requires live-build, qemu-user-static and debootstrap; after installation you must also re-register qemu-aarch64 with update-binfmts, otherwise cross execution will still fail. It is recommended to run the SDK's built-in dependency-check script before compiling, to fix all missing items at once.

For download-failure issues, resolve the network first, then place the package offline. After confirming access, run a full repo sync; when access is not possible, place the corresponding version's source package into buildroot/dl using the file name expected by Buildroot, then recompile. Note that the package name and version number must match the SITE and SOURCE variables; placing it in the wrong directory or with the wrong file name will not be recognized. Do not bypass the download by deleting the package configuration, as this also removes the dependency and may cause missing functionality later.

For incomplete-source-tree issues, the premise is to preserve .repo. The .repo in the SDK delivery package stores both the manifest and the git metadata of each repository; once deleted, neither Soong nor Buildroot can tell which files belong to the source. When migrating to your own repository, you should fully preserve .git and the untracked prebuilt files, or use the official SDK sync directly and then layer your own commits on top. For projects that have already been deleted, you can copy the original .repo and the missing .git directories back, then run a full sync.

For configuration issues, first verify lunch and the build target. When tablets and boxes use different SDKs, their lunch settings must not be mixed; when building recovery only, select the recovery lunch, and when building a normal rootfs switch back to the normal configuration—do not use the two interchangeably within the same build. Recompiling recovery after modifying the kernel is a normal flow, but the above configuration switch must be followed; you cannot directly reuse the previous rootfs output.

For version-incompatibility issues, complete the matrix according to the error. Android 16's outputmanager needs a complete optional AIDL hal section added to frameworks_compatibility_matrix.xml, declaring the name, version, interface and instance; after modification, delete out and do a full rebuild. If an unknown format or root name mismatch appears after the modification, it means the patch was added to the wrong file or wrong level; you should go back to the original template and compare the structure, rather than continuing to change the version field.

V. Scope and Upgrade Recommendations

This document covers the Android 7.1 to Android 16 builds of RK3128, RK3288, RK3399, RK3566 and RK3568, as well as Linux Buildroot and Debian builds. The dependency-check script, Buildroot's DL_DIR mechanism, and the lunch selection logic are basically consistent across versions; the VINTF matrix split and the outputmanager declaration method only appear in the SSI flow after Android 14, and older versions have no corresponding files. The Linux scripts referenced in this document come from the local Linux SDK; the Android 12 source tree does not contain Android 14/16's rockchip_generic configuration, so when porting you should verify the paths against the actual version.

When upgrading the SDK, it is recommended to first rebuild the build environment according to the release notes, confirming that the Ubuntu version, dependency packages and disk space meet the requirements, and then run a full sync. When encountering an error, first determine whether it belongs to environment, network, source tree, or configuration—do not modify the source code or delete directories right away. New SDKs usually already include dependency checks and clearer hints; when upgrading old projects you can bring these check scripts along to reduce the recurrence of similar problems.

Article shared from the Internet

ONE MORE THING

Thinkcore Team is an embedded board solution provider, developer, and motherboard supplier, specializing in the design, manufacturing, sales, and technical sharing of embedded motherboards. Our chipset portfolio includes Rockchip, Allwinner, and others. We welcome inquiries and collaboration!

mail:  developer@thinkcore.cn