Buildroot 2025.05 中文手册【AI高质量翻译】

译文在 Github 仓库和 Gitee 仓库保持最新，其它平台发的文档可能不会与之同步。

希望能够共同维护这个仓库的 Buildroot 手册中文译文，帮助更多人真正深入学习理解，更好的工作、生活和创造。

关于 AI 提示词以及更多工具的收集，有一个仓库：

说明

buildroot 官方手册网址：
https://buildroot.org/downloads/manual/manual.html

网上的一些翻译文档，但是有点旧了

过程：

手动拆分最新官方文档（2025.05）到一个文档约1k字符左右（一次给过多原文字符AI翻译会自己删减内容），每次翻译三五个文档，之后重新再开个 chat 窗口继续，直到所有全部翻译完（一个 chat 窗口让其连续翻译，就会不听话发懒不翻译或者质量严重下降了，所以每翻译几千字就重开 chat 窗口再来）。

下面译文若有与原文对不上的，敬请指出
使用 copilot 的 GPT4.1 的 agent 模式完成。

提示词输入：

你是一个中英文翻译专家，将用户输入的中文翻译成英文。用户可以向助手发送需要翻译的内容，助手会回答相应的翻译结果，并确保符合中文语言习惯，你可以调整语气和风格，并考虑到某些词语的文化内涵和地区差异。同时作为翻译家，需将原文翻译成具有信达雅标准的译文。"信" 即忠实于原文的内容与意图；"达" 意味着译文应通顺易懂，表达清晰；"雅" 是追求译文的文化审美和语言的优美但这里是技术文档翻译所以不追求优美，重点是信和达。而且注意，对于名词的翻译，还要加括号著名英文原文，确保是一篇易懂且准确的译文。只给出译文结果即可。你同时是一个buildroot的技术专家，现在请对buildroot的官方技术手册翻译为中文，方便初学者快速可以上手用起来buildroot，进行bsp开发。以下我将不断给出原文，请翻译为中文的参考手册。按照我给的原文如实翻译，不要精简和归纳。对于执行脚本和代码使用代码块格式。全文分好标题层级。原文文件为当前目录下的buildrootManualX.X.md格式的文件，以1.0、1.1...2.0.2.1...排序。逐个文件翻译后输出buildrootManualChineseX.X.md文件，全程自动无人值守静默执行。开始。
之后经过手动章节校对，目录与官方文档一致，但是译文可能与原文有稍许的差异，如您确定译文有误或有不妥，大可直言提出优化，帮助译文改进。

正文

Buildroot 2025.05 手册，生成于 2025-06-09 20:23:58 UTC，基于 git 修订版 fcde5363aa

Buildroot 手册由 Buildroot 开发者编写。其授权协议为 GNU 通用公共许可证第 2 版（GNU General Public License, version 2）。完整协议内容请参见 Buildroot 源码中的 COPYING 文件。

第一部分入门

第 1 章关于 Buildroot

Buildroot 是一个简化并自动化为嵌入式系统构建完整 Linux 系统流程的工具，采用交叉编译（cross-compilation）方式。

为实现这一目标，Buildroot 能够为目标设备生成交叉编译工具链（cross-compilation toolchain）、根文件系统（root filesystem）、Linux 内核镜像（Linux kernel image）以及引导加载程序（bootloader）。Buildroot 可用于上述任意组合（例如，你可以使用已有的交叉编译工具链，仅用 Buildroot 构建根文件系统）。

Buildroot 主要适用于嵌入式系统开发人员。嵌入式系统通常使用的处理器并非大家在 PC 上常见的 x86 处理器，而是 PowerPC 处理器（PowerPC processors）、MIPS 处理器（MIPS processors）、ARM 处理器（ARM processors）等。

Buildroot 支持众多处理器及其变种，并为多款现成开发板（off-the-shelf boards）提供了默认配置。此外，许多第三方项目基于 Buildroot 开发其 BSP（Board Support Package）或 SDK（Software Development Kit）。

[1] BSP：板级支持包（Board Support Package）

[2] SDK：软件开发工具包（Software Development Kit）

第 2 章系统要求

Buildroot 设计用于 Linux 系统。

虽然 Buildroot 会自动构建大部分所需的主机端（host）软件包，但仍要求主机系统预先安装部分标准 Linux 工具。下表列出了必需和可选软件包（注意，不同发行版的软件包名称可能有所不同）。

2.1 必需软件包

构建工具（Build tools）：
- which
- sed
- make（版本 3.81 或更高）
- binutils
- build-essential（仅限基于 Debian 的系统）
- diffutils
- gcc（版本 4.8 或更高）
- g++（版本 4.8 或更高）
- bash
- patch
- gzip
- bzip2
- perl（版本 5.8.7 或更高）
- tar
- cpio
- unzip
- rsync
- file（必须位于 /usr/bin/file）
- bc
- findutils
- awk
源码获取工具（Source fetching tools）：
- wget

2.2 可选软件包

推荐依赖（Recommended dependencies）：

Buildroot 的部分功能或工具（如 legal-info、图形生成工具等）需要额外依赖。虽然这些依赖对于简单构建并非强制，但仍强烈推荐安装：
- python（版本 2.7 或更高）
配置界面依赖（Configuration interface dependencies）：

对于这些库，你需要同时安装运行时和开发包（runtime and development data），在许多发行版中开发包通常以 -dev 或 -devel 结尾。
- ncurses5（用于 menuconfig 界面）
- qt5（用于 xconfig 界面）
- glib2、gtk2 和 glade2（用于 gconfig 界面）
源码获取工具（Source fetching tools）：

在官方源码树中，大多数软件包源码通过 wget 从 ftp、http 或 https 位置获取。部分软件包仅能通过版本控制系统（version control system）获取。此外，Buildroot 还支持通过 git 或 scp 等工具下载源码（详见第 20 章下载基础设施）。如启用这些方式获取的软件包，需在主机系统安装相应工具：
- bazaar
- curl
- cvs
- git
- mercurial
- scp
- sftp
- subversion
Java 相关软件包（Java-related packages），如需为目标系统构建 Java Classpath：
- javac 编译器（compiler）
- jar 工具（tool）
文档生成工具（Documentation generation tools）：
- asciidoc，版本 8.6.3 或更高
- w3m
- python，需带有 argparse 模块（2.7+ 和 3.2+ 默认自带）
- dblatex（仅生成 pdf 手册时需要）
图形生成工具（Graph generation tools）：
- graphviz（用于 graph-depends 和 <pkg>-graph-depends）
- python-matplotlib（用于 graph-build）
软件包统计工具（Package statistics tools，pkg-stats）：
- python-aiohttp

第 3 章获取 Buildroot

Buildroot 每 3 个月发布一次新版本，发布时间为 2 月、5 月、8 月和 11 月。版本号格式为 YYYY.MM，例如 2013.02、2014.08。

发布版压缩包可在 Index of /downloads/ 获取。

为方便用户，Buildroot 源码树的 support/misc/Vagrantfile 提供了一个 Vagrantfile，可快速搭建包含所需依赖的虚拟机环境。

如需在 Linux 或 Mac OS X 上搭建隔离的 buildroot 环境，请在终端粘贴以下命令：

curl -O https://buildroot.org/downloads/Vagrantfile; vagrant up

如在 Windows 上，请在 powershell 粘贴以下命令：

