Buildroot 开发指南
简介
本文介绍如何使用 Buildroot 构建系统。借助 Buildroot，开发者可快速自定义和构建运行于 ZHIHE SoC 的嵌入式 Linux 系统。
Buildroot 构建基础
获取代码
请参考快速上手。
目录介绍
Buildroot 以 Package 作为管理单位，每个 Package 中有 .mk 和 Config.in 文件定义构建配置和行为。boot 目录中存放启动相关包。linux 为独立目录。package 目录中存放其他第三方包。
| 目录 | 说明 |
|---|---|
| toolchain | 工具链支持包 |
| arch | 编译架构的配置 |
| support | 构建系统工具 |
| fs | 文件系统打包工具 |
| system | rootfs基础结构 |
| configs | 板级配置文件 |
| board | 板级配置代码 |
| boot | 引导系统包 |
| linux | linux 包 |
| package | 所有其他三方包 |
构建
用户可使用快速上手中的脚本自动构建 Buildroot，也可执行以下命令完成构建。
注意：
- 请确认 Buildroot 构建命令均在
zdocker环境中执行。- 下面所有命令的工作路径是 buildroot 代码的根目录
- 如果在同一个目录中切换配置，须先执行
make clean清理临时文件，再构建新配置。
-
查看 Buildroot 配置。
# 查看可用配置
ls configs/zhihe*
# 返回结果
configs/zhihe_a200_defconfig configs/zhihe_a210_defconfig -
根据配置类型，执行构建命令。
# 构建A200
make zhihe_a200_defconfig
make
# 构建A210
make zhihe_a210_defconfig
make
缓存机制说明
缓存下载机制
构建启动后会默认创建 dl 目录，所有软件包将首先下载至该目录，后续构建时无需重复下载。
用户可执行 make menuconfig 命令，进入 Build options->Mirrors and Download locations 来修改下载镜像的地址。
镜像地址示例如下所示。
→ Build options → Mirrors and Download locations ───────────────────────────────────────
┌───────────────────────── Mirrors and Download locations ──────────────────────────┐
│ Arrow keys navigate the menu. <Enter> selects submenus ---> (or empty submenus │
│ ----). Highlighted letters are hotkeys. Pressing <Y> selects a feature, while │
│ <N> excludes a feature. Press <Esc><Esc> to exit, <?> for Help, </> for Search. │
│ Legend: [*] feature is selected [ ] feature is excluded │
│ ┌───────────────────────────────────────────────────────────────────────────────┐ │
│ │ (https://sources.buildroot.net) Primary download site │ │
│ │ [ ] Only allow downloads from primary download site │ │
│ │ (https://sources.buildroot.net) Backup download site │ │
│ │ (https://cdn.kernel.org/pub) Kernel.org mirror │ │
│ │ (https://ftpmirror.gnu.org) GNU Software mirror │ │
│ │ (http://rocks.moonscript.org) LuaRocks mirror │ │
│ │ (https://cpan.metacpan.org) CPAN mirror (Perl packages) │ │
│ │
缓存编译机制
SDK 默认配置宏 BR2_CCACHE=y，使能 ccache 功能，通过缓存之前的编译结果来减少重复编译的时间，提升编译效率。
缓存目录： $HOME/.buildroot-ccache。用户可执行以下命令，查看缓存状态。
output/host/bin/ccache -d $HOME/.buildroot-ccache -s
Cacheable calls: 75921 / 108440 (70.01%)
Hits: 39803 / 75921 (52.43%)
Direct: 30335 / 39803 (76.21%)
Preprocessed: 9468 / 39803 (23.79%)
Misses: 36118 / 75921 (47.57%)
Uncacheable calls: 32519 / 108440 (29.99%)
Local storage:
Cache size (GiB): 1.6 / 5.0 (32.75%)
Hits: 39803 / 75921 (52.43%)
Misses: 36118 / 75921 (47.57%)
输出目录
| 目录 | 说明 |
|---|---|
| output/build | 所有 package 解压到该目录编译，包括 host 包 |
| output/host | 保存 host 包构建后输出的目标文件 |
| output/images | 保存基础系统包输出的目标文件 |
| output/staging | 构建 package 的 sysroot，目标系统的头文件、库文件和开发工具 |
| output/target | 最终生成的完整根文件系统 |
单独编译包
make <pkg> 命令整合了编译 package 的主要过程。 make <pkg>-<target>，可实现更多编译过程控制。示例命令如下。
# 重新编译uboot，如果没有清理不重复执行
make uboot
# 清理uboot，删除build目录下解压的包
make uboot-dirclean
# 从build阶段开始构建
make uboot-rebuild
用户可执行 make help，查看所有可执行命令。
Package-specific:
<pkg> - Build and install <pkg> and all its dependencies
<pkg>-source - Only download the source files for <pkg>
<pkg>-extract - Extract <pkg> sources
<pkg>-patch - Apply patches to <pkg>
<pkg>-depends - Build <pkg>'s dependencies
<pkg>-configure - Build <pkg> up to the configure step
<pkg>-build - Build <pkg> up to the build step
<pkg>-show-info - generate info about <pkg>, as a JSON blurb
<pkg>-show-depends - List packages on which <pkg> depends
<pkg>-show-rdepends - List packages which have <pkg> as a dependency
<pkg>-show-recursive-depends
- Recursively list packages on which <pkg> depends
<pkg>-show-recursive-rdepends
- Recursively list packages which have <pkg> as a dependency
<pkg>-graph-depends - Generate a graph of <pkg>'s dependencies
<pkg>-graph-rdepends - Generate a graph of <pkg>'s reverse dependencies
<pkg>-graph-both-depends
- Generate a graph of both <pkg>'s forward and
reverse dependencies.
<pkg>-dirclean - Remove <pkg> build directory
<pkg>-reconfigure - Restart the build from the configure step
<pkg>-rebuild - Restart the build from the build step
<pkg>-reinstall - Restart the build from the install step
基础系统定制
查看交叉编译工具链
Buildroot 提供内部和外部两种交叉编译工具链解决方案， SDK 使用外部工具链。
执行 make menuconfig 命令，进入 Toolchain 菜单可查看配置。
→ Toolchain ────────────────────────────────────────────────────────────────────────────
┌───────────────────────────────────── Toolchain ─────────────────────────────────────┐
│ Arrow keys navigate the menu. <Enter> selects submenus ---> (or empty submenus │
│ ----). Highlighted letters are hotkeys. Pressing <Y> selects a feature, while │
│ <N> excludes a feature. Press <Esc><Esc> to exit, <?> for Help, </> for Search. │
│ Legend: [*] feature is selected [ ] feature is excluded │
│ ┌─────────────────────────────────────────────────────────────────────────────────┐ │
│ │ Toolchain type (External toolchain) ---> │ │
│ │ *** Toolchain External Options *** │ │
│ │ Toolchain (Custom toolchain) ---> │ │
│ │ Toolchain origin (Pre-installed toolchain) ---> │ │
│ │ () Toolchain path │ │
│ │ (${ARCH}-unknown-linux-gnu) Toolchain prefix │ │
│ │ External toolchain gcc version (14.x) ---> │ │
│ │ External toolchain kernel headers series (6.6.x) ---> │ │
│ │ External toolchain C library (glibc) ---> │ │
│ │ [*] Toolchain has SSP support? │ │
│ │ [*] Toolchain has SSP strong support? │ │
│ │ [ ] Toolchain has RPC support?
定制基础系统源代码
用户可指定 OpenSBI、U-Boot、Kernel 仓库来源，覆盖默认源码获取方式。
-
定义
BR2_PACKAGE_OVERRIDE_FILE，开启代码覆盖功能。BR2_PACKAGE_OVERRIDE_FILE="$(TOPDIR)/board/zhihe/local.mk" -
需覆盖的仓库在
local.mk文件中定义。定义的本地仓库在构建前应与 Buildroot 同级保存。LINUX_OVERRIDE_SRCDIR = $(TOPDIR)/../kernel
UBOOT_OVERRIDE_SRCDIR = $(TOPDIR)/../u-boot
OPENSBI_OVERRIDE_SRCDIR = $(TOPDIR)/../opensbi -
仓库和对应的
buildroot的pkg名称仓库 名称 kernel linux u-boot uboot opensbi opensbi
重新构建
本节以 Linux Kernel 为例讲解。
首次构建后会复制一份 Kernel 代码到 output/build/linux-custom 进行编译。用户可修改原始代码并重新构建，也可以直接快速重构。
修改原始代码重新构建
-
修改并保存配置。仅修改源代码，可跳过本步骤。
Buildroot的
BR2_LINUX_KERNEL_CUSTOM_CONFIG_FILE宏保存了原始配置路径。启动配置菜单，配置完成后保存到原始配置文件。make linux-menuconfig
make linux-update-defconfig -
重新构建。
修改工作目录中的
linux-custom代码后，执行下面命令开始重构。make linux-dirclean
make linux
make
快速重构
修改 linux-custom 目录中的配置和代码，快速重构。
说明：
- 快速重构法只进行增量重构，用时较短。
- 修改配置需执行
make linux-menuconfig，仅代码修改可跳过menuconfig。
make linux-menuconfig
make linux-rebuild
make
定制根文件系统
管理主配置
-
执行
make menuconfig命令进入Target packages菜单。 该菜单分类了所有支持的Package，方便用户定制系统。→ Target packages ─────────────────────────────────────────────────────────────────────
┌────────────────────────────────── Target packages ──────────────────────────────────┐
│ Arrow keys navigate the menu. <Enter> selects submenus ---> (or empty submenus │
│ ----). Highlighted letters are hotkeys. Pressing <Y> selects a feature, while │
│ <N> excludes a feature. Press <Esc><Esc> to exit, <?> for Help, </> for Search. │
│ Legend: [*] feature is selected [ ] feature is excluded │
│ ┌─────────────────────────────────────────────────────────────────────────────────┐ │
│ │ -*- BusyBox │ │
│ │ (board/zhihe/a200-evb/configs/busybox.config) BusyBox configuration file to │ │
│ │ () Additional BusyBox configuration fragment files │ │
│ │ [*] Show packages that are also provided by busybox │ │
│ │ [ ] Individual binaries │ │
│ │ [ ] Install the watchdog daemon startup script │ │
│ │ Audio and video applications ---> │ │
│ │ Compressors and decompressors ---> │ │
│ │ Debugging, profiling and benchmark ---> │ │
│ │ Development tools ---> │ │
│ │ Filesystem and flash utilities ---> │ │
│ │ Fonts, cursors, icons, sounds and themes ---> │ │
│ │ Games ---> │ │
│ │ Graphic libraries and applications (graphic/text) ---> │ │
│ │ Hardware handling ---> │ │
│ │ Interpreter languages and scripting ---> │ │
│ │ Libraries ---> │ │
│ │ Mail ---> │ │
│ │ Miscellaneous ---> │ │
│ │ Networking applications ---> │ │
│ │ Package managers ---> │ │
│ │ Real-Time ---> │ │
│ │ Security ---> │ │
│ │ Shell and utilities ---> │ │
│ │ System tools ---> │ │
│ │ Text editors and viewers ---> │ │ -
保存配置。执行以下命令，修改后配置会自动保存到对应配置文件
zhihe_<board>_defconfig中。make savedefconfig
管理 Busybox 配置
Busybox 有独立 menuconfig 界面和配置文件 。执行以下命令，修改和保存配置。
# 开启配置界面
make busybox-menuconfig
# 保存配置到文件
make busybox-update-config
添加自定义文件
Buildroot 中，使用 Overlay 是一种定制根文件系统（rootfs）的常用方法。用户可在 Overlay 目录中添加、替换默认的文件，构建根文件系统时会覆盖到输出目录的对应路径中。
-
配置方法
Overlay 路径定义在 defconfig 中，默认路径如下。
注意
- 系统默认已配置路径，并存在系统初始的配置文件中，建议保留原始文件。
- Overlay 路径对应 rootfs 根路径，新增/替换文件需按系统路径存于 Overlay 文件夹，添加前建议确认文件在系统中的路径。
BR2_ROOTFS_OVERLAY="board/zhihe/overlay" -
添加自定义文件后重新生成。
Overlay 增加文件后，无需重编整个系统，重新执行
make后，可在buildroot/output/target中确认文件是否被增加。