4d36f10426
This patch reworks the section on BR2_EXTERNAL as follows: - move note about upstreaming to the chapter introduction - streamline the section with the previously added section 'Recommended directory structure', avoiding duplication. - use $(BR2_EXTERNAL) rather than BR2_EXTERNAL when referring to file paths. - some general rewording Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> Signed-off-by: Peter Korsgaard <peter@korsgaard.com>
103 lines
3.9 KiB
Plaintext
103 lines
3.9 KiB
Plaintext
// -*- mode:doc -*- ;
|
|
|
|
[[outside-br-custom]]
|
|
=== Keeping customizations outside of Buildroot
|
|
|
|
As already briefly mentioned in xref:customize-dir-structure[], you can
|
|
place project-specific customizations in two locations:
|
|
|
|
* directly within the Buildroot tree, typically maintaining them using
|
|
branches in a version control system so that upgrading to a newer
|
|
Buildroot release is easy.
|
|
|
|
* outside of the Buildroot tree, using the +BR2_EXTERNAL+ mechanism.
|
|
This mechanism allows to keep package recipes, board support and
|
|
configuration files outside of the Buildroot tree, while still
|
|
having them nicely integrated in the build logic. This section
|
|
explains how to use +BR2_EXTERNAL+.
|
|
|
|
+BR2_EXTERNAL+ is an environment variable that can be used to point to
|
|
a directory that contains Buildroot customizations. It can be passed
|
|
to any Buildroot +make+ invocation. It is automatically saved in the
|
|
hidden +.br-external+ file in the output directory. Thanks to this,
|
|
there is no need to pass +BR2_EXTERNAL+ at every +make+ invocation. It
|
|
can however be changed at any time by passing a new value, and can be
|
|
removed by passing an empty value.
|
|
|
|
*Note:* the +BR2_EXTERNAL+ path can be either an absolute or a relative path,
|
|
but if it's passed as a relative path, it is important to note that it
|
|
is interpreted relative to the main Buildroot source directory, *not*
|
|
to the Buildroot output directory.
|
|
|
|
Some examples:
|
|
|
|
-----
|
|
buildroot/ $ make BR2_EXTERNAL=/path/to/foobar menuconfig
|
|
-----
|
|
|
|
From now on, external definitions from the +/path/to/foobar+
|
|
directory will be used:
|
|
|
|
-----
|
|
buildroot/ $ make
|
|
buildroot/ $ make legal-info
|
|
-----
|
|
|
|
We can switch to another external definitions directory at any time:
|
|
|
|
-----
|
|
buildroot/ $ make BR2_EXTERNAL=/where/we/have/barfoo xconfig
|
|
-----
|
|
|
|
Or disable the usage of external definitions:
|
|
|
|
-----
|
|
buildroot/ $ make BR2_EXTERNAL= xconfig
|
|
-----
|
|
|
|
+BR2_EXTERNAL+ allows three different things:
|
|
|
|
* One can store all the board-specific configuration files there,
|
|
such as the kernel configuration, the root filesystem overlay, or
|
|
any other configuration file for which Buildroot allows to set its
|
|
location. The +BR2_EXTERNAL+ value is available within the
|
|
Buildroot configuration using +$(BR2_EXTERNAL)+. As an example, one
|
|
could set the +BR2_ROOTFS_OVERLAY+ Buildroot option to
|
|
+$(BR2_EXTERNAL)/board/<boardname>/overlay/+ (to specify a root
|
|
filesystem overlay), or the +BR2_LINUX_KERNEL_CUSTOM_CONFIG_FILE+
|
|
Buildroot option to
|
|
+$(BR2_EXTERNAL)/board/<boardname>/kernel.config+ (to specify the
|
|
location of the kernel configuration file).
|
|
|
|
* One can store package recipes (i.e. +Config.in+ and
|
|
+<packagename>.mk+), or even custom configuration options and make
|
|
logic. Buildroot automatically includes +$(BR2_EXTERNAL)/Config.in+ to
|
|
make it appear in the top-level configuration menu, and includes
|
|
+$(BR2_EXTERNAL)/external.mk+ with the rest of the makefile logic.
|
|
Providing those two files is mandatory, but they can be empty.
|
|
+
|
|
The main usage of this is to store package recipes. The recommended
|
|
way to do this is to write a +$(BR2_EXTERNAL)/Config.in+ file that
|
|
looks like:
|
|
+
|
|
------
|
|
source "$BR2_EXTERNAL/package/<boardname>/package1/Config.in"
|
|
source "$BR2_EXTERNAL/package/<boardname>/package2/Config.in"
|
|
------
|
|
+
|
|
Then, have a +$(BR2_EXTERNAL)/external.mk+ file that looks like:
|
|
+
|
|
------
|
|
include $(sort $(wildcard $(BR2_EXTERNAL)/package/*/*/*.mk))
|
|
------
|
|
+
|
|
And then in +$(BR2_EXTERNAL)/package/<boardname>/package1+ and
|
|
+$(BR2_EXTERNAL)/package/<boardname>/package2+ create normal Buildroot
|
|
package recipes, as explained in xref:adding-packages[].
|
|
|
|
* One can store Buildroot defconfigs in the +configs+ subdirectory of
|
|
+$(BR2_EXTERNAL)+. Buildroot will automatically show them in the
|
|
output of +make help+ and allow them to be loaded with the normal
|
|
+make <name>_defconfig+ command. They will be visible under the
|
|
+User-provided configs+' label in the 'make help' output.
|