(new-object System.Net.WebClient).DownloadFile(
"https://buildroot.org/downloads/Vagrantfile","Vagrantfile");
vagrant up

如需跟进开发版，可使用每日快照（daily snapshots）或克隆 Git 仓库。更多详情请参见 Buildroot 官网的下载页面。

第 4 章 Buildroot 快速入门

重要提示：你可以且应当以普通用户身份构建所有内容。配置和使用 Buildroot 无需 root 权限。以普通用户身份运行所有命令，可以防止在编译和安装过程中因软件包异常行为而影响你的系统。

使用 Buildroot 的第一步是创建配置。Buildroot 提供了类似于 Linux 内核或 BusyBox 的友好配置工具。

在 buildroot 目录下，运行：

 $ make menuconfig

以启动原始的基于 curses 的配置器，或

 $ make nconfig

以启动新的基于 curses 的配置器，或

 $ make xconfig

以启动基于 Qt 的配置器，或

 $ make gconfig

以启动基于 GTK 的配置器。

所有这些 "make" 命令都需要构建配置工具（包括界面），因此你可能需要为相关库安装“开发”软件包。详细信息请参见第 2 章系统要求，特别是可选依赖部分，以获取你喜欢的界面所需依赖。

在配置工具的每个菜单项中，你都可以找到相关帮助，说明该项的用途。关于部分具体配置内容，详见第 6 章 Buildroot 配置。

配置完成后，配置工具会生成一个 .config 文件，包含全部配置信息。该文件将被顶层 Makefile 读取。

要开始构建流程，只需运行：

 $ make

默认情况下，Buildroot 不支持顶层并行构建（top-level parallel build），因此无需使用 make -jN。不过，Buildroot 提供了实验性的顶层并行构建支持，详见第 8.12 节 “顶层并行构建”。

make 命令通常会执行以下步骤：

下载所需源码文件；
配置、构建并安装交叉编译工具链，或直接导入外部工具链；
配置、构建并安装所选目标软件包；
构建内核镜像（如已选择）；
构建引导加载程序镜像（如已选择）；
以所选格式创建根文件系统。

Buildroot 的输出统一存放在 output/ 目录下。该目录包含若干子目录：

images/：存放所有镜像（内核镜像、引导加载程序和根文件系统镜像）。这些文件需要烧录到目标系统。
build/：存放所有构建组件（包括 Buildroot 在主机上需要的工具和为目标编译的软件包）。该目录下每个组件对应一个子目录。
host/：包含为主机构建的工具和目标工具链的 sysroot。前者是为主机编译、Buildroot 正常运行所需的工具（包括交叉编译工具链）；后者结构类似根文件系统，包含所有用户空间软件包的头文件和库（供其他软件包依赖）。但该目录不应作为目标设备的根文件系统：其中包含大量开发文件、未剥离（unstripped）二进制和库，体积过大，仅供交叉编译时依赖。
staging/：指向 host/ 目录下目标工具链 sysroot 的符号链接，仅为兼容历史保留。
target/：包含几乎完整的目标根文件系统：除 /dev/ 下的设备文件（Buildroot 不能创建，因为不以 root 运行且不建议以 root 运行）和部分权限（如 busybox 二进制的 setuid 权限）外，其他内容齐全。因此，该目录不应直接用于目标设备。应使用 images/ 目录下生成的镜像文件。如需用于 NFS 启动的根文件系统解包镜像，请使用 images/ 目录下生成的 tar 包，并以 root 权限解包。与 staging/ 不同，target/ 仅包含运行所选目标应用所需的文件和库：不含开发文件（头文件等），二进制已剥离。

这些命令 make menuconfig|nconfig|gconfig|xconfig 和 make 是最基本的命令，可帮助你快速生成满足需求的镜像，包含你启用的所有功能和应用。

关于 "make" 命令的更多用法，详见第 8.1 节 “make 使用技巧”。

第 5 章社区资源

与所有开源项目一样，Buildroot 社区和外部有多种信息交流方式。

如果你需要帮助、想了解 Buildroot 或希望为项目做贡献，这些方式都值得关注。

邮件列表（Mailing List）

Buildroot 拥有用于讨论和开发的邮件列表，是 Buildroot 用户和开发者的主要交流方式。只有订阅者才能向该列表发帖。你可以通过邮件列表信息页面订阅。发送到邮件列表的邮件也会被归档，可通过 Mailman 或 lore.kernel.org 查看。
IRC

Buildroot 的 IRC 频道 #buildroot 托管在 OFTC 上。这里适合快速提问或讨论特定话题。提问时请使用 Pasthis - Simple pastebin 等代码分享网站粘贴相关日志或代码片段。对于某些问题，邮件列表可能更合适，因为能覆盖更多开发者和用户。
Bug 跟踪器（Bug tracker）

Buildroot 的 bug 可通过邮件列表或 Buildroot bugtracker 报告。请在提交 bug 报告前参见第 22.6 节 “报告问题/bug 或获取帮助”。
Wiki

Buildroot wiki 页面托管在 eLinux wiki 上，包含有用链接、往届和即将举行的活动概览及 TODO 列表。
Patchwork

Patchwork 是一个基于 Web 的补丁跟踪系统，便于开源项目的补丁贡献和管理。发送到邮件列表的补丁会被系统“捕获”，并显示在网页上，相关评论也会附在补丁页面。更多 Patchwork 信息见 patchwork。Buildroot 的 Patchwork 网站主要供维护者确保补丁不被遗漏，也供补丁审核者使用（参见第 22.3.1 节 “从 Patchwork 应用补丁”）。此外，该网站以简洁明了的界面公开补丁及其评论，对所有 Buildroot 开发者都很有用。Buildroot 补丁管理界面见 Buildroot development - Patchwork。

第二部分用户指南

第 6 章 Buildroot 配置

所有 make *config 的配置选项都带有帮助文本，详细说明该选项的作用。

make *config 命令还提供了搜索工具。具体用法请参见各前端菜单中的帮助信息：

在 menuconfig 中，按 / 调出搜索工具；
在 xconfig 中，按 Ctrl + f 调出搜索工具。

搜索结果会显示匹配项的帮助信息。在 menuconfig 中，左侧的数字为快捷方式，输入该数字可直接跳转到对应条目，若因依赖未满足该条目不可选，则跳转到包含该条目的菜单。

虽然菜单结构和帮助文本已较为自解释，但部分主题需要额外说明，详见下文。

6.1 交叉编译工具链（Cross-compilation toolchain）

编译工具链（compilation toolchain）是一组用于为你的系统编译代码的工具。它包括编译器（compiler，通常为 gcc）、二进制工具（binary utils，如汇编器 assembler 和链接器 linker，通常为 binutils）以及 C 标准库（C standard library，例如 GNU Libc、uClibc-ng）。

你的开发主机系统通常已自带一套编译工具链，可用于编译在本机运行的应用程序。如果你使用 PC，则该工具链在 x86 处理器上运行并生成 x86 代码。在大多数 Linux 系统中，工具链使用 GNU libc（glibc）作为 C 标准库。此类工具链称为“主机编译工具链”（host compilation toolchain），其运行的机器称为“主机系统”（host system）[3]。

主机编译工具链由发行版提供，Buildroot 仅使用它来构建交叉编译工具链及其他主机端工具。

