// -*- mode:doc -*- ;
[[outside-br-custom]]
-=== Keeping customizations outside Buildroot
+=== Keeping customizations outside of Buildroot
-The Buildroot community recommends and encourages upstreaming to the
-official Buildroot version the packages and board support that are
-written by developers. However, it is sometimes not possible or
-desirable because some of these packages or board support are highly
-specific or proprietary.
+As already briefly mentioned in xref:customize-dir-structure[], you can
+place project-specific customizations in two locations:
-In this case, Buildroot users are offered two choices:
+ * 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.
- * They can add their packages, board support and configuration files
- directly within the Buildroot tree, and maintain them by using
- branches in a version control system.
-
- * They can use the +BR2_EXTERNAL+ mechanism, which 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. The following paragraphs give details on how to
- use +BR2_EXTERNAL+.
+ * 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. By doing this,
+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*
-the Buildroot output directory.
+to the Buildroot output directory.
Some examples:
buildroot/ $ make BR2_EXTERNAL=/path/to/foobar menuconfig
-----
-Starting from now on, external definitions from the +/path/to/foobar+
+From now on, external definitions from the +/path/to/foobar+
directory will be used:
-----
buildroot/ $ make BR2_EXTERNAL= xconfig
-----
-+BR2_EXTERNAL+ then allows three different things:
++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
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). To achieve this, it is
- recommended but not mandatory, to store those details in
- directories called +board/<boardname>/+ under +BR2_EXTERNAL+. This
- matches the directory structure used within Buildroot.
+ 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
+ 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.
+ +$(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+ that looks
- like:
+ way to do this is to write a +$(BR2_EXTERNAL)/Config.in+ file that
+ looks like:
+
------
-source "$BR2_EXTERNAL/package/package1/Config.in"
-source "$BR2_EXTERNAL/package/package2/Config.in"
+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:
+Then, have a +$(BR2_EXTERNAL)/external.mk+ file that looks like:
+
------
-include $(sort $(wildcard $(BR2_EXTERNAL)/package/*/*.mk))
+include $(sort $(wildcard $(BR2_EXTERNAL)/package/*/*/*.mk))
------
+
-And then in +BR2_EXTERNAL/package/package1+ and
- +BR2_EXTERNAL/package/package2+ create normal Buildroot package
- recipes, as explained in xref:adding-packages[].
+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
+ +$(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.
-
-In the end, a typical +BR2_EXTERNAL+ directory organization would
-generally be:
-
------
-$(BR2_EXTERNAL)/
-+-- Config.in
-+-- external.mk
-+-- board/
-| +-- <boardname>/
-| +-- linux.config
-| +-- overlay/
-| +-- etc/
-| +-- <some file>
-+-- configs/
-| +-- <boardname>_defconfig
-+-- package/
- +-- package1/
- | +-- Config.in
- | +-- package1.mk
- +-- package2/
- +-- Config.in
- +-- package2.mk
-------
+ +User-provided configs+' label in the 'make help' output.
projects / buildroot.git / commitdiff