2 // vim: set syntax=asciidoc:
5 === Keeping customizations outside of Buildroot
7 As already briefly mentioned in xref:customize-dir-structure[], you can
8 place project-specific customizations in two locations:
10 * directly within the Buildroot tree, typically maintaining them using
11 branches in a version control system so that upgrading to a newer
12 Buildroot release is easy.
14 * outside of the Buildroot tree, using the +BR2_EXTERNAL+ mechanism.
15 This mechanism allows to keep package recipes, board support and
16 configuration files outside of the Buildroot tree, while still
17 having them nicely integrated in the build logic. This section
18 explains how to use +BR2_EXTERNAL+.
20 +BR2_EXTERNAL+ is an environment variable that can be used to point to
21 a directory that contains Buildroot customizations. It can be passed
22 to any Buildroot +make+ invocation. It is automatically saved in the
23 hidden +.br-external+ file in the output directory. Thanks to this,
24 there is no need to pass +BR2_EXTERNAL+ at every +make+ invocation. It
25 can however be changed at any time by passing a new value, and can be
26 removed by passing an empty value.
29 The +BR2_EXTERNAL+ path can be either an absolute or a relative path,
30 but if it's passed as a relative path, it is important to note that it
31 is interpreted relative to the main Buildroot source directory, *not*
32 to the Buildroot output directory.
37 buildroot/ $ make BR2_EXTERNAL=/path/to/foobar menuconfig
40 From now on, external definitions from the +/path/to/foobar+
41 directory will be used:
45 buildroot/ $ make legal-info
48 We can switch to another external definitions directory at any time:
51 buildroot/ $ make BR2_EXTERNAL=/where/we/have/barfoo xconfig
54 Or disable the usage of external definitions:
57 buildroot/ $ make BR2_EXTERNAL= xconfig
60 +BR2_EXTERNAL+ allows three different things:
62 * One can store all the board-specific configuration files there,
63 such as the kernel configuration, the root filesystem overlay, or
64 any other configuration file for which Buildroot allows to set its
65 location. The +BR2_EXTERNAL+ value is available within the
66 Buildroot configuration using +$(BR2_EXTERNAL)+. As an example, one
67 could set the +BR2_ROOTFS_OVERLAY+ Buildroot option to
68 +$(BR2_EXTERNAL)/board/<boardname>/overlay/+ (to specify a root
69 filesystem overlay), or the +BR2_LINUX_KERNEL_CUSTOM_CONFIG_FILE+
71 +$(BR2_EXTERNAL)/board/<boardname>/kernel.config+ (to specify the
72 location of the kernel configuration file).
74 * One can store package recipes (i.e. +Config.in+ and
75 +<packagename>.mk+), or even custom configuration options and make
76 logic. Buildroot automatically includes +$(BR2_EXTERNAL)/Config.in+ to
77 make it appear in the top-level configuration menu, and includes
78 +$(BR2_EXTERNAL)/external.mk+ with the rest of the makefile logic.
81 Providing +Config.in+ and +external.mk+ is mandatory, but they can be
84 The main usage of this is to store package recipes. The recommended
85 way to do this is to write a +$(BR2_EXTERNAL)/Config.in+ file that
89 source "$BR2_EXTERNAL/package/package1/Config.in"
90 source "$BR2_EXTERNAL/package/package2/Config.in"
93 Then, have a +$(BR2_EXTERNAL)/external.mk+ file that looks like:
96 include $(sort $(wildcard $(BR2_EXTERNAL)/package/*/*.mk))
99 And then in +$(BR2_EXTERNAL)/package/package1+ and
100 +$(BR2_EXTERNAL)/package/package2+ create normal Buildroot
101 package recipes, as explained in xref:adding-packages[].
102 If you prefer, you can also group the packages in subdirectories
103 called <boardname> and adapt the above paths accordingly.
105 * One can store Buildroot defconfigs in the +configs+ subdirectory of
106 +$(BR2_EXTERNAL)+. Buildroot will automatically show them in the
107 output of +make list-defconfigs+ and allow them to be loaded with the
108 normal +make <name>_defconfig+ command. They will be visible under the
109 +User-provided configs+' label in the 'make list-defconfigs' output.