• smb/resources/embedded/rootfs-build-methods/buildroot/README.md
• smb/resources/embedded/rootfs-build-methods/buildroot/实操教程.md

Buildroot 实操记录与教程

官方文档：https://buildroot.org/docs/website/

概述

Buildroot 是一个简单、高效的嵌入式 Linux 构建系统，通过 make menuconfig 配置，一键生成交叉编译工具链、kernel 和 rootfs。

核心特点

• Kconfig 配置系统：和 Linux 内核同款配置界面
• 一键生成完整系统：toolchain + kernel + bootloader + rootfs
• Minimal 设计：只包含你选择的东西
• 广泛硬件支持：主流 SOC 都有现成 defconfig

编译流程

Buildroot 编译流程
┌─────────────┐
│  .config    │  ← make menuconfig 配置
└──────┬──────┘
       │
       ▼
┌─────────────────────────────────────────────────┐
│                  make                           │
├─────────────────────────────────────────────────┤
│  1. Build Toolchain (gcc, binutils, glibc)     │
│  2. Bootloader (U-Boot, if selected)           │
│  3. Linux Kernel (if selected)                  │
│  4. RootFS (busybox, libraries, packages)       │
└─────────────────────────────────────────────────┘
       │
       ▼
┌─────────────┐
│ output/images/ │
│ - rootfs.tar  │
│ - zImage      │
│ - u-boot.bin  │
└─────────────┘

关键文件

目标配置（实操记录）

• 架构：ARM64 (aarch64)
• 工具链：ARM AArch64 GNU/Linux toolchain (glibc)
• RootFS 类型：ext4
• 包含：Busybox, CMake, Python3, SSH (dropbear)

环境准备

1. 构建环境

推荐：使用 Docker，隔离环境避免污染宿主机。

# 拉取 Debian Bullseye ARM64 镜像
docker pull debian:bullseye

# 运行容器
docker run -it --name buildroot-build \
  -v $(pwd)/workspace:/buildroot-build \
  debian:bullseye bash

2. 安装依赖（在容器内）

apt-get update && apt-get install -y \
  build-essential \
  git \
  wget \
  curl \
  cpio \
  unzip \
  rsync \
  bc \
  python3 \
  python3-dev \
  libncurses-dev \
  libncurses5-dev \
  libssl-dev \
  zlib1g-dev \
  bison \
  flex \
  patch \
  diffutils \
  file \
  git-lfs \
  locales

# 设置 locale
sed -i '/en_US.UTF-8/s/^# //g' /etc/locale.gen
locale-gen
export LANG=en_US.UTF-8

获取 Buildroot 源码

方法一：官方下载（推荐）

cd /buildroot-build
wget https://buildroot.org/downloads/buildroot-2024.08.tar.gz
tar xzf buildroot-2024.08.tar.gz
cd buildroot-2024.08

方法二：Git 克隆

cd /buildroot-build
git clone https://github.com/buildroot/buildroot.git --branch 2024.08 --depth 1
cd buildroot

配置 Buildroot

查看已有配置

Buildroot 内置了大量板级配置：

