Buildroot 用户手册 (中文)

本文为译文，英文原文地址：The Buildroot user manual

Buildroot是一个工具，它使用交叉编译简化了为嵌入式系统构建完整Linux系统的过程，并实现了自动化。

为了实现这一点，Buildroot能够为您的目标生成交叉编译工具链( a cross-compilation toolchain)、根文件系统(a root filesystem)、Linux内核映像(a Linux kernel image)和引导加载程序(a bootloader)。Buildroot可以独立地用于这些选项的任何组合(例如，您可以使用现有的交叉编译工具链，只用Buildroot构建您的根文件系统)。

Buildroot主要适用于使用嵌入式系统的人。嵌入式系统通常使用的处理器不是每个人都习惯在个人电脑中使用的常规x86处理器。它们可以是PowerPC处理器，MIPS处理器，ARM处理器等。

Buildroot支持许多处理器及其变体;它还提供了几种现成电路板的默认配置。除此之外，很多第三方项目都是基于，或者在Buildroot之上开发他们的BSP[1]或SDK[2]。

Buildroot设计用于在Linux系统上运行。

虽然Buildroot本身将构建它编译所需的大多数主机包，但某些标准的Linux实用程序预计已经安装在主机系统上。下面是强制包和可选包的概述(注意，不同发行版的包名称可能有所不同)。

以下是 Linux 环境上必须安装的程序：

以下是可选安装的程序：

Buildroot中的一些特性或实用程序，如the legal-info或the graph generation tools，有额外的依赖关系。尽管它们不是简单构建的强制要求，但仍然强烈推荐使用:

对于这些库，您需要同时安装运行时数据和开发数据，在许多发行版中，这些数据是单独打包的。开发包通常有一个-dev或-devel后缀。

在官方树中，大多数包源都是使用wget从ftp、http或https位置检索的。少数软件包只能通过版本控制系统获得。此外，Buildroot还可以通过其他工具下载资源，如rsync或scp(参阅第20章，下载基础设施了解更多细节)。如果您使用以下任何一种方法启用包，您将需要在主机系统上安装相应的工具:

Buildroot版本每3个月发布一次，分别是在2月、5月、8月和11月。版本号的格式为YYYY.MM，例如2013.02,2014.08。发布tarball可以在http://buildroot.org/downloads/上找到。

有两种方式可以搭建起 Buildroot 开发环境：

为方便起见，在Buildroot源代码树的support/misc/Vagrantfile中提供了一个Vagrantfile，用于快速设置一个虚拟机，其中包含启动所需的依赖项。

如果你想在Linux或Mac Os X上建立一个独立的构建根环境，请将这一行粘贴到你的终端上:

如果你在Windows上，把这个粘贴到你的powershell:

如果您想继续开发，可以使用日常快照或复制Git存储库。更多详细信息，请参考Buildroot网站的下载页面。

重要:你可以并且应该像普通用户一样构建一切。配置和使用Buildroot不需要是root。通过作为普通用户运行所有命令，可以保护系统免受包在编译和安装期间行为不正常的影响。

使用Buildroot的第一步是创建一个配置。Buildroot有一个很好的配置工具，类似于您可以在Linux内核或BusyBox中找到的那个。

From the buildroot directory, run

for the original curses-based configurator, or

for the new curses-based configurator, or

for the Qt-based configurator, or

for the GTK-based configurator.

所有这些make命令都需要构建一个配置实用程序(包括接口)，因此您可能需要为配置实用程序使用的相关库安装“开发”包。请参阅第2章 系统需求，以获得更多的细节，特别是可选的需求，以获得您喜欢的接口的依赖关系。

对于配置工具中的每个菜单项，您可以找到描述该项用途的相关帮助。关于一些具体配置方面的细节，请参阅第6章 Buildroot配置。

一旦一切配置完成，配置工具将生成一个包含整个配置的.config文件。这个文件将由顶级Makefile读取。

要启动构建过程，只需运行:

默认情况下，Buildroot不支持顶级并行构建，所以没有必要运行make -jN。不过，也有对顶层并行构建的实验性支持，请参见8.12节“顶层并行构建”。

上述make命令一般执行如下步骤:

Buildroot输出存储在单个目录output/中。这个目录包含几个子目录:

这些命令make menuconfig|nconfig|gconfig|xconfig和make是最基本的命令，它们允许您通过启用的所有特性和应用程序轻松快速地生成符合您需求的图像。

关于make命令使用的更多细节在8.1节“make tips”中给出。

社区资源 (略)。

make *config中的所有配置选项都有一个帮助文本，提供关于该选项的详细信息。

make *config命令也提供了一个搜索工具。阅读不同前端菜单中的帮助信息，了解如何使用它:

搜索结果显示匹配项的帮助信息。在menuconfig中，左边列中的数字为相应的条目提供了快捷方式。只要输入这个数字就可以直接跳转到条目，或者跳转到包含的菜单(如果条目由于缺少依赖项而无法选择的话)。

尽管条目的菜单结构和帮助文本应该具有足够的自解释性，但有一些主题需要额外的解释，这些内容不容易在帮助文本中介绍，因此将在下面的部分中介绍。

编译工具链是一组允许您为系统编译代码的工具。它包括一个编译器(在我们的例子中是gcc)、汇编器和链接器之类的二进制utils(在我们的例子中是binutils)和一个C标准库(例如GNU Libc, uClibc-ng)。

安装在开发站上的系统肯定已经有一个编译工具链，您可以使用它编译在系统上运行的应用程序。如果您使用的是PC，那么编译工具链运行在x86处理器上，并为x86处理器生成代码。在大多数Linux系统下，编译工具链使用GNU libc (glibc)作为C标准库。这个编译工具链称为“宿主编译工具链”。运行它和您工作的机器称为“主机系统”[3]。

编译工具链由您的发行版提供，而Buildroot与它无关(除了使用它来构建交叉编译工具链和在开发主机上运行的其他工具)。

如上所述，系统附带的编译工具链运行在主机系统中的处理器上并为其生成代码。由于嵌入式系统具有不同的处理器，因此需要一个交叉编译工具链——一个运行在主机系统上但为目标系统(和目标处理器)生成代码的编译工具链。例如，如果您的主机系统使用x86，而目标系统使用ARM，那么主机上的常规编译工具链运行在x86上并生成针对x86的代码，而交叉编译工具链运行在x86上并生成针对ARM的代码。

Buildroot为交叉编译工具链提供了两种解决方案:

使用Toolchain菜单中的Toolchain Type选项可以在这两个解决方案之间进行选择。一旦选择了一个解决方案，就会出现许多配置选项，以下部分将详细介绍这些选项。

在为目标嵌入式系统构建用户空间应用程序和库之前，内部工具链后端是Buildroot自己构建交叉编译工具链的后端。

这个后端支持几个C库:uClibc-ng、glibc和musl。

一旦您选择了这个后端，就会出现许多选项。最重要的是以下选项:

值得注意的是，每当其中一个选项被修改时，就必须重新构建整个工具链和系统。请参阅第8.2节 “了解什么时候需要进行完全重建”。

这个后端的优点:

这个后端的缺点:

外部工具链后端允许使用现有的预构建的交叉编译工具链。Buildroot知道许多著名的交叉编译工具链(从Linaro for ARM、Sourcery CodeBench for ARM、x86-64、PowerPC和MIPS)，并且能够自动下载它们，或者它可以指向一个定制的工具链，可以下载或在本地安装。

目前，你有三个解决方案来使用外部工具链:

我们的外部工具链支持已经通过来自CodeSourcery和Linaro的工具链、由crosstool-NG生成的工具链和由Buildroot本身生成的工具链进行了测试。一般来说，所有支持sysroot特性的工具链都应该工作。如果没有，不要犹豫联系开发人员。

我们不支持openenembedded或Yocto生成的工具链或SDK，因为这些工具链不是纯工具链(即编译器、binutils、C和c++库)。相反，这些工具链带有一组非常大的预编译库和程序。因此，Buildroot不能导入工具链的sysroot，因为它将包含数百兆字节的预编译库，而这些库通常是由Buildroot构建的。

我们也不支持使用发行版工具链(即由发行版安装的gcc/binutils/C库)作为构建目标软件的工具链。这是因为你的分发工具链不是一个“纯”的工具链(即只使用C/ c++库)，所以我们不能正确地将它导入Buildroot构建环境中。因此，即使您正在为x86或x86_64目标构建系统，也必须使用Buildroot或crosstool-NG生成交叉编译工具链。

如果你想为你的项目生成一个自定义的工具链，可以在Buildroot中作为外部工具链使用，我们的建议是使用Buildroot本身(见6.1.3节“使用Buildroot构建一个外部工具链”)或者使用crosstool-NG。

这个后端的优点:

这个后端的缺点:

Buildroot内部工具链选项可用于创建外部工具链。下面是构建内部工具链并将其打包以供Buildroot自身(或其他项目)重用的一系列步骤。

1、创建一个新的Buildroot配置，详细信息如下:

2、然后，我们可以触发构建，并要求Buildroot生成一个SDK。这将方便地为我们生成一个包含工具链的tarball:

这将在$(O)/images中生成SDK tarball，其名称类似于arm-buildroot-linux-uclibcgnueabi_sdk-buildroot.tar.gz。保存这个tarball，因为现在它是您可以在其他Buildroot项目中作为外部工具链重用的工具链。

3、在其他的Buildroot项目中，在Toolchain菜单中:

当使用外部工具链时，Buildroot生成一个wrapper程序，该程序透明地将适当的选项(根据配置)传递给外部工具链程序。如果您需要调试这个wrapper来检查传递了哪些参数，您可以将环境变量BR2_DEBUG_WRAPPER设置为以下任意一个:

在Linux系统中，/dev目录包含特殊的文件，称为设备文件(device files)，允许用户空间应用程序访问Linux内核管理的硬件设备。如果没有这些设备文件，您的用户空间应用程序将不能使用硬件设备，即使它们被Linux内核正确识别。

在System configuration,/dev management下，Buildroot提供了四种不同的解决方案来处理/dev目录:

Buildroot开发人员的建议是从Dynamic using devtmpfs only的解决方案开始，直到您需要通知用户空间何时添加/删除设备，或是否需要固件，在这种情况下，Dynamic using devtmpfs + mdev通常是一个很好的解决方案。

注意，如果选择systemd作为init系统，/dev管理将由systemd提供的udev程序执行。

init程序是由内核启动的第一个用户空间程序(它的PID号为1)，负责启动用户空间服务和程序(例如:web服务器、图形应用程序、其他网络服务器等)。

Buildroot允许使用三种不同类型的初始化系统，可以从System configuration, Init system中选择:

Buildroot开发人员推荐的解决方案是使用BusyBox init，因为它对于大多数嵌入式系统来说已经足够了。Systemd可以用于更复杂的情况。

在尝试修改下面的任何组件之前，请确保您已经配置了Buildroot本身，并启用了相应的包。

如果您已经有一个BusyBox配置文件，您可以直接在Buildroot配置中指定这个文件，使用BR2_PACKAGE_BUSYBOX_CONFIG。否则，Buildroot将从默认的BusyBox配置文件启动。

要对配置进行后续更改，请使用make busybox-menuconfig打开BusyBox配置编辑器。

还可以通过环境变量指定BusyBox配置文件，不过不建议这样做。请参阅8.6节“环境变量”了解更多细节。

uClibc的配置方法与BusyBox相同。指定现有配置文件的配置变量是BR2_UCLIBC_CONFIG。进行后续更改的命令是make uclibc-menuconfig。

如果您已经有了一个内核配置文件，那么可以使用BR2_LINUX_KERNEL_USE_CUSTOM_CONFIG在Buildroot配置中直接指定这个文件。

如果您还没有内核配置文件，那么您可以使用BR2_LINUX_KERNEL_USE_DEFCONFIG在Buildroot配置中指定defconfig，或者使用BR2_LINUX_KERNEL_USE_CUSTOM_CONFIG创建一个空文件并将其指定为自定义配置文件。

要对配置进行后续更改，请使用make Linux-menuconfig打开Linux配置编辑器。

Barebox的配置方法与Linux内核的配置方法相同。对应的配置变量是BR2_TARGET_BAREBOX_USE_CUSTOM_CONFIG和BR2_TARGET_BAREBOX_USE_DEFCONFIG。要打开配置编辑器，请使用make barebox-menuconfig。

U-Boot(2015.04及以上版本)的配置方法与Linux内核相同。对应的配置变量是BR2_TARGET_UBOOT_USE_CUSTOM_CONFIG和BR2_TARGET_UBOOT_USE_DEFCONFIG。打开配置编辑器，使用make uboot-menuconfig。

这是一组技巧，可以帮助你充分利用Buildroot。

并不是所有的目标都是可用的，.config文件中的一些设置可能会隐藏一些目标:

busybox-menuconfig only works when busybox is enabled; linux-menuconfig and linux-savedefconfig only work when linux is enabled; uclibc-menuconfig is only available when the uClibc C library is selected in the internal toolchain backend; barebox-menuconfig and barebox-savedefconfig only work when the barebox bootloader is enabled. uboot-menuconfig and uboot-savedefconfig only work when the U-Boot bootloader is enabled.

To delete all build products (including build directories, host, staging and target trees, the images and the toolchain)😕/ 删除所有构建产品(包括构建目录、主机、暂存和目标树、映像和工具链):

如果启用了ccache，运行make clean或distclean不会清空Buildroot使用的编译器缓存。要删除它，请参考8.14.3节“在Buildroot中使用ccache”。

可以使用一些变量来调整输出:

VARS will limit the listing to variables which names match the specified make-patterns - this must be set else nothing is printed // 将列表限制为名称与指定make-patterns匹配的变量—这必须设置，否则不打印任何内容 QUOTED_VARS, if set to YES, will single-quote the value // 如果设置为YES，将单引号引用该值 RAW_VARS, if set to YES, will print the unexpanded value // 如果设置为YES，将打印未展开的值

带引号的变量的输出可以在shell脚本中重用，例如:

当通过make menuconfig、make xconfig或其他配置工具改变系统配置时，Buildroot不会试图检测应该重新构建系统的哪些部分。在某些情况下，Buildroot应该重建整个系统，在某些情况下，只重建软件包的特定子集。但是以一种完全可靠的方式检测它是非常困难的，因此Buildroot开发人员决定不尝试这样做。

相反，用户有责任知道什么时候需要进行完全重新构建。作为提示，这里有一些经验法则可以帮助你理解如何使用Buildroot:

一般来说，当您面临构建错误并且不确定所做的配置更改的潜在后果时，请执行完整的重新构建。如果您得到相同的构建错误，那么您可以肯定这个错误与包的部分重构无关，如果这个错误发生在来自官方Buildroot的包上，请不要犹豫报告这个问题!随着您使用Buildroot的经验的积累，您将逐步了解什么时候真正需要一个完整的重建，您将节省越来越多的时间。

作为参考，完全重建可以通过运行:

Buildroot用户最常问的问题之一是如何重新构建给定的包，或者如何在不重新构建所有内容的情况下删除包。

如果不从头重新构建，Buildroot不支持删除包。这是因为Buildroot没有跟踪哪个包在output/staging目录和output/target目录中安装了什么文件，或者哪个包会根据另一个包的可用性进行不同的编译。

从头重新构建单个包的最简单方法是删除output/build中的构建目录。然后，Buildroot将重新提取、重新配置、重新编译和重新安装这个包。你可以通过make -dirclean命令要求buildroot这样做。

另一方面，如果只希望从编译步骤重新启动包的构建过程，可以运行make -rebuild。它将重新启动包的编译和安装，但不是从头开始:它基本上会在包内重新执行make和make install，因此它只会重新构建更改过的文件。

如果您想从配置步骤重新启动包的构建过程，可以运行make -reconfigure。它将重新启动包的配置、编译和安装。

虽然-rebuild意味着-reinstall，-reconfigure意味着-rebuild，但是这些目标以及只对上述起作用，并且不会触发重新创建根文件系统映像。如果需要重新创建根文件系统，还应该运行make或make all。

在内部，Buildroot创建所谓的戳文件(stamp files)，以跟踪每个包的哪些构建步骤已经完成。它们存储在包构建目录output/build/-/中，命名为.stamp_。上面详细介绍的命令只是操作这些戳文件，以强制Buildroot重新启动包构建过程的一组特定步骤。

关于包装特殊制造目标的进一步细节在8.14.5节“特定于包装的制造目标”中解释。

如果你打算进行离线构建，并且只是想下载你之前在配置器(menuconfig, nconfig, xconfig或gconfig)中选择的所有源代码，那么发出:

现在可以断开dl目录的内容或将其复制到构建主机中。

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

Buildroot还支持用类似于Linux内核的语法从树外构建。要使用它，请在make命令行中添加O=:

or

所有输出文件将位于/tmp/build目录下。如果O路径不存在，Buildroot将创建它。

注意:O路径可以是绝对路径，也可以是相对路径，但如果它作为相对路径传递，需要注意的是，它是相对于Buildroot主源目录解释的，而不是当前工作目录。

当使用树外构建时，Buildroot .config和临时文件也存储在输出目录中。这意味着您可以使用相同的源代码树安全地并行运行多个构建，只要它们使用唯一的输出目录。

为了便于使用，Buildroot在输出目录中生成了一个Makefile包装器-所以在第一次运行之后，你不再需要传递O= and-C ，只需运行(在输出目录中):

Buildroot也遵循一些环境变量，当它们被传递到环境中make或set时:

下面是一个使用顶层目录和$HOME中的配置文件的例子:

如果您想使用默认的gcc或g++以外的编译器在您的主机上构建辅助二进制文件，那么就这样做：

文件系统映像可以变得相当大，这取决于你选择的文件系统、包的数量，以及你是否提供了空闲空间……然而，文件系统映像中的一些位置可能只是空的(例如，长期运行的0);这样的文件称为稀疏文件。