如上所述，主机自带的工具链只能为主机处理器生成代码。嵌入式系统通常使用不同的处理器，因此需要交叉编译工具链（cross-compilation toolchain）：即在主机系统上运行、为目标系统（target system）和目标处理器生成代码的工具链。例如，主机为 x86，目标为 ARM，则主机工具链在 x86 上运行并生成 x86 代码，而交叉编译工具链在 x86 上运行并生成 ARM 代码。

Buildroot 提供两种交叉编译工具链方案：

内部工具链后端（internal toolchain backend），在配置界面中称为 Buildroot toolchain；
外部工具链后端（external toolchain backend），在配置界面中称为 External toolchain。

可在 Toolchain 菜单的 Toolchain Type 选项中选择方案。选择后会出现相应配置选项，详见下文。

6.1.1 内部工具链后端（Internal toolchain backend）

内部工具链后端 指 Buildroot 自行构建交叉编译工具链，然后再为目标嵌入式系统构建用户空间应用和库。

该后端支持多种 C 库：uClibc-ng、glibc 和 musl。

选择该后端后，可配置以下重要选项：

更改用于构建工具链的 Linux 内核头文件（kernel headers）版本。此项需特别说明：在构建交叉编译工具链过程中，需要构建 C 库。C 库为用户空间应用与 Linux 内核的接口。为实现此接口，C 库需访问 Linux 内核头文件（即内核的 .h 文件），这些头文件定义了用户空间与内核的接口（系统调用、数据结构等）。由于该接口向后兼容，构建工具链时使用的内核头文件版本无需与目标设备实际运行的内核版本完全一致，只需不高于目标内核版本即可。如果头文件版本高于目标内核，则 C 库可能会使用目标内核不支持的接口。
更改 GCC 编译器、binutils 及 C 库的版本。
选择多项工具链选项（仅 uClibc）：如是否支持 RPC（主要用于 NFS）、宽字符（wide-char）、本地化（locale，国际化）、C++ 支持、线程支持等。不同选项会影响 Buildroot 菜单中可见的用户空间应用和库：许多应用和库依赖特定工具链选项。大多数软件包在需要特定工具链选项时会有提示。如需进一步自定义 uClibc 配置，可运行 make uclibc-menuconfig。但需注意，Buildroot 仅测试其自带的 uClibc 默认配置：如自行裁剪 uClibc 功能，部分软件包可能无法编译。

注意：每当修改上述选项之一时，需重新构建整个工具链和系统。详见第 8.2 节 “何时需要全量重构”。

该后端优点：

与 Buildroot 集成良好
构建速度快，仅构建必要部分

缺点：

执行 make clean 时需重建工具链，耗时较长。如需缩短构建时间，可考虑外部工具链后端。

6.1.2 外部工具链后端（External toolchain backend）

外部工具链后端 允许使用已有的预编译交叉编译工具链。Buildroot 已内置多款知名交叉编译工具链（如 Linaro 针对 ARM，Sourcery CodeBench 针对 ARM、x86-64、PowerPC 和 MIPS），可自动下载，或指定自定义工具链（本地或可下载）。

使用外部工具链有三种方式：

使用预定义外部工具链配置文件，由 Buildroot 自动下载、解压和安装工具链。Buildroot 已内置部分 CodeSourcery 和 Linaro 工具链配置，只需在 Toolchain 菜单中选择即可。这是最简单的方式。
使用预定义外部工具链配置文件，但不让 Buildroot 下载和解压，而是手动指定已安装的工具链路径。在 Toolchain 菜单中选择配置，取消勾选 Download toolchain automatically，并在 Toolchain path 填写交叉编译工具链路径。
使用完全自定义的外部工具链。适用于用 crosstool-NG 或 Buildroot 自行生成的工具链。选择 Custom toolchain，填写 Toolchain path、Toolchain prefix 和 External toolchain C library。然后需告知 Buildroot 该工具链的支持特性：如为 glibc，只需说明是否支持 C++ 及内置 RPC；如为 uClibc，则需说明是否支持 RPC、宽字符、本地化、程序调用、线程和 C++。Buildroot 启动时会校验所选项与工具链配置是否匹配。

Buildroot 的外部工具链支持已在 CodeSourcery、Linaro、crosstool-NG 及 Buildroot 自身生成的工具链上测试。一般来说，支持 sysroot 特性的工具链均可用。如遇问题请联系开发者。

不支持 OpenEmbedded 或 Yocto 生成的工具链或 SDK，因为这些并非纯工具链（即仅包含编译器、binutils、C/C++ 库），而是包含大量预编译库和程序，Buildroot 无法导入其 sysroot，否则会包含数百兆预编译库，这些库本应由 Buildroot 构建。

也不支持将发行版自带工具链（即发行版安装的 gcc/binutils/C 库）作为目标软件编译工具链。因为发行版工具链并非“纯”工具链，无法正确导入 Buildroot 构建环境。即使目标为 x86 或 x86_64，也需用 Buildroot 或 crosstool-NG 生成交叉编译工具链。

如需为项目生成可用作 Buildroot 外部工具链的自定义工具链，建议用 Buildroot（见第 6.1.3 节 “用 Buildroot 构建外部工具链”）或 crosstool-NG 构建。

该后端优点：

可用知名、成熟的交叉编译工具链
避免了交叉编译工具链的构建时间，通常在嵌入式 Linux 系统整体构建时间中占比很大

缺点：

如预编译外部工具链有 bug，除非自行用 Buildroot 或 Crosstool-NG 构建，否则难以获得修复

[3] 主机系统（host system）：即你工作的开发主机。

6.1.3 使用 Buildroot 构建外部工具链

Buildroot 的内部工具链选项可用于创建外部工具链。以下是构建内部工具链并将其打包以供 Buildroot（或其他项目）复用的步骤：

新建 Buildroot 配置，主要设置如下：

在 目标选项（Target options） 中选择合适的目标 CPU 架构；
在 工具链（Toolchain） 菜单中，保持 工具链类型（Toolchain type） 为默认的 Buildroot toolchain，并按需配置工具链；
在 系统配置（System configuration） 菜单中，将 Init system 设为 None，将 * /bin/sh * 设为 none；
在 目标软件包（Target packages） 菜单中，禁用 BusyBox；
在 文件系统镜像（Filesystem images） 菜单中，禁用 tar the root filesystem。

然后，触发构建并让 Buildroot 生成 SDK，这会为你生成一个包含工具链的 tar 包：

make sdk

SDK tar 包会生成在 $(O)/images 目录下，文件名类似于 arm-buildroot-linux-uclibcgnueabi_sdk-buildroot.tar.gz。保存该 tar 包，即可在其他 Buildroot 项目中作为外部工具链复用。

在其他 Buildroot 项目中，在 工具链（Toolchain） 菜单：

设置 工具链类型（Toolchain type） 为 External toolchain；
设置 Toolchain 为 Custom toolchain；
设置 Toolchain origin 为 Toolchain to be downloaded and installed；
设置 Toolchain URL 为 file:///path/to/your/sdk/tarball.tar.gz。

外部工具链包装器（External toolchain wrapper）

使用外部工具链时，Buildroot 会生成一个包装程序（wrapper），自动为外部工具链程序传递合适参数（根据配置）。如需调试该包装器以检查实际传递的参数，可设置环境变量 BR2_DEBUG_WRAPPER，可选值如下：

