第3章源码结构解析

第3章：源码结构解析——Buildroot目录树详解

说实话，我第一次打开Buildroot源码目录时，也有点懵。一堆文件夹，名字还都挺抽象。但用久了你会发现，这个目录结构设计得其实很讲究。今天我就带你把它捋清楚。

3.1 顶层目录概览

先看根目录下都有什么。我习惯用 ls -l 扫一眼，重点关注这几个：

board/          # 板级支持文件
configs/        # 默认配置文件
package/        # 软件包定义
toolchain/      # 工具链相关
linux/          # Linux内核相关
boot/           # 引导程序
fs/             # 文件系统生成
system/         # 系统配置
support/        # 辅助脚本

每个文件夹都有明确分工。咱们一个一个说。

3.2 board/ —— 板级支持的核心

这个目录存放的是跟具体硬件平台相关的文件。比如设备树、分区表、启动脚本等。

典型结构：

board/
  raspberrypi/
    post-build.sh
    post-image.sh
    config.txt
    cmdline.txt
  beaglebone/
    uEnv.txt
    boot.scr

我在项目中遇到过一个问题：同一块板子，不同批次的外设引脚有差异。这时候board目录下的补丁文件就派上用场了。你可以放内核补丁、uboot补丁，甚至自定义的udev规则。

我的习惯：每个项目都在board下建一个以项目名命名的子目录。里面放所有跟硬件绑定的文件。这样换板子时，直接换目录就行。

3.3 configs/ —— 一键构建的钥匙

这个目录里全是 _defconfig 文件。说白了，就是Buildroot的预设配置快照。

configs/
  raspberrypi3_defconfig
  beaglebone_defconfig
  stm32mp157_dk_defconfig

每个文件内容大致长这样：

BR2_arm=y
BR2_TOOLCHAIN_BUILDROOT=y
BR2_LINUX_KERNEL=y
BR2_PACKAGE_BUSYBOX=y

你想想看，如果没有这些defconfig，每次构建都要从头选配置，那得多痛苦。我建议你拿到一块新板子，第一件事就是跑 make savedefconfig，把配置固化下来。

注意：defconfig只保存非默认值的选项。所以别指望它能完整还原你的所有设置。我吃过这个亏——有一次升级Buildroot版本，旧defconfig在新版上构建失败，排查了半天才发现是某个依赖包版本变了。

3.4 package/ —— 软件包的大本营

这是Buildroot最核心的目录。每个软件包一个子目录，里面包含：

Config.in —— 菜单配置
*.mk —— 构建规则
*.hash —— 校验文件
patches/ —— 补丁文件

举个例子，看看 package/curl/：

package/curl/
  Config.in
  curl.mk
  curl.hash
  patches/
    0001-fix-ssl.patch

3.4.1 Config.in 文件

这个文件决定了你在 make menuconfig 里能看到什么选项。语法是Kconfig格式：

config BR2_PACKAGE_CURL
    bool "curl"
    depends on BR2_TOOLCHAIN_HAS_THREADS
    select BR2_PACKAGE_OPENSSL if BR2_PACKAGE_CURL_SSL
    help
      Command line tool for transferring data with URL syntax.

嗯，这里要注意：depends on 和 select 的区别。前者是依赖关系，后者是自动选中。我刚开始经常搞混，结果编译出来的镜像要么缺库，要么多了不需要的东西。

3.4.2 *.mk 文件

这才是真正的构建脚本。Buildroot用了一套自己的变量命名规范：

CURL_VERSION = 7.88.1
CURL_SITE = https://curl.se/download
CURL_SOURCE = curl-$(CURL_VERSION).tar.bz2
CURL_LICENSE = MIT
CURL_LICENSE_FILES = COPYING

define CURL_BUILD_CMDS
    $(MAKE) -C $(@D) all
endef

define CURL_INSTALL_TARGET_CMDS
    $(MAKE) -C $(@D) DESTDIR=$(TARGET_DIR) install
endef

$(eval $(generic-package))

你看，变量名都是 包名_属性 的格式。最后一行 $(eval $(generic-package)) 是关键——它告诉Buildroot用通用构建方式。如果是autotools项目，就用 autotools-package；cmake项目用 cmake-package。

避坑指南：我曾经在写自定义包时，忘了加 $(eval $(generic-package))，结果make执行时完全没反应。排查了半小时才发现这个低级错误。所以，写完mk文件后，先检查最后一行有没有这个宏调用。

3.5 toolchain/ —— 工具链的管家

这个目录管理着交叉编译工具链。Buildroot支持三种方式：

方式	配置选项	适用场景
Buildroot内部构建	BR2_TOOLCHAIN_BUILDROOT	从头编译，定制性强
外部工具链	BR2_TOOLCHAIN_EXTERNAL	使用预编译工具链，省时间
系统工具链	BR2_TOOLCHAIN_EXTERNAL_CUSTOM	使用系统自带的

我个人习惯用外部工具链。为什么？因为内部构建太慢了。第一次构建要等半小时才能看到工具链编译完成。但如果你需要定制glibc版本或者gcc特性，那就只能选内部构建了。

3.6 其他关键目录

linux/ —— 内核配置和补丁。里面有个 linux.mk，定义了内核的下载、配置、编译流程。
boot/ —— 引导程序。uboot、grub、barebox都在这里。
fs/ —— 文件系统生成逻辑。ext4、squashfs、initramfs等格式的支持都在这里。
system/ —— 系统级配置。比如设备节点、用户组、密码策略等。
support/ —— 辅助脚本。比如 support/scripts/ 下的 genimage.sh 用于生成镜像文件。

3.7 知识体系结构图

下面这张图帮你理清Buildroot目录树的核心逻辑：

3.8 我的建议

刚开始接触Buildroot时，别急着改代码。先花半小时把目录结构走一遍。打开几个典型的Config.in和mk文件看看，理解它们的写法。等你需要添加新包或者修改构建流程时，就知道该动哪个文件了。

我记得有一次，客户要求在镜像里加入一个私有库。我直接去 package/ 下新建了个目录，照着curl的写法复制粘贴，改改变量名，半小时就搞定了。这就是熟悉目录结构的好处——你知道该抄谁的作业。

总结一句话：Buildroot的目录树就是它的设计哲学——模块化、可配置、易扩展。理解了它，你就掌握了嵌入式Linux构建的主动权。

公众号:蓝海资料掘金营，微信deep3321

📚 课程目录