大多数工具都可以有效地处理稀疏文件，并且只存储或编写稀疏文件中非空的那些部分。

例如:

其他工具可能有类似的选项。请参阅他们各自的手册页。

如果您需要存储文件系统映像(例如，从一台机器传输到另一台机器)，或者需要发送它们(例如，发送到Q&A团队)，那么您可以使用稀疏文件。

但是请注意，当使用dd的稀疏模式时，将文件系统映像烧录到设备上可能会导致文件系统损坏(例如，ext2文件系统的块位图可能损坏;或者，如果您的文件系统中有稀疏文件，那么这些部分在回读时可能不是全零)。您应该只在构建机器上处理文件时使用稀疏文件，而不是将它们传输到目标上使用的实际设备时。

Buildroot可以生成一个JSON简介，描述当前配置中启用的包集，以及它们的依赖项、许可和其他元数据。这个JSON简介是通过使用show-info make目标产生的:

Buildroot还可以使用pkg-stats make 目标生成关于包的HTML和JSON输出的详细信息。除了其他内容外，这些细节包括已知的cve(安全漏洞)是否会影响当前配置中的包。它还显示了这些包是否有更新的上游版本。

Buildroot的工作之一是了解包之间的依赖关系，并确保它们以正确的顺序构建。这些依赖有时非常复杂，对于一个给定的系统，通常不容易理解为什么Buildroot将这样或那样的包引入构建中。

为了帮助理解依赖关系，从而更好地理解不同组件在嵌入式Linux系统中的角色，Buildroot能够生成依赖关系图。

要生成你所编译的整个系统的依赖关系图，只需运行:

您将在output/graphs/graph-dependencies.pdf中找到生成的图形。

如果您的系统相当大，依赖关系图可能过于复杂和难以阅读。因此，为给定的包生成依赖关系图是可能的:

您将在output/graph/-graph-depends.pdf中找到生成的图形。

请注意，依赖关系图是使用Graphviz项目中的点工具生成的，要使用此特性，必须在系统上安装该工具。在大多数发行版中，它可以作为graphviz包使用。

默认情况下，依赖关系图是以PDF格式生成的。但是，通过传递BR2_GRAPH_OUT环境变量，您可以切换到其他输出格式，如PNG、PostScript或SVG。支持点工具的-T选项所支持的所有格式。

可以通过在BR2_GRAPH_DEPS_OPTS环境变量中设置选项来控制依赖于图形的行为。接受的选项有:

当构建一个系统需要很长时间时，有时能够了解哪些包的构建时间最长，看看是否可以做些什么来加快构建速度是很有用的。为了帮助这样的构建时间分析，Buildroot收集每个包的每个步骤的构建时间，并允许从这些数据生成图表。

要在构建后生成构建时间图，运行:

将会生成一系列文件在 output/graphs 中:

这个图形构建目标需要安装Python Matplotlib和Numpy库(大多数发行版上是Python-Matplotlib和Python-Numpy)，如果使用的是2.7以上的Python版本(大多数发行版上是Python-argparse)，还需要安装argparse模块。

默认情况下，图形的输出格式是PDF，但是可以使用BR2_GRAPH_OUT环境变量选择另一种格式。唯一支持的其他格式是PNG:

当目标系统增长时，有时了解每个Buildroot包对总体根文件系统大小的贡献是有用的。为了帮助进行这样的分析，Buildroot收集了关于每个包安装的文件的数据，并使用这些数据生成一个图表和CSV文件，详细说明不同包的大小贡献。

要在构建后生成这些数据，运行:

将会生成：

这个图形大小的目标需要安装Python Matplotlib库(大多数发行版上是Python - Matplotlib)，如果使用的是2.7以上的Python版本(大多数发行版上是Python -argparse)，还需要安装argparse模块。

与持续时间图一样，也支持BR2_GRAPH_OUT环境变量来调整输出文件格式。关于这个环境变量的详细信息，请参见8.9节“绘制包之间的依赖关系”。

此外，还可以设置环境变量BR2_GRAPH_SIZE_OPTS来进一步控制生成的图。接受的选项是:

Note. The collected filesystem size data is only meaningful after a complete clean rebuild. Be sure to run make clean all before using make graph-size.

To compare the root filesystem size of two different Buildroot compilations, for example after adjusting the configuration or when switching to another Buildroot release, use the size-stats-compare script. It takes two file-size-stats.csv files (produced by make graph-size) as input. Refer to the help text of this script for more details:

请注意。收集到的文件系统大小数据只有在完成干净重建后才有意义。确保在使用make graph-size之前运行make clean all。

要比较两个不同Buildroot编译的根文件系统大小，例如在调整配置后或切换到另一个Buildroot版本时，可以使用size-stats-compare脚本。它以两个file-size-stats.csv文件(由make graph-size生成)作为输入。有关更多细节，请参阅此脚本的帮助文本:

请注意。本节讨论一个非常实验性的特性，它在一些普通的情况下可以实现收支平衡。使用风险自负。

Buildroot一直能够在每个包的基础上使用并行构建:每个包都是由Buildroot使用make -jN(或者对非基于make的构建系统的等价调用)构建的。并行级别的默认值是cpu数量+ 1，但是可以使用BR2_JLEVEL配置选项进行调整。

然而，直到2020.02年，Buildroot还在以串行方式构建包:每个包一个接一个地构建，而没有在包之间并行构建。到2020.02年，Buildroot已经对顶级并行构建提供了实验性的支持，通过并行构建没有依赖关系的包，可以大大节省构建时间。然而，这一特性被标记为实验性的，并且已知在某些情况下不起作用。

为了使用顶层并行构建，必须:

在内部，BR2_PER_PACKAGE_DIRECTORIES将启用一种名为每个包目录的机制，它将产生以下效果:

一部分嵌入式Linux开发人员喜欢经典的文本编辑器(如Vim或Emacs)和基于命令行的界面，而其他一些嵌入式Linux开发人员喜欢更丰富的图形界面来完成他们的开发工作。Eclipse是最流行的集成开发环境之一，Buildroot与Eclipse集成是为了简化Eclipse用户的开发工作。

我们与Eclipse的集成简化了构建在Buildroot系统之上的应用程序和库的编译、远程执行和远程调试。它没有将Buildroot配置和构建过程本身与Eclipse集成在一起。因此，Eclipse集成的典型使用模型是:

在https://github.com/mbats/eclipse-buildroot-bundle/wiki上详细描述了Buildroot Eclipse集成的安装过程和使用方法。

您可能希望针对您的目标编译您自己的程序或其他没有打包在Buildroot中的软件。为了做到这一点，您可以使用Buildroot生成的工具链。

Buildroot生成的工具链默认位于output/host/。使用它最简单的方法是将output/host/bin/添加到PATH环境变量中，然后使用ARCH-linux-gcc, ARCH-linux-objdump, ARCH-linux-ld等。

另外，Buildroot也可以通过执行make SDK命令，导出所有选定包的工具链和开发文件，作为SDK。这将生成主机目录output/host/内容的tar文件，名为_sdk-buildroot.tar.gz(可以通过设置环境变量BR2_SDK_PREFIX来覆盖)，该文件位于输出目录output/images/中。

然后，当应用程序开发人员希望开发尚未打包为Buildroot包的应用程序时，可以将这个tarball分发给他们。

在提取SDK压缩包后，用户必须运行脚本relocate-sdk.sh(位于SDK的顶部目录)，以确保所有路径都使用新位置更新。

或者，如果你只是想准备SDK而不生成tarball(例如，因为你将只是移动主机目录，或将生成tarball自己)，Buildroot也允许你只准备SDK与make prepare-sdk，而不实际生成tarball。

为了方便起见，通过选择BR2_PACKAGE_HOST_ENVIRONMENT_SETUP选项，可以将environment-setup脚本安装到output/host/中，从而安装到SDK中。此脚本可以使用。你的/sdk/path/environment-setup导出一些环境变量，这些变量将帮助你使用Buildroot sdk交叉编译你的项目:PATH将包含SDK二进制文件，标准的autotools变量将用适当的值定义，CONFIGURE_FLAGS将包含基本的。./configure选项来交叉编译autotools项目。它还提供了一些有用的命令。但是请注意，一旦该脚本来源于此脚本，环境就只设置为交叉编译，而不再设置为本机编译。

Buildroot允许进行交叉调试，调试器在构建机器上运行，并与目标上的gdbserver通信，以控制程序的执行。

为实现这一目标:

现在，为了开始调试一个叫做foo的程序，你应该在目标上运行:

这将导致gdbserver在TCP端口2345上监听来自交叉gdb的连接。

然后，在主机上，您应该使用以下命令行启动交叉gdb:

当然，foo必须在当前目录中可用，使用调试符号构建。通常，您从构建foo的目录启动此命令(而不是从output/target/，因为该目录中的二进制文件被剥离)。

/output/staging/usr/share/buildroot/gdbinit文件将告诉交叉gdb在哪里可以找到目标库。