0、空或未设置：无调试输出；
1：所有参数输出在一行；
2：每行输出一个参数。

6.2 /dev 管理

在 Linux 系统中，/dev 目录包含特殊文件，称为设备文件（device files），用于让用户空间应用访问由内核管理的硬件设备。没有这些设备文件，即使内核已识别硬件，用户空间应用也无法使用。

在 System configuration 的 /dev management 下，Buildroot 提供四种 /dev 目录管理方案：

第一种方案是 静态设备表（Static using device table）。这是 Linux 早期管理设备文件的传统方式。设备文件持久存储在根文件系统中（重启后依然存在），不会因硬件增减自动创建或删除。Buildroot 会用设备表（device table）创建一组标准设备文件，默认表位于 Buildroot 源码的 system/device_table_dev.txt。该文件在生成最终根文件系统镜像时处理，因此设备文件不会出现在 output/target 目录。BR2_ROOTFS_STATIC_DEVICE_TABLE 选项可更改默认设备表或添加额外设备表，以便在构建时创建更多设备文件。如需添加设备文件，可新建 board/<yourcompany>/<yourproject>/device_table_dev.txt，并将 BR2_ROOTFS_STATIC_DEVICE_TABLE 设为 system/device_table_dev.txt board/<yourcompany>/<yourproject>/device_table_dev.txt。设备表格式详见第 25 章 Makedev 语法文档。
第二种方案是 仅用 devtmpfs 动态管理（Dynamic using devtmpfs only）。devtmpfs 是内核 2.6.32 引入的虚拟文件系统（如用旧内核无法用此选项）。挂载到 /dev 后，内核会根据硬件增减自动动态创建和删除设备文件，但不会持久化。需启用内核配置 CONFIG_DEVTMPFS 和 CONFIG_DEVTMPFS_MOUNT。如 Buildroot 负责构建内核，会自动启用这两个选项；如在 Buildroot 外构建内核，需自行确保启用，否则 Buildroot 系统无法启动。
第三种方案是 devtmpfs + mdev 动态管理（Dynamic using devtmpfs + mdev）。此法同样依赖上述 devtmpfs（同样需启用 CONFIG_DEVTMPFS 和 CONFIG_DEVTMPFS_MOUNT），但在其基础上增加了 BusyBox 的 mdev 用户空间工具。每当设备增减，内核会调用 mdev，其行为可通过 /etc/mdev.conf 配置，如设置设备文件权限、归属、调用脚本等。这样，用户空间可对设备事件做出反应。mdev 还可用于设备出现时自动加载内核模块，或为需固件的设备推送固件。mdev 是 udev 的轻量实现。详见 http://git.busybox.net/busybox/tree/docs/mdev.txt。
第四种方案是 devtmpfs + eudev 动态管理（Dynamic using devtmpfs + eudev）。同样依赖 devtmpfs，但在其上运行 eudev 守护进程。eudev 是后台运行的守护进程，设备增减时由内核调用。比 mdev 更重，但更灵活。eudev 是 udev 的独立版本，udev 原为大多数桌面 Linux 发行版的用户空间守护进程，现已并入 Systemd。详见 http://en.wikipedia.org/wiki/Udev。

Buildroot 开发者建议优先使用 仅用 devtmpfs 动态管理（Dynamic using devtmpfs only），如需用户空间响应设备事件或需固件支持，则推荐 devtmpfs + mdev。

注意：如选择 systemd 作为 init system，则 /dev 管理由 systemd 提供的 udev 完成。

6.3 init 系统

init 程序是内核启动的第一个用户空间程序（PID 为 1），负责启动用户空间服务和程序（如 Web 服务器、图形应用、网络服务等）。

Buildroot 支持三种 init 系统，可在 System configuration 的 Init system 选择：

第一种方案是 BusyBox。BusyBox 除众多工具外，还实现了基本的 init 程序，足以满足大多数嵌入式系统。启用 BR2_INIT_BUSYBOX 后，BusyBox 会构建并安装其 init 程序（Buildroot 默认方案）。BusyBox 的 init 程序启动时读取 /etc/inittab 文件。该文件语法见 http://git.busybox.net/busybox/tree/examples/inittab（注意 BusyBox 的 inittab 语法特殊，请勿参考网络上其他 inittab 文档）。Buildroot 默认的 inittab 位于 package/busybox/inittab。除挂载重要文件系统外，默认 inittab 主要启动 /etc/init.d/rcS 脚本和 getty（登录提示）。
第二种方案是 systemV。采用传统的 sysvinit 程序，Buildroot 打包于 package/sysvinit。该方案曾为大多数桌面 Linux 发行版所用，后被 Upstart、Systemd 等替代。sysvinit 也用 inittab 文件（语法与 BusyBox 略有不同），默认 inittab 位于 package/sysvinit/inittab。
第三种方案是 systemd。systemd 是新一代 Linux init 系统，功能远超传统 init：支持激进的并行启动、基于 socket 和 D-Bus 的服务激活、按需启动守护进程、用 Linux 控制组跟踪进程、支持快照和恢复等。systemd 适用于较复杂的嵌入式系统（如需 D-Bus 及服务间通信）。需注意，systemd 依赖较多（如 dbus、udev 等）。详见 systemd。

Buildroot 开发者推荐使用 BusyBox init，足以满足大多数嵌入式系统。如需更复杂功能可选用 systemd。

[3] 该术语与 GNU configure 不同，后者将 host 定义为应用实际运行的机器（通常即 target）。

第 7 章其他组件的配置

在尝试修改下述任何组件前，请确保已配置好 Buildroot 本身，并已启用相应软件包。

BusyBox

如果已有 BusyBox 配置文件，可在 Buildroot 配置中通过 BR2_PACKAGE_BUSYBOX_CONFIG 直接指定该文件。否则，Buildroot 会从默认 BusyBox 配置文件开始。如需后续修改配置，可用 make busybox-menuconfig 打开 BusyBox 配置编辑器。也可通过环境变量指定 BusyBox 配置文件，但不推荐。详见第 8.6 节环境变量。
uClibc

uClibc 的配置方式与 BusyBox 类似。可用配置变量 BR2_UCLIBC_CONFIG 指定已有配置文件，后续修改可用 make uclibc-menuconfig。
Linux 内核

如已有内核配置文件，可在 Buildroot 配置中通过 BR2_LINUX_KERNEL_USE_CUSTOM_CONFIG 直接指定。如无配置文件，可在 Buildroot 配置中用 BR2_LINUX_KERNEL_USE_DEFCONFIG 指定 defconfig，或新建空文件并指定为自定义配置文件（BR2_LINUX_KERNEL_USE_CUSTOM_CONFIG）。后续修改可用 make linux-menuconfig。
Barebox

Barebox 的配置方式与 Linux 内核类似。相关配置变量为 BR2_TARGET_BAREBOX_USE_CUSTOM_CONFIG 和 BR2_TARGET_BAREBOX_USE_DEFCONFIG。配置编辑器命令为 make barebox-menuconfig。
U-Boot

U-Boot（2015.04 及以上版本）配置方式同 Linux 内核。相关配置变量为 BR2_TARGET_UBOOT_USE_CUSTOM_CONFIG 和 BR2_TARGET_UBOOT_USE_DEFCONFIG。配置编辑器命令为 make uboot-menuconfig。

第 8 章 Buildroot 常用用法

