Using Overlays in Buildroot

Introduction

In the article “Automatic Mounting of USB Hard Drives,” I completed debugging by modifying <span>/usr/lib/udev/rules.d/usbmount.rules</span>. During the debugging process, I operated on the development board. After debugging, how can I synchronize the modifications to the SDK code? To address this issue, I first searched the SDK and found that it does not contain this file, as it is part of the usbmount module. Based on past debugging experience, I had two options: either modify the code of the usbmount module or overwrite the system configuration file using an Overlay. Since I am not familiar with the development process of the usbmount module, I chose to use an Overlay to handle it. This article will introduce the principles and debugging process of Overlays.

Overview of Overlay Functionality

The Overlay feature in Buildroot is a powerful customization mechanism that allows developers to deeply customize the generated root filesystem without modifying the internal package definitions of Buildroot. By overriding or adding files during the build process, developers can easily achieve:

• • Custom configuration files
• • Adding precompiled binaries
• • Modifying default system behavior
• • Deploying custom scripts and services

How Overlays Work

The Overlay mechanism in Buildroot executes at specific stages of the build process, as follows:

1. 1. Position in the build process:

• • Executed after all packages are installed
• • Executed before the filesystem image is generated
• • Executed before the post-build scripts are run

buildroot/board/rockchip/common/post-build.sh
OVERLAYS="$(dirname "$0")/overlays"
fordir in $(ls "$OVERLAYS"); do
        OVERLAY_DIR="$OVERLAYS/$dir"
        if [ -x "$OVERLAY_DIR/prepare.sh" ] && \
                ! "$OVERLAY_DIR/prepare.sh" "$TARGET_DIR"; then
                echo ">>> Ignored $OVERLAY_DIR"
                continue
        fi

        echo ">>> Copying $OVERLAY_DIR"
        rsync -av --chmod=u=rwX,go=rX --exclude .empty --exclude /prepare.sh \
                "$OVERLAY_DIR/" "$TARGET_DIR/"
done

• • File permissions are preserved (–chmod)
• • Version control and temporary files are excluded
• • Directory structure integrity is maintained

Configuration and Usage

Basic Configuration

1. 1. Configure via menuconfig:

   System configuration → Root filesystem overlay directories

2. 2. Directly modify the .config file:

   BR2_ROOTFS_OVERLAY="/path/to/overlay1 /path/to/overlay2"

Example Directory Structure

A typical overlay directory structure should mirror the target root filesystem:

my_overlay/
├── etc/
│   ├── network/
│   │   └── interfaces
│   └── shadow
├── home/
│   └── user/
│       └── .bashrc
└── usr/
    └── local/
        └── bin/
            └── my_script

Debugging Process

View Current Configuration

Taking the SDK for RK3576 as an example, the macro for Overlay is <span>BR2_ROOTFS_OVERLAY</span>. The .config file generated by Buildroot is stored in the <span>buildroot/output/rockchip_rk3576/</span> directory, so I will use grep to confirm the current configuration:

$ grep "BR2_ROOTFS_OVERLAY" buildroot/output/rockchip_rk3576/.config
BR2_ROOTFS_OVERLAY="board/rockchip/common/base board/rockchip/rk3576/fs-overlay/"

Confirm Current Directory Structure

$ tree buildroot/board/rockchip/common/base/ buildroot/board/rockchip/rk3576/fs-overlay/
buildroot/board/rockchip/common/base/
└── busybox.fragment
buildroot/board/rockchip/rk3576/fs-overlay/

0 directories, 0 files

It was found that there is only one file in the Overlay directory, so I need to create the corresponding directories as needed.

Create Directories and Embed Files

$ mkdir -p buildroot/board/rockchip/rk3576/fs-overlay/usr/lib/udev/rules.d/
$ cp ~/tmp/usbmount.rules buildroot/board/rockchip/rk3576/fs-overlay/usr/lib/udev/rules.d/
$ tree buildroot/board/rockchip/rk3576/fs-overlay/
buildroot/board/rockchip/rk3576/fs-overlay/
└── usr
    └── lib
        └── udev
            └── rules.d
                └── usbmount.rules

4 directories, 1 file

Compile and Generate Firmware

During the compilation process, the following logs can be seen:

2025-06-18T06:59:25 >>>   Finalizing host directory
2025-06-18T06:59:25 >>>   Finalizing target directory
2025-06-18T07:00:21 >>>   Sanitizing RPATH in target tree
2025-06-18T07:00:25 >>>   Sanity check in overlay board/rockchip/common/base
2025-06-18T07:00:25 >>>   Sanity check in overlay board/rockchip/rk3576/fs-overlay/
2025-06-18T07:00:25 >>>   Copying overlay board/rockchip/common/base
2025-06-18T07:00:25 >>>   Copying overlay board/rockchip/rk3576/fs-overlay/
2025-06-18T07:00:30 >>>   Executing post-build script board/rockchip/common/post-build.sh

Confirm that the modified files can be updated to the firmware.

Conclusion

The Overlay feature in Buildroot provides a flexible file system customization solution. By effectively utilizing the Overlay feature, developers can efficiently create system images that meet specific requirements while maintaining the cleanliness and maintainability of the build system.