最后，从交叉gdb连接到目标:

Ccache是一个编译器缓存。它存储每个编译过程产生的目标文件，并且能够通过使用预先存在的目标文件跳过将来对同一源文件(使用相同的编译器和相同的参数)的编译。当多次从头进行几乎相同的构建时，它可以很好地加快构建过程。

ccache支持集成在Buildroot中。你只需要在Build选项中启用编译器缓存。这将自动构建ccache，并在每个主机和目标编译中使用它。

缓存位于$HOME/.buildrooot-ccache中。它存储在Buildroot输出目录之外，以便可以由单独的Buildroot构建共享。如果您想删除缓存，只需删除此目录。

您可以通过运行make ccache-stats获取缓存的统计信息(大小、命中次数、未命中次数等)。

make目标ccache-options和CCACHE_OPTIONS变量提供了对缓存的更多的访问。例如

Ccache对源文件和编译器选项进行hash。如果编译器选项不同，缓存的目标文件将不会被使用。然而，许多编译器选项包含到暂存目录的绝对路径。因此，在不同的输出目录中构建会导致许多缓存丢失。

为了避免这个问题，buildroot有使用相对路径选项(BR2_CCACHE_USE_BASEDIR)。这将把指向输出目录内的所有绝对路径重写为相对路径。因此，更改输出目录不再会导致缓存丢失。

相对路径的一个缺点是，它们最终也是对象文件中的相对路径。因此，例如，调试器将不再找到该文件，除非您首先cd到输出目录。

有关这种重写绝对路径的详细信息，请参阅ccache手册的Compiling in different directories一节。

Buildroot下载的各种tarball都存储在BR2_DL_DIR中，默认情况下该目录是dl目录。如果您想保留一个完整的Buildroot版本(已知它使用了相关的tarball)，您可以对此目录创建一个副本。这将允许您用完全相同的版本重新生成工具链和目标文件系统。

如果您维护多个Buildroot树，那么最好使用一个共享的下载位置。这可以通过将BR2_DL_DIR环境变量指向一个目录来实现。如果设置了此值，则会覆盖Buildroot配置中的BR2_DL_DIR的值。以下一行应该添加到。

还可以在.config文件中使用BR2_DL_DIR选项设置下载位置。与.config文件中的大多数选项不同，这个值被BR2_DL_DIR环境变量覆盖。

运行make 会构建并安装那个特定的包及其依赖项。

对于依赖于Buildroot框架的包，有许多特殊的make目标可以像这样独立调用:

包构建目标有(按照执行的顺序):

此外，还有其他一些有用的make目标:

Buildroot的正常操作是下载一个tarball，提取它，配置，编译和安装在这个tarball中找到的软件组件。源代码在output/build/-中提取，这是一个临时目录:每当使用make clean时，这个目录将被完全删除，并在下一次调用make时重新创建。即使使用Git或Subversion存储库作为包源代码的输入，Buildroot也会从中创建一个tarball，然后像往常一样使用tarball。

当Buildroot主要用作集成工具来构建和集成嵌入式Linux系统的所有组件时，这种行为非常适合。然而，如果一个人在开发系统的某些组件时使用Buildroot，这种行为就不是很方便了:相反，人们会希望对一个包的源代码做一个小的更改，并能够用Buildroot快速地重建系统。

直接在output/build/-中进行更改不是合适的解决方案，因为make clean时会删除此目录。

因此，Buildroot为这个用例提供了一个特定的机制:_OVERRIDE_SRCDIR机制。Buildroot读取覆盖文件，该文件允许用户告诉Buildroot某些包的源代码位置。

覆盖文件的默认位置是$(CONFIG_DIR)/local.mk。由BR2_PACKAGE_OVERRIDE_FILE配置选项定义。$(CONFIG_DIR)是Buildroot .config文件的位置，所以是本地的。local.mk默认与.config文件并排存在，这意味着:

如果需要不同于这些默认值的位置，可以通过BR2_PACKAGE_OVERRIDE_FILE配置选项指定。

在这个覆盖文件中，Buildroot期望找到表单中的行:

例如:

当Buildroot发现对于给定的包，已经定义了_OVERRIDE_SRCDIR，它将不再尝试下载、解压缩和打补丁。相反，它将直接使用指定目录中可用的源代码，而make clean将不触及此目录。这允许将Buildroot指向您自己的目录，该目录可以由Git、Subversion或任何其他版本控制系统管理。为了实现这一点，Buildroot将使用rsync将组件的源代码从指定的_OVERRIDE_SRCDIR复制到output/build/-custom/。

此机制最好与make -rebuild和make -reconfigure目标一起使用。make -rebuild all序列将把源代码从_OVERRIDE_SRCDIR rsync到output/build/-custom(多亏了rsync，只有修改后的文件被复制)，并重新启动这个包的构建过程。

在上面的linux包的例子中，开发者可以在/home/bob/linux中修改源代码，然后运行:

并在几秒钟内在output/images中获得更新后的Linux内核映像。类似地，可以在/home/bob/busybox和后面对BusyBox源代码进行更改:

output/images中的根文件系统映像包含更新后的BusyBox。

大型项目的源代码树通常包含数百或数千个不需要构建的文件，但会减慢用rsync复制源代码的过程。还可以定义_OVERRIDE_SRCDIR_RSYNC_EXCLUSIONS来跳过源树中某些文件的同步。例如，当处理webkitgtk包时，以下内容将从本地WebKit源代码树中排除测试和树内构建:

默认情况下，Buildroot会跳过VCS工件的同步(例如，.git和.svn目录)。有些包希望在构建过程中使用这些VCS目录，例如自动确定版本信息的精确提交引用。要以较慢的速度撤销此内置过滤，请将以下目录添加回:

对于一个特定的项目，你可能需要执行的典型行动是:

关于此类project-specific的自定义的重要说明:请仔细考虑哪些更改确实是特定于项目的，哪些更改对项目之外的开发人员也是有用的。Buildroot社区强烈推荐并鼓励对官方Buildroot项目的改进、包和板的支持。当然，有时上游是不可能或不可取的，因为变更是高度特定或专有的。

本章描述了如何在Buildroot中进行此类特定于项目的定制，以及如何以一种可以以可重复的方式构建相同映像的方式存储它们，甚至在运行make clean之后。通过遵循推荐的策略，您甚至可以使用相同的Buildroot树来构建多个不同的项目!

在为项目定制Buildroot时，您将创建一个或多个特定于项目的文件，这些文件需要存储在某个地方。虽然大多数这些文件可以放在任何位置，因为它们的路径将在Buildroot配置中指定，但Buildroot开发人员推荐了一个特定的目录结构，这将在本节中描述。

与这个目录结构正交的是，您可以选择将这个结构本身放在哪里:要么放在Buildroot树中，要么使用br2-external tree放在它的外部。这两个选项都是有效的，选择取决于您。

上述文件的细节将在本章中进一步给出。

注意:如果您选择将这个结构放在Buildroot树的外部，但放在br2-external树中，那么和组件可能是多余的，可以被删除。

对于一个用户来说，有几个相关的项目部分需要相同的自定义，这是很常见的。与其为每个项目重复这些定制，不如使用分层定制方法，如本节所述。

Buildroot中几乎所有可用的定制方法，比如构建后脚本post-build scripts和根文件系统root filesystem overlays覆盖，都接受空格分隔的项列表。指定的项总是按从左到右的顺序处理。通过创建多个这样的项，一个用于公共定制，另一个用于真正的特定于项目的定制，您可以避免不必要的重复。每一层通常都包含在board//内部的一个单独目录中。根据项目的不同，您甚至可以引入两个以上的层。

一个用户有两个自定义层common和fooboard的目录结构示例是:

例如，如果用户将BR2_GLOBAL_PATCH_DIR配置选项设置为:

然后首先应用普通层的补丁，然后应用底层的补丁。

正如9.1节“推荐的目录结构”中已经简要提到的，您可以将特定于项目的自定义放置在两个位置:

通过将BR2_EXTERNAL make变量设置为要使用的br2-external树的路径，可以告诉Buildroot使用一个或多个br2-external树。它可以传递给任何Buildroot make调用。它自动保存在输出目录中隐藏的.br2-external.mk的文件。因此，无需在每次make调用时传递BR2_EXTERNAL。但是，它可以在任何时候通过传递一个新值来更改，也可以通过传递一个空值来删除。

请注意。到br2-external树的路径可以是绝对路径，也可以是相对路径。如果它是作为相对路径传递的，那么一定要注意，它是相对于Buildroot主源目录而不是Buildroot输出目录来解释的。

注意:如果在Buildroot 2016.11之前使用br2-external树，你需要先转换它，然后才能在Buildroot 2016.11之后使用它。请参阅第27.1节，“迁移到2016年11月”，以获得相关帮助。

一些例子:

From now on, definitions from the /path/to/foo br2-external tree will be used:

We can switch to another br2-external tree at any time:

We can also use multiple br2-external trees:

Or disable the usage of any br2-external tree:

一个br2-external树必须包含至少这三个文件，在以下章节中描述:

除了这些强制文件之外，br2-external树中还可能存在其他可选内容，比如configs/或provides/目录。它们也将在下面的章节中进行描述。

后面还将描述一个完整的示例br2-external树布局。

The external.desc file

这个文件描述了 br2-external tree: the name and description for that br2-external tree.

该文件的格式是逐行的，每行以一个关键字开头，后面跟着一个冒号和一个或多个空格，然后是分配给该关键字的值。目前识别的关键字有两个:

name, mandatory, defines the name for that br2-external tree. That name must only use ASCII characters in the set [A-Za-z0-9_]; any other character is forbidden. Buildroot sets the variable BR2_EXTERNAL_$(NAME)_PATH to the absolute path of the br2-external tree, so that you can use it to refer to your br2-external tree. This variable is available both in Kconfig, so you can use it to source your Kconfig files (see below) and in the Makefile, so that you can use it to include other Makefiles (see below) or refer to other files (like data files) from your br2-external tree.

// Name(强制)定义了br2-external树的名称。该名称在集合[A-Za-z0-9_]中只能使用ASCII字符;禁止使用其他任何字符。Buildroot将变量BR2_EXTERNAL_$(NAME)_PATH设置为br2-external树的绝对路径，这样您就可以使用它来引用br2-external树。这个变量在Kconfig中可用，因此您可以使用它来生成Kconfig文件(见下文)和Makefile，这样您就可以使用它来包含其他Makefile(见下文)或引用br2-external树中的其他文件(如数据文件)。

Note: Since it is possible to use multiple br2-external trees at once, this name is used by Buildroot to generate variables for each of those trees. That name is used to identify your br2-external tree, so try to come up with a name that really describes your br2-external tree, in order for it to be relatively unique, so that it does not clash with another name from another br2-external tree, especially if you are planning on somehow sharing your br2-external tree with third parties or using br2-external trees from third parties. // 注意:因为可以一次使用多个br2-external树，所以这个名称被Buildroot用来为每个树生成变量。这个名字是用来识别你的br2-外部树的，所以试着想出一个真正描述你的br2-外部树的名字，为了让它相对独特，这样它就不会和另一个来自另一个br2-外部树的名字冲突，特别是当您计划以某种方式与第三方共享您的br2-external树或使用来自第三方的br2-external树时。

desc, optional, provides a short description for that br2-external tree. It shall fit on a single line, is mostly free-form (see below), and is used when displaying information about a br2-external tree (e.g. above the list of defconfig files, or as the prompt in the menuconfig); as such, it should relatively brief (40 chars is probably a good upper limit). The description is available in the BR2_EXTERNAL_$(NAME)_DESC variable.

// Desc(可选)提供了br2-external树的简短描述。它应该适合一行，大部分是自由形式的(见下文)，用于显示关于br2-external树的信息(例如，在defconfig文件列表上面，或作为menuconfig中的提示符);因此，它应该相对简短(40字符可能是一个很好的上限)。该描述可在BR2_EXTERNAL_$(NAME)_DESC变量中获得。

名称示例和相应的BR2_EXTERNAL_$(NAME)_PATH变量:

在下面的例子中，假定名称设置为BAR_42。

注意:BR2_EXTERNAL_$(NAME)_PATH和BR2_EXTERNAL_$(NAME)_DESC都在Kconfig文件和makefile中可用。它们也被导出到环境中，因此可以在构建后、生成映像后和伪造后脚本中使用。

The Config.in and external.mk files

这些文件(可能每个都是空的)可以用来定义包配方(例如foo/Config.in和foo/foo.mk就像Buildroot本身的包)。在和foo / foo。或者其他自定义配置选项或make逻辑。

构建根自动从每个br2-external树中包含Config.in使其显示在顶级配置菜单中，并包含external.mk从每个br2-external树和其余的makefile逻辑。

它的主要用途是存储package recipes。推荐的方法是编写一个Config.in像这样:

然后，有一个external.mk文件看起来像这样:

然后在$(BR2_EXTERNAL_BAR_42_PATH)/package/package1和$(BR2_EXTERNAL_BAR_42_PATH)/package/package2中创建普通的Buildroot包配方，如第18章，添加新包到Buildroot。如果您愿意，还可以将包分组到名为的子目录中，并相应地调整上述路径。

您还可以在Config.in定义自定义配置选项。在external.mk自定义make逻辑。

The configs/ directory

可以将Buildroot defconfigs存储在br2-external树的configs子目录中。Buildroot会自动在make list-defconfigs的输出中显示它们，并允许使用普通的make _defconfig命令加载它们。它们将在make list-defconfigs输出中可见，位于External configs标签下面，该标签包含定义它们的br2-external树的名称。

注意:如果一个defconfig文件存在于多个br2-external树中，那么将使用最后一个br2-external树中的那个。因此，可以覆盖Buildroot或另一个br2-external树中绑定的defconfig。

The provides/ directory

对于某些包，Buildroot提供了两个(或更多)api兼容包的实现。例如，可以选择libjpeg或jpeg-turbo;openssl和libressl之间有一个;有一个选择一个已知的，预先配置的工具链…

br2-external可以通过提供一组定义这些替代方案的文件来扩展这些选择:

Free-form content

可以将所有特定于板的配置文件存储在那里，比如内核配置、根文件系统覆盖层，或者任何其他Buildroot允许设置位置的配置文件(通过使用BR2_EXTERNAL_$(NAME)_PATH变量)。例如，你可以将路径设置为一个全局补丁目录，一个rootfs覆盖和内核配置文件，如下所示(例如，通过运行make menuconfig并填写这些选项):

Additional Linux kernel extensions

额外的Linux内核扩展(请参见18.21.2节，“Linux -kernel-extensions”)可以通过将它们存储在br2-external树的根Linux/目录中来添加。

Example layout

下面是一个使用br2-external所有特性的示例布局(示例内容显示在上面的文件中，当它与解释br2-external树相关时;当然，这完全是为了说明而编造的):

br2-external树将在menuconfig中可见(布局展开):

如果你使用了多个br2-external树，它看起来应该是这样的(布局展开，第二个名字为FOO_27，但在external.desc中没有desc:字段):

此外，jpeg提供程序将在jpeg选项中可见:

工具链也类似:

请注意。工具链选项toolchain/toolchain-external-mine/Config.in.options将不会出现在工具链菜单中。它们必须显式地包含在br2-external的顶级Config.in和将因此出现在External options菜单中。

可以使用make savedefconfig命令存储Buildroot配置。

这将通过删除默认值的配置选项来删除Buildroot配置。结果存储在一个名为defconfig的文件中。如果你想把它保存在另一个地方，请更改Buildroot配置本身的BR2_DEFCONFIG选项，或者使用make savedefconfig BR2_DEFCONFIG=调用make。

这个defconfig的推荐存储位置是configs/_defconfig。如果您遵循此建议，该配置将在make help中列出，并且可以通过运行make _defconfig再次设置。

或者，您可以将文件复制到任何其他地方，并使用make defconfig BR2_DEFCONFIG=重新构建。

BusyBox、Linux内核、Barebox、U-Boot和uClibc的配置文件如有更改，也应保存。对于每一个组件，都有一个Buildroot配置选项指向一个输入配置文件，例如BR2_LINUX_KERNEL_CUSTOM_CONFIG_FILE。要存储它们的配置，请将这些配置选项设置为您希望保存配置文件的路径，然后使用下面描述的帮助器目标来实际存储配置。

如9.1节“推荐的目录结构”所述，这些配置文件的推荐存储路径为board///foo.config。

确保在更改BR2_LINUX_KERNEL_CUSTOM_CONFIG_FILE等选项之前创建了一个配置文件。否则，Buildroot将尝试访问这个配置文件，它还不存在，并将失败。您可以通过运行make linux-menuconfig等来创建配置文件。

Buildroot提供了一些帮助器目标，以简化配置文件的保存。

除了通过make *config改变配置之外，还有一些其他的方法来定制最终的目标文件系统。

两种推荐的方法可以共存，即根文件系统覆盖root filesystem overlay和后构建脚本post build script。

Root filesystem overlays (BR2_ROOTFS_OVERLAY)

文件系统覆盖层是在构建目标文件系统之后直接复制的文件树。要启用此特性，请将配置选项BR2_ROOTFS_OVERLAY(在System configuration菜单中)设置为覆盖的根。您甚至可以指定多个以空格分隔的叠加。如果你指定一个相对路径，它将是相对于Buildroot树的根。版本控制系统的隐藏目录，如.git、.svn、.hg等，名为.empty的文件和以~结尾的文件都将被排除在副本之外。

当BR2_ROOTFS_MERGED_USR被启用时，覆盖层必须不包含/bin、/lib或/sbin目录，因为Buildroot将把它们创建为指向/usr中相关文件夹的符号链接。在这种情况下，如果覆盖层有任何程序或库，它们应该放在/usr/bin， /usr/sbin和/usr/lib.

如9.1节“推荐的目录结构”所示，此覆盖的推荐路径为board///rootfs-overlay。