8.1 make 使用技巧

以下是帮助你高效使用 Buildroot 的技巧。

显示 make 执行的所有命令：

 $ make V=1 <target>

显示带 defconfig 的所有开发板列表：

 $ make list-defconfigs

显示所有可用目标：

 $ make help

并非所有目标始终可用，.config 文件中的部分设置会隐藏某些目标：

仅启用 busybox 时可用 busybox-menuconfig；
仅启用 linux 时可用 linux-menuconfig 和 linux-savedefconfig；
仅选择内部工具链为 uClibc 时可用 uclibc-menuconfig；
仅启用 barebox 启动加载器时可用 barebox-menuconfig 和 barebox-savedefconfig；
仅启用 U-Boot 启动加载器且构建系统为 Kconfig 时可用 uboot-menuconfig 和 uboot-savedefconfig。

清理： 如更改体系结构或工具链配置选项，需显式清理。

删除所有构建产物（包括构建目录、host、staging 和 target 树、镜像和工具链）：

 $ make clean

生成手册： 当前手册源码位于 docs/manual 目录。生成手册命令：

 $ make manual-clean
 $ make manual

手册输出位于 output/docs/manual。

注意

构建文档需安装部分工具（见第 2.2 节可选软件包）。

为新目标重置 Buildroot： 删除所有构建产物及配置：

 $ make distclean

注意： 如启用 ccache，运行 make clean 或 distclean 不会清空 Buildroot 使用的编译器缓存。清理方法见第 8.13.3 节 Buildroot 中使用 ccache。

导出 make 内部变量： 可导出 make 已知变量及其值：

 $ make -s printvars VARS='VARIABLE1 VARIABLE2'
 VARIABLE1=value_of_variable
 VARIABLE2=value_of_variable

可通过变量调整输出：

VARS will limit the listing to variables which names match the specified make-patterns - this must be set else nothing is printed
QUOTED_VARS, if set to YES, will single-quote the value
RAW_VARS, if set to YES, will print the unexpanded value

For example:

 $ make -s printvars VARS=BUSYBOX_%DEPENDENCIES
 BUSYBOX_DEPENDENCIES=skeleton toolchain
 BUSYBOX_FINAL_ALL_DEPENDENCIES=skeleton toolchain
 BUSYBOX_FINAL_DEPENDENCIES=skeleton toolchain
 BUSYBOX_FINAL_PATCH_DEPENDENCIES=
 BUSYBOX_RDEPENDENCIES=ncurses util-linux
 $ make -s printvars VARS=BUSYBOX_%DEPENDENCIES QUOTED_VARS=YES
 BUSYBOX_DEPENDENCIES='skeleton toolchain'
 BUSYBOX_FINAL_ALL_DEPENDENCIES='skeleton toolchain'
 BUSYBOX_FINAL_DEPENDENCIES='skeleton toolchain'
 BUSYBOX_FINAL_PATCH_DEPENDENCIES=''
 BUSYBOX_RDEPENDENCIES='ncurses util-linux'
 $ make -s printvars VARS=BUSYBOX_%DEPENDENCIES RAW_VARS=YES
 BUSYBOX_DEPENDENCIES=skeleton toolchain
 BUSYBOX_FINAL_ALL_DEPENDENCIES=$(sort $(BUSYBOX_FINAL_DEPENDENCIES) $(BUSYBOX_FINAL_PATCH_DEPENDENCIES))
 BUSYBOX_FINAL_DEPENDENCIES=$(sort $(BUSYBOX_DEPENDENCIES))
 BUSYBOX_FINAL_PATCH_DEPENDENCIES=$(sort $(BUSYBOX_PATCH_DEPENDENCIES))
 BUSYBOX_RDEPENDENCIES=ncurses util-linux

The output of quoted variables can be reused in shell scripts, for example:

 $ eval $(make -s printvars VARS=BUSYBOX_DEPENDENCIES QUOTED_VARS=YES)
 $ echo $BUSYBOX_DEPENDENCIES
 skeleton toolchain

8.2 何时需要全量重构

Buildroot 不会尝试自动检测在通过 make menuconfig、make xconfig 或其他配置工具更改系统配置后，哪些部分需要重建。有时应重建整个系统，有时只需重建部分软件包，但要完全可靠地检测这些情况非常困难，因此 Buildroot 开发者选择不做自动检测。

因此，用户需自行判断何时需要全量重构。以下经验法则可帮助你理解 Buildroot 的工作方式：

更改目标体系结构配置时，需全量重构。例如更改架构变体、二进制格式或浮点策略等会影响整个系统。
更改工具链配置时，通常也需全量重构。工具链配置变更通常涉及编译器版本、C 库类型或其配置等，这些都会影响整个系统。
新增软件包时，不一定需要全量重构。Buildroot 会检测到该包未被构建过并自动构建。但如该包为可被其他已构建包可选依赖的库，Buildroot 不会自动重建这些包。你需手动重建相关包，或全量重构。例如，已构建带 ctorrent、不带 openssl 的系统，后续启用 openssl 并重建，Buildroot 只会构建 openssl，不会自动重建 ctorrent 以启用 SSL。此时需手动重建 ctorrent 或全量重构。
移除软件包时，Buildroot 不会做特殊处理。不会从目标根文件系统或工具链 sysroot 中移除该包安装的文件。需全量重构才能彻底移除该包。但通常无需立即移除，可等下次完整构建时再处理。
更改软件包子选项时，Buildroot 不会自动重建该包。此时通常只需重建该包，除非新选项为其他已构建包提供了新特性。Buildroot 不追踪包的重建依赖：包一旦构建，除非显式指定，否则不会重建。
更改根文件系统 skeleton 时，需全量重构。但更改 rootfs overlay、post-build 脚本或 post-image 脚本时，无需全量重构，直接 make 即可生效。
当 FOO_DEPENDENCIES 中的软件包被重建或移除时，Buildroot 不会自动重建依赖该包的 foo 包。例如 FOO_DEPENDENCIES = bar，如更改 bar 配置，foo 不会自动重建。此时需手动重建所有依赖 bar 的包，或全量重构以确保依赖关系正确。

一般来说，如遇构建错误且不确定配置更改的影响，建议全量重构。若错误依旧，则可确定与部分重建无关。如为官方 Buildroot 包，欢迎报告问题！随着经验积累，你会逐步掌握何时需全量重构，从而节省时间。

全量重构命令如下：

$ make clean all

8.3 如何重建软件包

Buildroot 用户常问如何重建某个软件包或在不全量重构的情况下移除软件包。

Buildroot 不支持在不全量重构的情况下移除软件包。因为 Buildroot 不追踪各包在 output/staging 和 output/target 目录下安装了哪些文件，也不追踪哪些包会因其他包的可用性而编译出不同内容。

重建单个软件包最简单的方法是删除其在 output/build 下的构建目录。Buildroot 会重新解包、配置、编译并安装该包。可用 make <package>-dirclean 命令自动完成。

如只需从编译步骤重新构建包，可用 make <package>-rebuild，会重新编译和安装，但不会从头开始，仅重新构建有变更的文件。

如需从配置步骤重新构建包，可用 make <package>-reconfigure，会重新配置、编译和安装。

<package>-rebuild 隐含 <package>-reinstall，<package>-reconfigure 隐含 <package>-rebuild，这些目标及 <package> 只作用于该包本身，不会自动重建根文件系统镜像。如需重建根文件系统，需额外运行 make 或 make all。

