11. Debian root file system build¶

With the help of LubanCat-SDK, we can easily build Debian images with one click, but the construction process of Debian root file system is relatively independent and does not depend on other parts of the SDK.

The Debian root file system is built with live build, a set of scripts used to build live system images. live build is a tool suite that uses a configuration directory to fully automate and customize all aspects of building live images.

In addition to live build, our Debian build repository also has many build scripts, which can minimize manual operations and make the built root file system consistent.

注解

The Debian build project used by LubanCat-SDK has the same function as the Debian image we provide. It is recommended that users directly use the root file system image we built. For specific usage methods and download address, please see the LubanCat-SDK construction chapter.

11.1. Debian system support¶

11.1.1. LubanCat-RK356x¶

Only support Debian 10 “Buster”。

lite ~No desktop version
xfce4 ~Desktop version
xfce4-full ~Desktop version with additional plugins

11.1.2. LubanCat-RK3588¶

Only Debian 11 “Bullseye” is supported.

lite ~No desktop version
gnome ~Desktop version (default desktop)
xfce ~Desktop version (no technical support)
lxde ~Desktop version (no technical support)

11.2. What is Debian¶

The following document uses Debian10 as an example for demonstration. The content of Debain11 is similar. If you use Debain11, just replace “debain11” and “buster” in the relevant content or scripts with “debain11” and “bullseye”

Debian GNU/Linux (Debian for short) is one of the largest non-commercial Linux distributions in the world. It is a completely free and open Linux operating system that is widely used in various devices.

Features of Debian:

Debian for users
- Debian is free software that everyone can freely use, modify, and distribute.
- Stable and safe.
- Extensive hardware support.
- Provides smooth updates.
- The basis for many other distributions.
- The Debian project is a community.
Debian for developers
- Supports multiple hardware architectures, including AMD64, i386, ARM and MIPS, etc.
- Supports IoT and embedded devices
- Has a large number of packages, using deb format
- Different releases
- Public bug tracking system

Debian Official website:https://www.debian.org/

11.3. Debian root filesystem build repository¶

The complete Debian root file system construction project is already included in the LubanCat-SDK we released, which is saved in the debain directory of the SDK.

Enter the debian directory and there are the following files

ls -hgG

-rwxrwxr-x  1 1.1K 3月  10 11:04 mk-base-debian.sh
-rwxrwxr-x  1 8.1K 3月  10 11:25 mk-buster-rootfs.sh
-rwxrwxr-x  1  477 3月  10 10:49 mk-image.sh
-rwxrwxr-x  1  441 12月 26 15:18 mk-rootfs.sh
drwxrwxr-x  7   67 11月 30 11:19 overlay
drwxrwxr-x  5   49 11月 30 11:19 overlay-debug
drwxrwxr-x  4   28 11月 30 11:19 overlay-firmware
drwxrwxr-x  3   19 11月 30 11:19 packages
drwxrwxr-x  5   47 11月 30 11:19 packages-patches
-rwxrwxr-x  1 3.0K 11月 30 11:19 post-build.sh
-rw-rw-r--  1 2.6K 3月  10 11:17 readme.md
drwxrwxr-x  7  164 11月 30 11:19 ubuntu-build-service

mk-base-debian.sh: Clean the build directory and call live build to start the build.
mk-buster-rootfs.sh: Add Rockchip overlay layer.
mk-image.sh: Package the root file system into an img image file
overlay: Rockchip overlay layer, mainly the configuration file in rootfs
overlay-debug: Rockchip overlay layer, mainly debug scripts and tools
overlay-firmware: Rockchip overlay layer, mainly wifi/bt/npu firmware
packages: Hardware acceleration package
ubuntu-build-service: Dependency files and live build configuration files used to build the build environment

Currently the build script supports three versions of image building

lite: No desktop, terminal version
xfce: Use the desktop version of the xfce suite
xfce-full: Desktop version using xfce suite + more recommended packages

11.4. Debian root file system build process¶

The construction of the Debian root file system is mainly divided into three steps:

Step 1: Use the live build tool to build the lite-debian or xfce-debian root file system. Implemented using the mk-base-debian.sh script.

Step 2: Add software packages that enhance functions based on the RK processor, such as GPU drivers and hardware firmware. Use the mk-buster-rootfs.sh script to implement.

Step 3: Package the built root file system into img format to facilitate burning and next step processing. Implemented through the mk-image.sh script, which is automatically called after the second step is completed.

11.5. Set up the build environment¶

Execute the following command in the debian directory

sudo apt-get install binfmt-support qemu-user-static
sudo dpkg -i ubuntu-build-service/packages/*
sudo apt-get install -f

There may be warnings or errors during the execution of the above command. This is normal. We can directly ignore the error.

11.6. Build a Debian root file system mirror image¶

In the Ubuntu-Build-Service directory, some preset files of Live Build have been saved according to the LITE or XFCE version, ARMHF or ARM64 architecture, such as software packages, user names, passwords, user groups, time zones, etc.

We used mk-base-debian.sh script to call Live Build to build the corresponding Debian root file system.

The theoretically generated root file system can already run on our board and card, but it has not been added to the configuration for board cards, such as networks, display, etc., and can only run core services.

Let’s take a look at the specific construction process:

11.6.1. Construct a Debian-Base basic root file system¶

We run the following command in the Debian directory

1	./mk-base-debian.sh

Select the Debian version to be constructed. Here we choose the XFCE version, input 2 and press the Enter button, and input the user password according to the prompt.

---------------------------------------------------------
please enter TARGET version number:
[0] Exit Menu
[1] lite
[2] xfce
[3] xfce-full
---------------------------------------------------------
2

The entire construction time is long, and after the order of the command is over, we can see the file changes in the Debian directory:

ls -hgG

-rw-rw-rw-  1 370M 3月  10 14:04 linaro-buster-xfce-alip-20230418.tar.gz
-rwxrwxr-x  1 1.1K 3月  10 11:04 mk-base-debian.sh
-rwxrwxr-x  1 8.1K 3月  10 11:25 mk-buster-rootfs.sh
-rwxrwxr-x  1  477 3月  10 10:49 mk-image.sh
-rwxrwxr-x  1  441 12月 26 15:18 mk-rootfs.sh
drwxrwxr-x  7   67 11月 30 11:19 overlay
drwxrwxr-x  5   49 11月 30 11:19 overlay-debug
drwxrwxr-x  4   28 11月 30 11:19 overlay-firmware
drwxrwxr-x  3   19 11月 30 11:19 packages
drwxrwxr-x  5   47 11月 30 11:19 packages-patches
-rwxrwxr-x  1 3.0K 11月 30 11:19 post-build.sh
-rw-rw-r--  1 2.6K 3月  10 11:17 readme.md
drwxrwxr-x  7  164 11月 30 11:19 ubuntu-build-service

The newly added file linaro-buster-xfce-alip-20230418.tar.gz is the compressed package of the basic Debian root file system that has just been built through live build.

11.6.2. Build a complete Debian root file system¶

The root file system built by the previous step can already be run on the board card. In order to further optimize the effect of running on Lubancat, we also need to add the RockChip Overlay layer, which mainly configure files and firmware to add or cover the original configuration file in the root file system.

1	./mk-buster-rootfs.sh

Select the Debian version to be constructed. Here we choose the XFCE version, enter 2 and press the Enter button, and enter the user password according to the prompt.

---------------------------------------------------------
please enter TARGET version number:
[0] Exit Menu
[1] lite
[2] xfce
[3] xfce-full
---------------------------------------------------------
2

drwxr-xr-x 23  270 3月  10 14:57 binary
-rw-rw-rw-  1 370M 3月  10 14:04 linaro-buster-xfce-alip-20230418.tar.gz
-rw-rw-r--  1 1.3G 3月  10 14:11 linaro-xfce-rootfs.img
-rwxrwxr-x  1 1.1K 3月  10 11:04 mk-base-debian.sh
-rwxrwxr-x  1 8.1K 3月  10 11:25 mk-buster-rootfs.sh
-rwxrwxr-x  1  477 3月  10 10:49 mk-image.sh
-rwxrwxr-x  1  441 12月 26 15:18 mk-rootfs.sh
drwxrwxr-x  7   67 11月 30 11:19 overlay
drwxrwxr-x  5   49 11月 30 11:19 overlay-debug
drwxrwxr-x  4   28 11月 30 11:19 overlay-firmware
drwxrwxr-x  3   19 11月 30 11:19 packages
drwxrwxr-x  5   47 11月 30 11:19 packages-patches
-rwxrwxr-x  1 3.0K 11月 30 11:19 post-build.sh
-rw-rw-r--  1 2.6K 3月  10 11:17 readme.md
drwxrwxr-x  7  164 11月 30 11:19 ubuntu-build-service

After the construction is completed, the binary directory is added in the Debian directory, which is stored in the root file system after decompression. We will copy or add the files that are covered or added, and then modify through the Chroot command.

11.6.3. Packing Debian-Lite root file system mirror¶

At the end of the script ./mk-Buster-rootfs.sh, the IMAGE_VERSION=$TARGET ./mk-image.sh script was automatically called. TARGET is the debain version we chose when running a script.

After the script is running, we get a root file system mirror file called linaro-xfce-rootfs.img.

11.7. Customize DEBIAN root file system¶

Due to the limitation of the image volume, the custom DEBIAN mirror we provide is pre -installed with some commonly used software. However, more software may be installed during the development of users and further customization of the root file system. The following parts will make a specific explanation of the modification of the root file system.

11.7.1. Add pre -installed software package¶

For adding pre-installed software, we recommend placing it in the mk-buster-rootfs.sh script. In this way, after we make modifications, we only need to repeat the process of adding the Rockchip overlay layer and packaging the img image, which can save a lot of development time.

For example, if we want to preinstall git and vim into the root file system, we can add the following content to mk-buster-rootfs.sh.

export APT_INSTALL="apt-get install -fy --allow-downgrades"
#The added position is on the next line of export APT_INSTALL

#The added content is
echo -e "\033[47;36m ---------- LubanCat -------- \033[0m"
\${APT_INSTALL} git vim

11.7.2. Add peripheral firmware¶

If we use peripherals such as wireless network interface controller, we need to add the controller firmware to the root file system. At this time, directly store the corresponding firmware in the overlay-firmware/ directory and save it according to the path in the root file system.

11.7.3. Add service items and configuration files¶

If we want to customize the configuration of some service items, we can add the corresponding configuration files in the overlay/ directory. In the process of making the root file system, when adding the Rockchip overlay layer, the original configuration file in the root file system will be added or replaced to achieve the effect of customizing the configuration file.

Here we take the banner configuration when logging in to the Debain console as an example. Its configuration file is in the /etc/update-motd.d directory of the root file system. This corresponds to the overlay/etc/update-motd.d/ directory.

We create a new file named 00-header in overlay/etc/update-motd.d/ and add the following content to the file:

#!/bin/sh
#

[ -r /etc/lsb-release ] && . /etc/lsb-release

printf "\n"
echo "\e[1;34m
        OO                            OO
        OOOO                        OOOO
        OOOOO                     OOOOOO
        OOOOOOO                 .OOOOOOO
        OOOOOOOOO              OOOOOOOOO
        OOOOOOOOOOO          OOOOOOOOOOO
        OOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOO
        OOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOO
        OOOOO\    OOOOOOOOOOOO    /OOOOO
        OOOOOOOOO    OOOOOO     OOOOOOOO
        OOOOO/    OOOOOOOOOOOOO   \OOOOO
        OOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOO
        OOOOOOOOOOOOOO\￣/OOOOOOOOOOOOOO
        OOOOOOOOOOOOOOO\/OOOOOOOOOOOOOOO
        OOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOO
_            _                     ____        _
| |    _   _ | |__    ____  _____  / ___| ____ | |_
| |   | | | || '_ \  / _  ||  _  || |    / _  || __|
| |___| |_| || |_) || (_| || | | || |___| (_| || |_
|_____|\__._||_.__/  \__'_||_| |_| \____|\__'_| \__|
\e[0m"

if [ -z "$DISTRIB_DESCRIPTION" ] && [ -x /usr/bin/lsb_release ]; then
    # Fall back to using the very slow lsb_release utility
    DISTRIB_DESCRIPTION=$(lsb_release -s -d)
fi
printf "\n"
printf "Welcome to %s (%s %s %s)\n" "$DISTRIB_DESCRIPTION" "$(uname -o)" "$(uname -r)" "$(uname -m)"

The purpose of this script is to generate dynamic banners.

After adding the configuration file, we rebuild the image and then burn it to the board to start, so that we can achieve the banner effect we want.

注意

If you add a shell script, you need to modify the file permissions to 775 after creating the file, otherwise it may not be executed in the root file system.

11.7.4. Repackage the root file system image¶

After making changes to the root file system build script, we need to repackage the debian-xfce/lite-rootfs.img .

If we have not modified the live build configuration file, there is no need to repeat the basic image building part. If the configuration file is modified, you need to rebuild it, manually delete the base image compressed package, and then use the mk-base-debian.sh script to build.

# Delete the base image compressed package
rm linaro-*-alip-*.tar.gz

#Build base image
mk-base-debian.sh

If the contents of mk-buster-rootfs.sh, overlay, overlay-debug, overlay-firmware, and packages are modified, you need to execute

#Build a complete root file system image
./mk-buster-rootfs.sh

11.8. Build with one click using LubanCat-SDK¶

After completing Set up the build environment, we can also use the one-click build command directly. This will allow you to build the custom root file system image we provide. You can also use the image packaging function of the SDK to package U-boot, kernel and other parts into a complete system image.

11.8.1. SDK configuration file description¶

The SDK configuration file of the LubanCat board is stored in the device/rockchip/rk356x/ directory and is named after BoardConfig-LubanCat-CPU model-system type-system version.mk

Let’s take a look at the configuration file of the Debain root file system. Here we take BoardConfig-LubanCat-RK3568-debian-xfce.mk as an example to mainly explain the settings related to the Debain root file.

# SOC
export RK_SOC=rk356x

# build.sh save Package name
export RK_PKG_NAME=lubancat-${RK_UBOOT_DEFCONFIG}

# Define default rootfs as debian
export RK_ROOTFS_SYSTEM=debian

# Set debian version (10: buster)
export RK_DEBIAN_VERSION=10

# Define whether the default rootfs is the desktop version
# xfce: desktop version lite: console version xfce-full: desktop version + recommended software package
export RK_ROOTFS_TARGET=xfce

# Define whether to add the DEBUG tool to the default rootfs
# debug: add      none: do not add
export RK_ROOTFS_DEBUG=debug

RK_SOC: Define SOC type, used in ./mk-buster-rootfs.sh
RK_PKG_NAME: Defines the name of the image when it is released and packaged
RK_ROOTFS_SYSTEM: Defines the root file system type
RK_DEBIAN_VERSION: Defines Debian distribution, currently only supports buster
RK_ROOTFS_TARGET: Defines the root file system version
RK_ROOTFS_DEBUG: Whether to add rockchip overlay_debug

11.8.2. Automatic build script in build.sh¶

The one-click build function of the Debain root file system is mainly implemented by the following functions in the build.sh script.

function build_debian(){
    ARCH=${RK_DEBIAN_ARCH:-${RK_ARCH}}
    case $ARCH in
        arm|armhf) ARCH=armhf ;;
        *) ARCH=arm64 ;;
    esac

    echo "=========Start building debian for $ARCH========="
    echo "RK_DEBIAN_VERSION: $RK_DEBIAN_VERSION"
    echo "RK_ROOTFS_TARGET: $RK_ROOTFS_TARGET"
    echo "RK_ROOTFS_DEBUG: $RK_ROOTFS_DEBUG"
    echo " "

    cd debian

    if [[ "$RK_DEBIAN_VERSION" == "stretch" || "$RK_DEBIAN_VERSION" == "9" ]]; then
        RELEASE='stretch'
    elif [[ "$RK_DEBIAN_VERSION" == "buster" || "$RK_DEBIAN_VERSION" == "10" ]]; then
        RELEASE='buster'
    elif [[ "$RK_DEBIAN_VERSION" == "bullseye" || "$RK_DEBIAN_VERSION" == "11" ]]; then
        RELEASE='bullseye'
    else
        echo -e "\033[36m please input the os type,stretch or buster...... \033[0m"
    fi

    if [ ! -e linaro-$RK_ROOTFS_TARGET-rootfs.img ]; then
        echo "[ No linaro-$RK_ROOTFS_TARGET-rootfs.img, Run Make Debian Scripts ]"
        if [ ! -e linaro-$RELEASE-$RK_ROOTFS_TARGET-alip-*.tar.gz ]; then
            echo "[ build linaro-$RELEASE-$RK_ROOTFS_TARGET-alip-*.tar.gz ]"
            RELEASE=$RELEASE TARGET=$RK_ROOTFS_TARGET ARCH=$ARCH ./mk-base-debian.sh
        fi

        RELEASE=$RELEASE TARGET=$RK_ROOTFS_TARGET VERSION=$RK_ROOTFS_DEBUG SOC=$RK_SOC ARCH=$ARCH ./mk-rootfs.sh
    else
        echo "[    Already Exists IMG,  Skip Make Debian Scripts    ]"
        echo "[ Delate linaro-$RK_ROOTFS_TARGET-rootfs.img To Rebuild Debian IMG ]"
    fi

    finish_build
}

Its workflow is as follows

Use the echo command to print relevant configuration information.
Determine whether linaro-$RK_ROOTFS_TARGET-rootfs.img exists ($RK_ROOTFS_TARGET indicates whether it is the desktop version defined in the configuration file). If it exists, skip the build process. If it does not exist, run the build command. It takes a long time to build the root file system. You do not want to build the root file system frequently or use the already built root file system image.
Determine whether the base image for building exists. If it does not exist, build the base image. If it exists, skip the base image building process. Except for the first build, we generally do not modify the base image.
Based on the basic image, add rockchip overlay.
Package the complete image.

11.8.3. Preparations before compilation¶

Before starting the compilation, first ensure that the SDK configuration file is consistent with the rootfs to be compiled. If the current configuration file is inconsistent with the rootfs to be compiled, you need to switch the configuration file first.

# Select SDK configuration file - specify directly
./build.sh BoardConfig-xxx-debian-version.mk

# Select SDK configuration file-select by serial number
./build.sh lunch

After setting the correct configuration file, we can proceed to the next step of building the work.

11.8.4. Build rootfs separately and package it¶

We build the Debian root file system using the following commands.

# Build Debian
./build.sh debian

The rootfs image generated by compilation is linaro-$RK_ROOTFS_TARGET-rootfs.img, and is soft-linked to rockdev/rootfs.ext4.

注意

The Debian root file system will only be rebuilt if linaro-$RK_ROOTFS_TARGET-rootfs.img does not exist. If you modify the configuration file or build script of the Debian root file system, you must first manually delete buntu/linaro-$RK_ROOTFS_TARGET-rootfs.img and then rebuild it.

After the construction is completed, the independent partition table, boot.img, uboot.img and other partition images can be packaged into a complete image.

Before performing the following operations, please make sure that you have completed U-Boot compilation, Kernel compilation, and the just-completed process of building rootfs separately.

After making sure everything is correct, execute the following command

# Firmware packaging
./mkfirmware.sh

# Generate update.img
./build.sh updateimg

After packaging is completed, the generated image is rockdev/update.img. We can use the burning tool to burn update.img into the board eMMC or SD card.

11.8.5. Build a complete image with one click¶

After setting the correct configuration file, execute the following command to complete the compilation of U-Boot, Kernel and rootfs with one click and generate the update.img image.

# One-click compilation
./build.sh

After packaging is completed, the generated image is rockdev/update.img. We can use the burning tool to burn update.img into the board eMMC or SD card.