Post-build scripts (BR2_ROOTFS_POST_BUILD_SCRIPT)

构建后脚本是在Buildroot构建所有选择的软件之后，但在组装rootfs映像之前调用的shell脚本。要启用此特性，请在配置选项BR2_ROOTFS_POST_BUILD_SCRIPT(在System configuration菜单中)中指定一个空格分隔的构建后脚本列表。如果你指定一个相对路径，它将是相对于Buildroot树的根。

使用构建后脚本，您可以删除或修改目标文件系统中的任何文件。但是，您应该小心地使用该特性。每当您发现某个包生成错误或不需要的文件时，您应该修复该包，而不是使用一些构建后清理脚本来处理它。

如9.1节“推荐的目录结构”所示，该脚本推荐的路径为board///post_build.sh。

构建后脚本将以主Buildroot树作为当前工作目录运行。目标文件系统的路径作为每个脚本的第一个参数传递。如果配置选项BR2_ROOTFS_POST_SCRIPT_ARGS不是空的，这些参数也将被传递到脚本。所有的脚本都将被传递完全相同的参数集，不可能给每个脚本传递不同的参数集。

此外，你也可以使用这些环境变量:

下面将介绍另外三种自定义目标文件系统的方法，但不推荐使用。

Direct modification of the target filesystem

对于临时修改，您可以直接修改目标文件系统并重新构建映像。目标文件系统在output/target/下可用。完成更改后，运行make重新构建目标文件系统映像。

这个方法允许您对目标文件系统做任何操作，但是如果您需要使用make clean来清除Buildroot树，那么这些更改将会丢失。这种清理在一些情况下是必要的，请参阅第8.2节“了解什么时候需要完全重新构建”以了解细节。因此，此解决方案只适用于快速测试:更改无法通过make clean命令保存。一旦您验证了您的更改，您应该确保它们将在make clean之后持久存在，使用根文件系统覆盖或构建后脚本。

Custom target skeleton (BR2_ROOTFS_SKELETON_CUSTOM)

根文件系统映像是从目标框架skeleton创建的，所有包都在目标框架之上安装它们的文件。在构建和安装任何包之前，将框架复制到目标目录output/target。默认的目标框架提供了标准的Unix文件系统布局和一些基本的初始化脚本和配置文件。

如果默认框架(在system/skeleton下可用)不符合您的需求，您通常会使用根文件系统覆盖或构建后脚本对其进行调整。但是，如果默认框架与您所需要的完全不同，那么使用自定义框架可能更合适。

要启用此功能，请启用配置选项BR2_ROOTFS_SKELETON_CUSTOM，并将BR2_ROOTFS_SKELETON_CUSTOM_PATH设置为自定义骨架的路径。这两个选项都可以在System configuration菜单中使用。如果你指定一个相对路径，它将是相对于Buildroot树的根。

自定义框架不需要包含/bin、/lib或/sbin目录，因为它们是在构建过程中自动创建的。当启用BR2_ROOTFS_MERGED_USR时，自定义框架必须不包含/bin、/lib或/sbin目录，因为Buildroot将把它们创建为指向/usr中相关文件夹的符号链接。在这种情况下，如果框架有任何程序或库，它们应该放在/usr/bin、/usr/sbin和/usr/lib.

不建议使用此方法，因为它复制了整个框架，这妨碍了利用在以后的Buildroot版本中对默认框架进行的修复或改进。

Post-fakeroot scripts (BR2_ROOTFS_POST_FAKEROOT_SCRIPT)

当聚合最终的映像时，这个过程的某些部分需要根权限:在/dev中创建设备节点，设置文件和目录的权限或所有权……这并不能完全替代实际的root，但已经足够满足Buildroot的需求了。

fakeroot后脚本是在fakeroot阶段结束时，即在调用文件系统映像生成器之前调用的shell脚本。因此，它们被称为在fakeroot上下文中。

当您需要调整文件系统以进行通常只对根用户可用的修改时，Post-fakeroot脚本可能非常有用。

注意:建议使用现有的机制来设置文件权限或在/dev中创建条目(见9.5.1节，“设置文件权限和所有权并添加自定义设备节点”)或创建用户(见9.6节，“添加自定义用户帐户”) 注意:后构建脚本(上面提到的)和fakeroot脚本之间的区别在于，后构建脚本不会在fakeroot上下文中被调用。 注意:使用fakeroot并不能完全替代实际的root。Fakeroot只会伪造文件访问权限和类型(常规，块或char设备…)和uid/gid;这些是在内存中模拟的。

有时需要在文件或设备节点上设置特定的权限或所有权。例如，某些文件可能需要root用户拥有。由于构建后脚本不是作为root运行的，因此您不能从那里进行此类更改，除非从构建后脚本中使用显式的fakeroot。

相反，Buildroot提供了对所谓权限表permission tables的支持。要使用此特性，请将配置选项BR2_ROOTFS_DEVICE_TABLE设置为以空格分隔的权限表列表，即遵循makedev语法的常规文本文件。

如果你正在使用一个静态设备表(即不使用devtmpfs, mdev，或(e)udev)，那么你可以使用相同的语法添加设备节点，在所谓的设备表device tables。要使用此特性，请将配置选项BR2_ROOTFS_STATIC_DEVICE_TABLE设置为用空格分隔的设备表列表。

如9.1节“推荐的目录结构”所示，这些文件的推荐位置是board///。

需要注意的是，如果特定的权限或设备节点与特定的应用程序相关，你应该在包的.mk文件中设置变量FOO_PERMISSIONS和FOO_DEVICES(参见18.5.2节，“通用包引用”)。

有时需要在目标系统中添加特定的用户。为了满足这一需求，Buildroot提供了对所谓用户表users tables的支持。要使用此特性，请将配置选项BR2_ROOTFS_USERS_TABLES设置为一个空格分隔的用户表列表，即遵循makeusers语法的常规文本文件。

如9.1节“推荐的目录结构”所示，这些文件的推荐位置是board///。

需要注意的是，如果自定义用户与特定的应用程序相关，你应该在包的.mk文件中设置变量FOO_USERS(参见18.5.2节，“通用包引用”)。

当构建后脚本post-build scripts(第9.5节，“自定义生成的目标文件系统”)在构建文件系统映像、内核和引导加载程序之前运行时，可以使用后映像脚本post-image scripts在创建所有映像之后执行一些特定的操作。

例如，可以使用后映像脚本post-image scripts在NFS服务器导出的位置中自动提取根文件系统tarball，或者创建一个将根文件系统和内核映像绑定在一起的特殊固件映像，或者您的项目所需的任何其他自定义操作。

要启用这个特性，在配置选项BR2_ROOTFS_POST_IMAGE_SCRIPT中指定一个空格分隔的后映像脚本列表(在System configuration菜单中)。如果你指定一个相对路径，它将是相对于Buildroot树的根。

就像编译后脚本一样，编译后图像脚本运行时将主要Buildroot树作为当前工作目录。图像输出目录的路径作为每个脚本的第一个参数传递。如果配置选项BR2_ROOTFS_POST_SCRIPT_ARGS不是空的，这些参数也将被传递到脚本。所有的脚本都将被传递完全相同的参数集，不可能给每个脚本传递不同的参数集。

同样，与构建后脚本一样，脚本可以访问环境变量BR2_CONFIG、HOST_DIR、STAGING_DIR、TARGET_DIR、BUILD_DIR、BINARIES_DIR、CONFIG_DIR和BASE_DIR。

后映像脚本将以执行Buildroot同样的用户的身份执行，该用户通常不应该是根用户。因此，这些脚本中任何需要root权限的操作都需要特殊处理(fakeroot或sudo的使用)，这就交给脚本开发人员了。

在Buildroot中提供的包的基础上应用额外的补丁有时是有用的。例如，这可能用于支持项目中的自定义特性，或者在处理新体系结构时。

BR2_GLOBAL_PATCH_DIR配置选项可用于指定一个空格分隔的包含包补丁的一个或多个目录列表。

对于特定包的特定版本，补丁从BR2_GLOBAL_PATCH_DIR应用，如下所示:

对于BR2_GLOBAL_PATCH_DIR中存在的每个目录 ，将确定，如下所示:

然后补丁将会从应用，如下所示:

有关如何为一个包应用补丁的信息，请参见第19.2节“如何应用补丁”。

BR2_GLOBAL_PATCH_DIR选项是为包指定自定义补丁目录的首选方法。它可以用于为buildroot中的任何包指定补丁目录。它也应该用来代替U-Boot和Barebox等软件包可用的自定义补丁目录选项。通过这样做，它将允许用户从一个顶级目录管理他们的补丁。 BR2_GLOBAL_PATCH_DIR作为指定自定义补丁的首选方法的例外情况是BR2_LINUX_KERNEL_PATCH。BR2_LINUX_KERNEL_PATCH应该用于指定在URL中可用的内核补丁。注意:BR2_LINUX_KERNEL_PATCH指定了在BR2_GLOBAL_PATCH_DIR中可用的补丁之后应用的内核补丁，因为它是从Linux包的补丁后钩子post-patch hook执行的。