Buildroot 内部用标记文件（stamp files）记录每个包的构建步骤，存于 output/build/<package>-<version>/，文件名为 .stamp_<step-name>。上述命令通过操作这些标记文件，强制 Buildroot 重新执行包的特定构建步骤。

更多包专用 make 目标详见第 8.13.5 节包专用 make 目标。

8.4 离线构建

如需离线构建，仅想下载配置器（menuconfig、nconfig、xconfig 或 gconfig）中已选软件包的所有源码，可运行：

 $ make source

此后即可断网或将 dl 目录内容拷贝到构建主机。

8.5 树外构建（out-of-tree build）

默认情况下，Buildroot 构建的所有内容都存储在 Buildroot 树下的 output 目录。

Buildroot 也支持类似 Linux 内核的树外构建。用法是在 make 命令行加 O=<目录>：

 $ make O=/tmp/build menuconfig

或：

 $ cd /tmp/build; make O=$PWD -C path/to/buildroot menuconfig

所有输出文件都位于 /tmp/build。如 O 路径不存在，Buildroot 会自动创建。

注意： O 路径可为绝对或相对路径，但如为相对路径，则相对于 Buildroot 源码主目录（而非当前工作目录）。

使用树外构建时，Buildroot 的 .config 和临时文件也存储在输出目录。这样可在同一源码树下并行运行多个构建，只需保证输出目录唯一。

为方便使用，Buildroot 会在输出目录生成 Makefile 包装器——首次运行后，无需再传递 O=<…> 和 -C <…>，只需在输出目录下直接运行：

 $ make <target>

8.6 环境变量

Buildroot 支持部分环境变量，可在调用 make 时传递或在环境中设置：

HOSTCXX：主机 C++ 编译器
HOSTCC：主机 C 编译器
UCLIBC_CONFIG_FILE=<path/to/.config>：uClibc 配置文件路径（如构建内部工具链）。uClibc 配置文件也可在 Buildroot 配置界面设置，推荐用 .config 文件方式。
BUSYBOX_CONFIG_FILE=<path/to/.config>：BusyBox 配置文件路径。也可在 Buildroot 配置界面设置，推荐用 .config 文件方式。
BR2_CCACHE_DIR：覆盖 Buildroot 使用 ccache 时缓存文件的目录。
BR2_DL_DIR：覆盖 Buildroot 下载/检索文件的目录。下载目录也可在 Buildroot 配置界面设置，推荐用 .config 文件方式。详见第 8.13.4 节下载包位置。
BR2_GRAPH_ALT：如设置且非空，构建时图表使用备用配色方案。
BR2_GRAPH_OUT：设置生成图表的文件类型，pdf（默认）或 png。
BR2_GRAPH_DEPS_OPTS：为依赖关系图传递额外选项，详见第 8.9 节包依赖关系图。
BR2_GRAPH_DOT_OPTS：原样传递给 dot 工具以绘制依赖关系图。
BR2_GRAPH_SIZE_OPTS：为大小图传递额外选项，详见第 8.11 节文件系统大小图。

示例：配置文件分别位于顶层目录和 $HOME：

 $ make UCLIBC_CONFIG_FILE=uClibc.config BUSYBOX_CONFIG_FILE=$HOME/bb.config

如需为主机端辅助二进制选择非默认 gcc 或 g++ 编译器：

 $ make HOSTCXX=g++-4.3-HEAD HOSTCC=gcc-4.3-HEAD

8.7 高效处理文件系统镜像

文件系统镜像体积可能很大，取决于文件系统类型、软件包数量、预留空间等。但镜像中部分区域可能只是空（如长串零），这种文件称为稀疏文件（sparse file）。

大多数工具可高效处理稀疏文件，仅存储/写入非零部分。

例如：

tar 支持 -S 选项，仅存储稀疏文件的非零块：
- tar cf archive.tar -S [files…] 可高效打包稀疏文件
- tar xf archive.tar -S 可高效解包稀疏文件
cp 支持 --sparse=WHEN 选项（WHEN 可为 auto、never 或 always）：
- cp --sparse=always source.file dest.file 如源文件有长零区，目标文件也会为稀疏文件

其他工具也有类似选项，详见各自 man 手册。

如需存储、传输文件系统镜像（如跨机传输或发给 QA），可用稀疏文件。

但注意：用 dd 的稀疏模式刷写镜像到设备可能导致文件系统损坏（如 ext2 的块位图损坏，或稀疏文件部分读回时非全零）。稀疏文件仅适用于构建机本地操作，不应用于实际设备刷写。

8.8 关于软件包的详细信息

Buildroot 可生成 JSON 格式的摘要，描述当前配置下已启用软件包的集合，包括其依赖关系、许可证及其他元数据。可通过 show-info make 目标生成：

make show-info

Buildroot 还可通过 pkg-stats make 目标生成软件包详细信息（HTML 和 JSON 格式）。其中包括当前配置下软件包是否受已知 CVE（安全漏洞）影响，以及是否有上游新版本。

make pkg-stats

8.9 软件包依赖关系图

Buildroot 负责管理软件包间的依赖关系，确保按正确顺序构建。这些依赖有时很复杂，理解某个包为何被 Buildroot 引入并不容易。

为帮助理解依赖关系、理清嵌入式 Linux 系统各组件作用，Buildroot 可生成依赖关系图。

生成全系统依赖关系图：

make graph-depends

生成的图位于 output/graphs/graph-depends.pdf。

如系统较大，依赖图可能过于复杂。可仅为某个包生成依赖图：

make <pkg>-graph-depends

生成的图位于 output/graph/<pkg>-graph-depends.pdf。

依赖关系图由 Graphviz 项目的 dot 工具生成，需预先安装（大多数发行版包名为 graphviz）。

默认输出为 PDF 格式。可通过 BR2_GRAPH_OUT 环境变量切换为 PNG、PostScript、SVG 等（所有 dot 工具 -T 选项支持的格式均可用）。

BR2_GRAPH_OUT=svg make graph-depends

graph-depends 行为可通过 BR2_GRAPH_DEPS_OPTS 环境变量设置。可用选项：

--depth N 或 -d N：限制依赖深度为 N 层，默认 0 表示无限制。
--stop-on PKG 或 -s PKG：在包 PKG 处停止绘制。PKG 可为包名、通配符、virtual（虚包）、host（主机包）。该包仍在图中，但不再展开其依赖。
--exclude PKG 或 -x PKG：同 --stop-on，但图中不显示该包。
--transitive、--no-transitive：是否绘制传递依赖。默认不绘制。
--colors R,T,H：设置根包（R）、目标包（T）、主机包（H）的颜色，默认 lightblue,grey,gainsboro。

BR2_GRAPH_DEPS_OPTS='-d 3 --no-transitive --colors=red,green,blue' make graph-depends

8.10 构建时长分析图

如系统构建耗时较长，可分析各包构建耗时以优化构建速度。Buildroot 会收集每个包各步骤的构建时长，并可生成图表。

构建后生成时长分析图：

make graph-build

生成文件位于 output/graphs：

build.hist-build.pdf：按构建顺序排列的各包构建时长直方图
build.hist-duration.pdf：按时长降序排列的各包构建时长直方图
build.hist-name.pdf：按包名排列的各包构建时长直方图
build.pie-packages.pdf：各包构建时长饼图
build.pie-steps.pdf：各步骤总耗时饼图