ls configs/*_defconfig | head -20

常用配置示例：

• qemu_aarch64_virt_defconfig - QEMU 虚拟 ARM64
• raspberrypi3_64_defconfig - 树莓派 3/4 64位
• rockchip_rk3588_defconfig - RK3588
• freescale_imx8mqevk_defconfig - NXP i.MX8

使用 QEMU ARM64 最小配置（快速验证）

cd /buildroot-build/buildroot-2024.08
make qemu_aarch64_virt_defconfig

自定义配置

make menuconfig

菜单说明：

Target options  --->
    Target Architecture = ARM (aarch64)
    Target Architecture Variant = cortex-A53

Build options  --->
    ()  Modified package source directory
    ()  Final target kernel tree
    (output/build)  Build root filesystem as a tarball

Toolchain  --->
    Toolchain type = External toolchain
    Toolchain = ARM AArch64 GCC >

System configuration  --->
    System hostname = buildroot
    Root filesystem overlay directories = ./board/overlay
    /dev management = eudev
    (password) Root filesystem overlay directories

Kernel  --->
    [ ] Linux Kernel (不编译内核，用目标板的)

Target packages  --->
    [*] BusyBox
    [*] Python3
    [*] Git
    [*] OpenSSH (dropbear 或 openssh-server)

保存配置

make savedefconfig
cp defconfig configs/my_aarch64_minimal_defconfig

编译

完整编译

make -j$(nproc)

首次编译需要下载所有源码，耗时 30-60 分钟（视网络和机器性能）。

增量编译

make
# 或只编译某个包
make busybox
make python3

清理

make clean      # 清理编译产物
make distclean  # 清理所有，包括配置

构建产物

编译完成后，产物在 output/images/：

output/images/
├── rootfs.tar          # 根文件系统 tar 包
├── rootfs.ext2         # ext2 镜像
├── rootfs.cpio         # cpio 归档
├── rootfs.squashfs     # squashfs 只读镜像
└── barebox/            # 如果选了 bootloader
    └── barebox.bin

测试运行（QEMU）

启动 QEMU 虚拟机

# 在 buildroot 目录执行
./output/host/bin/qemu-aarch64 \
  -M virt \
  -m 512M \
  -kernel output/images/Image \
  -append "root=/dev/vda console=ttyAMA0" \
  -drive file=output/images/rootfs.ext4,if=vda,format=raw \
  -net nic,model=virtio \
  -net user,hostfwd=tcp::2222-:22 \
  -nographic

简化启动脚本

./output/host/usr/bin/qemu-system-aarch64 \
  -M virt \
  -cpu cortex-a53 \
  -m 512M \
  -nographic \
  -kernel output/images/Image \
  -append "root=/dev/vda console=ttyAMA0" \
  -drive file=output/images/rootfs.ext4,if=vda,format=raw

部署到真实设备

1. 打包 rootfs

cd output/images
# 已有 rootfs.tar，直接用
ls -lh rootfs.tar

2. 传输到目标板

# 假设目标板 IP 是 192.168.1.100
scp rootfs.tar [email protected]:/tmp/

3. 解压到目标板

# SSH 登录目标板
ssh [email protected]

# 备份原 rootfs（如果有）
mkdir -p /backup
cp -a /bin /backup/ 2>/dev/null || true

# 解压新 rootfs
cd /
tar xvf /tmp/rootfs.tar --numeric-owner

# 清理
rm /tmp/rootfs.tar
sync
reboot

4. SD 卡/EMMC 部署

# 找到设备
lsblk
# 假设是 /dev/mmcblk0

# 挂载
mount /dev/mmcblk0p2 /mnt
cd /mnt

# 解压
tar xvf /path/to/rootfs.tar --numeric-owner

# 设置权限
chown -R root:root *

# 卸载
cd /
umount /mnt
sync

常见问题

Q: 编译报错 “Your build system is too dirty”

git clean -fdx
make distclean
make defconfig

Q: 如何查看编译日志

make 2>&1 | tee build.log

Q: 如何添加自定义软件包

在 package/ 下创建：

package/hello/
├── Config.in
└── hello.mk

示例 hello.mk：

HELLO_VERSION = 1.0
HELLO_SITE = file://$(BR2_EXTERNAL)/package/hello
HELLO_SITE_METHOD = file
HELLO_LICENSE = MIT

define HELLO_BUILD_CMDS
    $(TARGET_MAKE_ENV) $(MAKE) CC="$(TARGET_CC)" -C $(@D)
endef

define HELLO_INSTALL_TARGET_CMDS
    $(INSTALL) -D -m 755 $(@D)/hello $(TARGET_DIR)/usr/bin/hello
endef

$(eval $(generic-package))

Q: 如何添加 rootfs overlay

创建 board/<boardname>/rootfs-overlay/ 目录，放入要添加的文件：

mkdir -p board/myboard/rootfs-overlay/etc
echo "127.0.0.1 localhost" > board/myboard/rootfs-overlay/etc/hosts

# 在 menuconfig 中配置
# System configuration -> Root filesystem overlay directories = board/myboard/rootfs-overlay

进阶：自定义交叉编译器

如果需要完全自包含的 toolchain：

make menuconfig

Toolchain  --->
    Toolchain type = Buildroot toolchain
    [*] Enable C++ support
    [*] Enable WCHAR support
    [*] Enable large file support
    [*] Enable locale support
    [*] Enable threads support
    [*] Enable RPC support

参考链接

• 官方文档：https://buildroot.org/docs/
• 官方手册：https://buildroot.org/downloads/manual/manual.pdf
• Buildroot GitHub：https://github.com/buildroot/buildroot