一般来说，任何新包都应该直接添加到包目录中，并提交给Buildroot上游项目。在第18章“向Buildroot添加新包”中详细介绍了如何向Buildroot添加包，这里不再重复。但是，您的项目可能需要一些不能上行的专有包。本节将解释如何将这些特定于项目的包保存在特定于项目的目录中。

如9.1节“推荐的目录结构”所示，项目特定包的推荐位置是package//。如果你正在使用br2-external树特性(参见9.2节，“保持自定义在Buildroot之外”)，推荐的位置是将它们放在br2-external树的名为package/的子目录中。

但是，除非我们执行一些额外的步骤，否则Buildroot不会知道这个位置中的包。正如第18章“向Buildroot添加新包”中所解释的，Buildroot中的包基本上由两个文件组成:一个.mk文件(描述如何构建包)和一个Config.in文件(描述此包的配置选项)。

Buildroot会自动将.mk文件包含在package目录的一级子目录中(使用模式package/*/*.mk)。如果我们想让Buildroot包含更深层次的子目录(比如package//package1)中的.mk文件，那么我们只需在包含这些额外的.mk文件的第一级子目录中添加一个.mk文件。因此，创建一个文件package//.mk以下内容(假设你在package//下面只有一个额外的目录级别):

For the Config.in files, create a file package//Config.in that includes the Config.in files of all your packages. An exhaustive list has to be provided since wildcards are not supported in the source command of kconfig. For example:

对于Config.in文件，创建一个文件package//Config.in其中包括你所有软件包的文件里Config.in。必须提供详尽的列表，因为在kconfig的源命令中不支持通配符。例如:

包括这个新的文件package//Config.in从package/Config.in。最好是在特定于公司的菜单中，以便与未来的Buildroot版本更容易合并。

如果使用br2-external树，请参考9.2节“保持自定义在Buildroot之外”，了解如何填写这些文件。

在本章的前面，已经描述了用于进行特定于项目的定制的不同方法。本节将通过提供存储特定于项目的自定义的逐步说明来总结所有这些内容。显然，可以跳过与项目无关的步骤。

SELinux是一个执行访问控制策略的Linux内核安全模块。除了传统的文件权限和访问控制列表之外，SELinux还允许为用户或进程编写访问资源(文件、套接字……)的特定功能的规则。

SELinux有三种操作模式:

在Buildroot中，操作模式由BR2_PACKAGE_REFPOLICY_POLICY_STATE_*配置选项控制。Linux内核还有各种配置选项，这些选项会影响如何启用SELinux(请参阅Linux内核源代码中的security/ ELinux/Kconfig)。

默认情况下，在Buildroot中，SELinux策略是由上游refpolicy项目提供的，由BR2_PACKAGE_REFPOLICY启用。

要在Buildroot生成的系统中正确支持SELinux，必须启用以下配置选项:

此外，文件系统映像格式必须支持扩展属性。

SELinux repolicy包含可以在构建时启用或禁用的模块。每个模块都提供了许多SELinux规则。在Buildroot中，默认情况下非基本模块是禁用的，提供了几种启用这些模块的方法:

Buildroot还允许完全覆盖repolicy。这允许提供专门为给定系统设计的完整自定义策略。当采用这种方式时，上述所有机制都将被禁用:没有额外的SElinux模块添加到策略中，并且自定义策略中的所有可用模块都将被启用并构建到最终的二进制策略中。自定义策略必须是官方重新策略的一个分支。

为了完全覆盖repolicy，必须设置以下配置变量:

引导进程以下消息以后似乎挂起(消息不一定完全相似，取决于所选包的列表):

这意味着系统正在运行，但没有在串行控制台上启动shell。为了让系统在您的串行控制台上启动一个shell，您必须进入Buildroot配置，在System configuration,中，修改Run a getty (login prompt) after boot，并在getty options子菜单中设置适当的端口和波特率。这将自动调整生成的系统的/etc/inittab文件，以便shell在正确的串口上启动。

已经决定从Buildroot-2012.11版本开始停止对目标板原生编译器的支持，因为:

如果你的目标上需要一个编译器，那么Buildroot不适合你的目的。在这种情况下，你需要一个真正的发行版，你应该选择如下内容:

因为目标上没有可用的编译器(参见11.2节，“为什么目标上没有编译器?”)，所以在头文件或静态库上浪费空间是没有意义的。

因此，自Buildroot-2012.11发布以来，这些文件总是从目标中删除。

因为Buildroot主要针对有限资源(CPU、ram、大容量存储)的小型或非常小的目标硬件，所以用文档数据浪费空间是没有意义的。

如果您无论如何都需要目标上的文档数据，那么Buildroot并不适合您的目的，您应该寻找一个真正的发行版(参见11.2节，“为什么目标上没有编译器?”)。

如果一个包存在于Buildroot树中，并且没有出现在配置菜单中，这很可能意味着该包的某些依赖项没有满足。

要了解更多关于包的依赖关系，可以在配置菜单中搜索包的符号(见8.1节“make tips”)。

然后，您可能必须递归地启用几个选项(对应于未满足的依赖项)，以便最终能够选择包。

如果包因为一些未满足的工具链选项而不可见，那么您当然应该运行一个完整的重新构建(参见8.1节“make tips”以获得更多解释)。

有很多理由不使用目标目录chroot，其中:

由于这些原因，使用目标目录作为新的根，通过chroot运行的命令很可能会失败。

如果您想在chroot中运行目标文件系统，或者作为NFS根运行，那么使用images/中生成的tarball映像并将其作为根解压。

在Buildroot列表中经常讨论的一个特性是“包管理”package management的一般主题。总的来说，这个想法是添加一些跟踪哪个Buildroot包安装了什么文件，目的是:

通常，大多数人认为这很容易做到:只需跟踪哪个软件包安装了什么，并在软件包未被选中时删除它。然而，实际情况要复杂得多:

由于所有这些原因，结论是，当包未被选中时，添加已安装文件的跟踪来删除它们，或者生成二进制包的存储库，是非常难以可靠地实现的，并且会增加很多复杂性。

在这个问题上，Buildroot开发者发表了如下立场声明:

由于Buildroot经常涉及到对整个系统进行完整的重建，这可能会很长，所以我们提供以下一些技巧来帮助减少构建时间:

Buildroot的所有最终产品(工具链、根文件系统、内核、引导加载器)都包含开源软件，在各种许可下发布。

使用开源软件使您可以自由地构建丰富的嵌入式系统，可以从各种各样的包中进行选择，但也强加了一些您必须知道和遵守的义务。有些许可证要求您在产品文档中发布许可证文本。另一些则要求您将软件的源代码重新分发给接收您产品的人。

每个许可的确切要求都记录在每个包中，遵守这些要求是您的责任(或您的法律办公室的责任)。为了让你更容易做到这一点，Buildroot可以为你收集一些你可能需要的材料。要生成这个材料，在你用make menuconfig、make xconfig或make gconfig配置了Buildroot之后，运行:

Buildroot将在legal-info/子目录下的输出目录中收集与法律相关的材料。在那里你会发现:

请注意，Buildroot的法律信息特性的目的是生成所有与软件包许可的法律遵从有关的材料。Buildroot并没有试图生产出你必须以某种方式公开的确切材料。当然，生产的材料比严格遵守法律所需要的要多。例如，它为在类似bsd的许可下发布的包生成源代码，您不需要以源代码的形式重新发布这些包。

此外，由于技术限制，Buildroot不能生成您将要或可能需要的一些材料，例如一些外部工具链的工具链源代码和Buildroot源代码本身。当您运行make legal-info时，Buildroot会在README文件中产生警告，通知您无法保存的相关材料。

最后，请记住，make legal-info的输出基于每个包recipes中的声明性语句。Buildroot开发人员尽其所能保持那些声明性语句尽可能准确，就他们所知。然而，很可能这些陈述性的陈述并不都完全准确或详尽无遗。您(或您的法律部门)在使用make legal-info作为您自己的合规交付之前，必须检查其输出。参见Buildroot发行版根目录的copy文件中的NO WARRANTY条款(第11和12条)。

Buildroot本身是一个开源软件，根据GNU通用公共许可证(General Public License)版本2或(由您选择)任何更新版本发布，除了下面详细介绍的包补丁。然而，作为一个构建系统，它通常不是最终产品的一部分:如果您为一个设备开发根文件系统、内核、引导加载程序或工具链，那么Buildroot的代码只出现在开发机器上，而不是在设备存储中。

然而，Buildroot开发人员的普遍看法是，当发布包含gpl许可软件的产品时，应该将Buildroot源代码与其他包的源代码一起发布。这是因为GNU GPL将可执行作品的“完整源代码”定义为“它包含的所有模块的所有源代码，加上任何关联的接口定义文件，加上用来控制可执行作品的编译和安装的脚本”。Buildroot是用于控制可执行文件的编译和安装的脚本的一部分，因此它被认为是必须重新分发的材料的一部分。

请记住，这只是Buildroot开发人员的意见，如果您有任何疑问，应该咨询您的法律部门或律师。

Buildroot还捆绑补丁文件，应用于各种包的源代码。这些补丁不在Buildroot的许可范围内。相反，它们是由应用补丁的软件的许可证所覆盖的。当上述软件在多个许可下可用时，Buildroot补丁只在公共可访问的许可下提供。

技术细节请参见第19章补丁包。

要实现nfs引导，请在filesystem映像菜单中启用tar根文件系统。

完成构建后，只需运行以下命令设置nfs根目录:

请记住将此路径添加到/etc/exports.

然后，可以从目标执行nfs引导。

要构建一个实时CD映像，请启用文件系统映像菜单中的iso映像选项。注意，这个选项只适用于x86和x86-64体系结构，如果您正在使用Buildroot构建内核的话。

您可以使用IsoLinux、Grub或Grub 2作为引导加载程序构建一个活动CD映像，但只有IsoLinux支持使该映像同时作为活动CD和活动USB使用(通过构建混合映像选项)。

You can test your live CD image using QEMU:

Or use it as a hard-drive image if it is a hybrid ISO:

It can be easily flashed to a USB drive with dd:

如果你想在生成的映像中使用chroot，那么有几件事你应该注意:

正如上面提到的，Buildroot基本上是一组makefile文件，它们使用正确的选项下载、配置和编译软件。它还包括各种软件包的补丁——主要是交叉编译工具链(gcc、binutils和uClibc)中涉及的补丁。

基本上每个软件包都有一个Makefile，它们以.mk扩展名命名。makefile被分成许多不同的部分：

每个目录至少包含2个文件:

主Makefile执行以下步骤(一旦配置完成):

总之，这些编码风格规则可以帮助您在Buildroot中添加新文件或重构现有文件。

如果你稍微修改一些现有的文件，重要的是保持整个文件的一致性，这样你就可以:

Config.in文件包含Buildroot几乎所有可配置的条目。

一个条目具有以下模式:

Do not align the = signs. // 不要将=号对齐。

请注意，定义块中的commands应该总是以tab开始，这样make将它们识别为命令。

Optional dependency: // 选项依赖:

YES:

NO:

Optional hooks: keep hook definition and assignment together in one if block.

// 可选钩子:将钩子定义和赋值放在一个if块中。

YES:

NO:

The documentation uses the asciidoc format.

For further details about the asciidoc syntax, refer to http://www.methods.co.nz/asciidoc/userguide.html.

Some scripts in the support/ and utils/ directories are written in Python and should follow the PEP8 Style Guide for Python Code.

Buildroot包含几个公开可用硬件板的基本配置，这样这样一个板的用户就可以轻松地构建一个已知可以工作的系统。你也可以在Buildroot中添加对其他板的支持。

为此，您需要创建一个普通的Buildroot配置，它为硬件构建一个基本的系统:(内部)工具链、内核、引导加载程序、文件系统和一个简单的BusyBox-only用户空间。不应该选择特定的包:配置应该尽可能少，并且应该只为目标平台构建一个可工作的基本BusyBox系统。当然，您可以为您的内部项目使用更复杂的配置，但是Buildroot项目将只集成基本的板配置。这是因为包选择是高度特定于应用程序的。

一旦您有了一个已知的工作配置，运行make savedefconfig。这将在Buildroot源树的根生成一个最小的defconfig文件。将此文件移到configs/目录中，并将其重命名为_defconfig。如果配置有点复杂，最好手动重新格式化并将其划分为多个部分，每个部分之前都有注释。典型的部分是架构、工具链选项(通常只是linux头文件版本)、固件、引导装载程序、内核和文件系统。

对于不同的组件，总是使用固定版本或提交散列，而不是“最新”版本。例如，将BR2_LINUX_KERNEL_CUSTOM_VERSION=y和BR2_LINUX_KERNEL_CUSTOM_VERSION_VALUE设置为您测试的内核版本。

建议尽可能多地使用Linux内核和引导加载程序的上游版本，并尽可能多地使用默认的内核和引导加载程序配置。如果它们对您的板不正确，或没有默认存在，我们鼓励您发送修复到相应的上游项目。

然而，与此同时，您可能希望存储特定于目标平台的内核或引导加载程序配置或补丁。为此，创建一个board/和子目录board//。然后，您可以将补丁和配置存储在这些目录中，并从主要的Buildroot配置中引用它们。有关更多细节，请参阅第9章，特定于项目的定制。

本节介绍如何将新的包(用户空间库或应用程序)集成到Buildroot中。它还展示了如何集成现有的包，这是修复问题或调优其配置所需要的。

当您添加一个新的包时，请确保在各种条件下对它进行测试(参见第18.24.3节，“如何测试您的包”)，并检查它的编码风格(参见第18.24.2节，“如何检查编码风格”)。

首先，在软件package目录下为您的软件创建一个目录，例如libfoo。

有些包按主题分组在子目录中:x11r7、qt5和gstreamer。如果您的包符合其中一个类别，那么在这些类别中创建您的包目录。但是，不建议创建新的子目录。

对于要在配置工具中显示的包，您需要在您的包目录中创建一个Config文件。有两种类型:Config.in and Config.in.host。

对于在目标上使用的包，创建一个名为Config.in的文件。这个文件将包含与我们的libfoo软件相关的选项描述，这些选项将在配置工具中使用和显示。它基本上应该包含:

关于配置选项的bool行、help行和其他元数据信息必须用一个tab缩进。帮助文本本身应该缩进一个制表符和两个空格，行应该换行以适应72列，其中制表符计数为8，所以文本本身的62个字符。帮助文本必须在空行之后提到项目的上游URL。

作为特定于Buildroot的约定，属性的顺序如下:

您可以将其他子选项添加到if BR2_PACKAGE_LIBFOO…endif语句中，以配置软件中的特定内容。您可以查看其他包中的示例。配置的语法与内核Kconfig文件相同。此语法的文档可在 http://kernel.org/doc/Documentation/kbuild/kconfig-language.txt 获得

最后，您必须将新的libfoo/Config添加进package/Config.in(或者在一个类别子目录中，如果您决定将您的包放在一个现有类别中)。其中包含的文件按每个类别的字母顺序排序，除了包的名字之外不应该包含任何内容。

还需要为主机系统构建一些包。这里有两个选择:

与Config.in相同的编码风格和选项。在文件中是有效的。

Finally you have to add your new libfoo/Config.in.host to package/Config.in.host. The files included there are sorted alphabetically and are NOT supposed to contain anything but the bare name of the package.

最后，必须添加新的libfoo/Config.in.host到package/Config.in.host。其中包含的文件是按字母顺序排序的，除了包的名字之外不应该包含任何内容。

然后主机包在Host utilities菜单中有效。

在包的Config.in文件中还必须确保启用了依赖项。通常，Buildroot使用以下规则:

请注意。kconfig语言的当前问题是这两个依赖语义没有内部链接。因此，有可能select一个包，它的一个依赖项/需求没有被满足。

下面的例子说明了select和depends的用法:

请注意，这两种依赖类型仅对相同类型的依赖关系具有传递性。

这意味着，在下面的例子中:

总的来说，对于包库依赖项，应该首选select。

请注意，这些依赖项将确保依赖项选项也被启用，但不一定是在您的包之前构建的。为此，还需要在包的.mk文件中表示依赖关系。

进一步的格式化细节:参见编码风格。

许多包依赖于工具链的某些选项:C库、c++支持、线程支持、RPC支持、wchar支持或动态库支持的选择。有些包只能在特定的目标体系结构上构建，或者在处理器中有MMU的情况下。

这些依赖项必须用Config.in文件中的适当依赖项语句来表示。此外，对于工具链选项的依赖项，当选项未启用时，应该显示注释comment，以便用户知道包不可用的原因。对目标体系结构或MMU支持的依赖不应该在注释comment中可见:因为用户不太可能自由选择另一个目标，显式地显示这些依赖没有什么意义。

只有当满足工具链选项依赖关系时，config选项本身才会可见，注释comment才应该可见。这意味着包的所有其他依赖项(包括对目标体系结构和MMU支持的依赖项)都必须在注释定义上重复。为了保持清晰，这些非工具链选项的依赖语句应该与工具链选项的依赖语句分开。如果在同一个文件(通常是主包)中存在对配置选项的依赖，最好使用全局If…endif构造，而不是在注释和其他配置选项上重复依赖语句。

foo包的依赖注释comment的一般格式是:

for example:

or

请注意，本文故意保持简短，以便适合80个字符的终端。

本节的其余部分枚举了不同的目标和工具链选项、要依赖的相应配置符号以及注释中要使用的文本。

Target architecture

MMU support

Gcc _sync* built-ins used for atomic operations. They are available in variants operating on 1 byte, 2 bytes, 4 bytes and 8 bytes. Since different architectures support atomic operations on different sizes, one dependency symbol is available for each size:

Gcc _atomic* built-ins used for atomic operations.

Kernel headers