graph-build 目标需安装 Python Matplotlib 和 Numpy 库（大多数发行版为 python-matplotlib 和 python-numpy），如 Python 版本低于 2.7 还需 argparse 模块。

默认输出为 PDF 格式，可用 BR2_GRAPH_OUT 环境变量切换为 PNG：

BR2_GRAPH_OUT=png make graph-build

8.11 软件包对文件系统大小的贡献分析

随着目标系统体积增大，了解各 Buildroot 软件包对根文件系统总体积的贡献变得很有价值。为此，Buildroot 会收集每个包安装的文件数据，并据此生成图表和 CSV 文件，详细展示各包的体积贡献。

构建后生成这些数据：

make graph-size

将生成：

output/graphs/graph-size.pdf：各包对根文件系统总体积贡献的饼图
output/graphs/package-size-stats.csv：各包对根文件系统总体积贡献的 CSV 文件
output/graphs/file-size-stats.csv：每个已安装文件对所属包及总体积贡献的 CSV 文件

graph-size 目标需安装 Python Matplotlib 库（大多数发行版为 python-matplotlib），如 Python 版本低于 2.7 还需 argparse 模块。

如同时长分析图，可用 BR2_GRAPH_OUT 环境变量调整输出格式。详见第 8.9 节包依赖关系图。

还可用环境变量 BR2_GRAPH_SIZE_OPTS 进一步控制生成的图表。可用选项：

--size-limit X 或 -l X：将单个包贡献低于 X 百分比的包合并为 Others，默认 X=0.01（即低于 1% 的包合并）。取值范围 [0.0..1.0]。
--iec、--binary、--si、--decimal：选择 IEC（二进制，1024 进制）或 SI（十进制，1000 进制，默认）前缀。
--biggest-first：按包体积降序排列，而非升序。

注意： 文件系统体积数据仅在完全 clean 重构后才有意义。请先运行 make clean all 再用 make graph-size。

如需比较两次 Buildroot 编译的根文件系统体积（如调整配置或切换 Buildroot 版本后），可用 size-stats-compare 脚本。该脚本以两份 file-size-stats.csv（由 make graph-size 生成）为输入。详细用法见脚本帮助：

utils/size-stats-compare -h

8.12 顶层并行构建（Top-level parallel build）

注意： 本节介绍的为实验性功能，已知在部分常见场景下会出错，请谨慎使用。

Buildroot 一直支持包内并行构建：每个包用 make -jN（或等效命令）构建，默认并行度为 CPU 数 + 1，可通过 BR2_JLEVEL 配置调整。

直到 2020.02 版本，Buildroot 仍以串行方式构建各包：每次只构建一个包，包间无并行。自 2020.02 起，Buildroot 实验性支持顶层并行构建，可并行构建无依赖关系的包，显著缩短构建时间。但该功能仍为实验性，部分场景下已知不可用。

使用顶层并行构建需：

在 Buildroot 配置中启用 BR2_PER_PACKAGE_DIRECTORIES 选项
构建时用 make -jN

内部实现上，BR2_PER_PACKAGE_DIRECTORIES 会启用每包独立目录（per-package directories）机制，具体效果如下：

不再有全局 target 和 host 目录，每个包有独立的 target 和 host 目录，分别位于 $(O)/per-package/<pkg>/target/ 和 $(O)/per-package/<pkg>/host/。这些目录在 <pkg> 构建前从依赖包目录同步。编译器和工具只能访问 <pkg> 显式依赖包安装的文件。
构建结束后，全局 target 和 host 目录才会被填充，分别位于 $(O)/target 和 $(O)/host。构建期间这两个目录为空，只有在构建结束时才填充。

8.13 高级用法

8.13.1 在 Buildroot 外部使用生成的工具链

你可能希望为目标设备编译 Buildroot 未打包的软件或自有程序。此时可直接使用 Buildroot 生成的工具链。

Buildroot 生成的工具链默认位于 output/host/。最简单的用法是将 output/host/bin/ 加入 PATH，然后使用 ARCH-linux-gcc、ARCH-linux-objdump、ARCH-linux-ld 等。

另外，Buildroot 也可通过 make sdk 导出工具链及所有已选包的开发文件，生成 SDK。该命令会将 output/host/ 内容打包为 <TARGET-TUPLE>_sdk-buildroot.tar.gz（可通过环境变量 BR2_SDK_PREFIX 覆盖），存放于 output/images/。

该 tar 包可分发给应用开发者，用于开发尚未打包为 Buildroot 包的应用。

解压 SDK tar 包后，用户需运行 SDK 顶层目录下的 relocate-sdk.sh 脚本，以更新所有路径。

如只需准备 SDK 而不打包（如仅移动 host 目录或自行打包），可用 make prepare-sdk。

如启用 BR2_PACKAGE_HOST_ENVIRONMENT_SETUP，output/host/ 及 SDK 中会安装 environment-setup 脚本。可用 . your/sdk/path/environment-setup 导出一系列环境变量，便于用 Buildroot SDK 交叉编译项目：PATH 会包含 SDK 二进制，标准 autotools 变量会自动设置，CONFIGURE_FLAGS 包含 autotools 项目交叉编译的基本 ./configure 选项，还提供部分实用命令。注意：sourcing 该脚本后，环境仅适用于交叉编译，不再适用于本地编译。

8.13.2 在 Buildroot 中使用 `gdb`

Buildroot 支持交叉调试：调试器运行在构建机，通过 gdbserver 与目标设备通信，控制程序执行。

操作步骤：

如用内部工具链（Buildroot 构建），需启用 BR2_PACKAGE_HOST_GDB、BR2_PACKAGE_GDB 和 BR2_PACKAGE_GDB_SERVER，确保交叉 gdb 和 gdbserver 均被构建，gdbserver 安装到目标设备。
如用外部工具链，应启用 BR2_TOOLCHAIN_EXTERNAL_GDB_SERVER_COPY，将外部工具链自带的 gdbserver 拷贝到目标。如外部工具链无交叉 gdb 或 gdbserver，也可让 Buildroot 构建，方法同内部工具链。

调试名为 foo 的程序时，目标设备运行：

gdbserver :2345 foo

此时 gdbserver 监听 2345 端口，等待交叉 gdb 连接。

主机端启动交叉 gdb：

<buildroot>/output/host/bin/<tuple>-gdb -ix <buildroot>/output/staging/usr/share/buildroot/gdbinit foo

注意：foo 需带调试符号，建议在其构建目录下运行该命令（output/target/ 下的二进制已剥离）。

<buildroot>/output/staging/usr/share/buildroot/gdbinit 文件会告知交叉 gdb 目标库文件位置。

最后，在交叉 gdb 中连接目标：

(gdb) target remote <target ip address>:2345

8.13.3 在 Buildroot 中使用 `ccache`

ccache 是编译器缓存工具。它缓存每次编译生成的目标文件，后续相同源码（编译器及参数一致）可直接复用缓存，加快多次相似全量构建。

Buildroot 集成了 ccache 支持。只需在 Build options 启用“Enable compiler cache”，即可自动构建并为所有主机和目标编译启用 ccache。

缓存目录由 BR2_CCACHE_DIR 配置项指定，默认 $HOME/.buildroot-ccache。该目录位于 Buildroot 输出目录之外，便于多个 Buildroot 构建共享。如需清理缓存，直接删除该目录即可。

可用 make ccache-stats 查看缓存统计（大小、命中/未命中等）。

ccache-options make 目标和 CCACHE_OPTIONS 变量可用于通用 ccache 操作。例如：

# 设置缓存大小上限
make CCACHE_OPTIONS="--max-size=5G" ccache-options

# 清零统计计数器
make CCACHE_OPTIONS="--zero-stats" ccache-options

ccache 会对源码和编译参数做哈希。若编译参数不同，则不会复用缓存。许多编译参数包含绝对路径（如 staging 目录），因此更换输出目录会导致大量缓存未命中。

为避免此问题，Buildroot 提供“Use relative paths”选项（BR2_CCACHE_USE_BASEDIR），会将输出目录内的绝对路径重写为相对路径，从而更换输出目录时不影响缓存命中。

缺点是目标文件中的路径也变为相对路径，调试时需先切换到输出目录。

详见 ccache 手册“在不同目录编译”章节。

启用 BR2_CCACHE=y 后：

Buildroot 构建过程会用 ccache
在 Buildroot 外部（如直接调用交叉编译器或用 SDK）不会用 ccache

可用 BR2_USE_CCACHE 环境变量覆盖此行为：设为 1 时启用（Buildroot 构建默认），未设或非 1 时禁用。

8.13.4 下载包的位置

Buildroot 下载的各类 tar 包均存储在 BR2_DL_DIR，默认是 dl 目录。如需保留一份与 tar 包配套、可复现的 Buildroot 版本，可直接复制该目录。这样可确保工具链和目标文件系统可用完全相同的源码重建。

如维护多个 Buildroot 树，建议用共享下载目录。可将 BR2_DL_DIR 环境变量指向该目录，此时会覆盖 Buildroot 配置中的 BR2_DL_DIR。可在 <~/.bashrc> 添加：

 export BR2_DL_DIR=<shared download location>

下载目录也可在 .config 文件用 BR2_DL_DIR 选项设置，但该值会被环境变量覆盖。

8.13.5 包专用 make 目标

运行 make <package> 会构建并安装该包及其依赖。

依赖 Buildroot 基础设施的软件包有许多专用 make 目标，可独立调用：

make <package>-<target>

包构建目标（按执行顺序）：

命令/目标	说明
`source`	获取源码（下载 tar 包、克隆源码仓库等）
`depends`	构建并安装构建该包所需的所有依赖
`extract`	将源码放入包构建目录（解包、复制源码等）
`patch`	应用补丁（如有）
`configure`	运行配置命令（如有）
`build`	运行编译命令
`install-staging`	目标包：安装到 staging 目录（如有必要）
`install-target`	目标包：安装到 target 目录（如有必要）
`install`	目标包：运行前两步安装命令；主机包：安装到 host 目录

其他常用 make 目标：

命令/目标	说明
`show-depends`	显示构建该包所需的一阶依赖
`show-recursive-depends`	递归显示构建该包所需的所有依赖
`show-rdepends`	显示直接依赖该包的包（一阶反向依赖）
`show-recursive-rdepends`	递归显示所有依赖该包的包（直接或间接）
`graph-depends`	生成该包的依赖关系图，详见依赖关系图章节
`graph-rdepends`	生成该包的反向依赖关系图
`graph-both-depends`	生成该包的正反向依赖关系图
`dirclean`	删除整个包的构建目录
`reinstall`	重新运行安装命令
`rebuild`	重新运行编译命令（仅适用于 OVERRIDE_SRCDIR 或直接修改构建目录源码）
`reconfigure`	重新运行配置命令并重编译（仅适用于 OVERRIDE_SRCDIR 或直接修改构建目录源码）

8.13.6 开发阶段使用 Buildroot

Buildroot 正常流程为：下载 tar 包、解包、配置、编译、安装。源码解包到 output/build/<package>-<version>，该目录为临时目录，make clean 时会被删除并在下次 make 时重建。即使源码为 Git 或 SVN 仓库，Buildroot 也会先打包再解包，流程一致。

此流程适合 Buildroot 作为集成工具使用。但如需开发某组件，直接在 output/build/<package>-<version> 修改源码并不合适，因为 make clean 会删除该目录。

为此，Buildroot 提供 <pkg>_OVERRIDE_SRCDIR 机制。Buildroot 会读取 override 文件，允许用户指定某些包的源码路径。

override 文件默认位置为 $(CONFIG_DIR)/local.mk，由 BR2_PACKAGE_OVERRIDE_FILE 配置。$(CONFIG_DIR) 为 Buildroot .config 所在目录，即：

树内构建（未用 O=）时为 Buildroot 源码主目录
树外构建（用 O=）时为输出目录

如需自定义 override 文件位置，可用 BR2_PACKAGE_OVERRIDE_FILE 配置。

override 文件内容格式：

<pkg1>_OVERRIDE_SRCDIR = /path/to/pkg1/sources
<pkg2>_OVERRIDE_SRCDIR = /path/to/pkg2/sources

示例：

LINUX_OVERRIDE_SRCDIR = /home/bob/linux/
BUSYBOX_OVERRIDE_SRCDIR = /home/bob/busybox/

如为某包定义了 <pkg>_OVERRIDE_SRCDIR，Buildroot 不再下载、解包、打补丁，而是直接用指定目录源码，make clean 也不会影响该目录。这样可将 Buildroot 指向你用 Git、SVN 等管理的源码目录。Buildroot 会用 rsync 将 <pkg>_OVERRIDE_SRCDIR 下源码同步到 output/build/<package>-custom/。

此机制建议结合 make <pkg>-rebuild 和 make <pkg>-reconfigure 使用。make <pkg>-rebuild all 会用 rsync 同步源码（仅同步变更文件），并重启该包的构建流程。

如上例，开发者可在 /home/bob/linux 修改源码后运行：

make linux-rebuild all

几秒后即可在 output/images 得到更新的内核镜像。同理，修改 /home/bob/busybox 后：

make busybox-rebuild all

output/images 下的根文件系统镜像即包含更新后的 BusyBox。

第 9 章项目定制

对于特定项目，你可能需要执行的典型操作包括：

配置 Buildroot（包括构建选项和工具链、引导加载程序、内核、软件包和文件系统镜像类型的选择）
配置其他组件，如 Linux 内核和 BusyBox（原文：BusyBox）
定制生成的目标文件系统
- 在目标文件系统上添加或覆盖文件（使用 BR2_ROOTFS_OVERLAY）
- 修改或删除目标文件系统上的文件（使用 BR2_ROOTFS_POST_BUILD_SCRIPT）
- 在生成文件系统镜像前运行任意命令（使用 BR2_ROOTFS_POST_BUILD_SCRIPT）
- 设置文件权限和所有权（使用 BR2_ROOTFS_DEVICE_TABLE）
- 添加自定义设备节点（使用 BR2_ROOTFS_STATIC_DEVICE_TABLE）
添加自定义用户账户（使用 BR2_ROOTFS_USERS_TABLES）
在生成文件系统镜像后运行任意命令（使用 BR2_ROOTFS_POST_IMAGE_SCRIPT）
为某些软件包添加项目专属补丁（使用 BR2_GLOBAL_PATCH_DIR）
添加项目专属软件包