|
@@ -11,25 +11,27 @@ place project-specific customizations in two locations:
|
|
|
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.
|
|
|
+ * 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.
|
|
|
+ having them nicely integrated in the build logic. We call this
|
|
|
+ location a _br2-external tree_. This section explains how to use
|
|
|
+ the br2-external mechanism and what to provide in a br2-external
|
|
|
+ tree.
|
|
|
+
|
|
|
+One can tell Buildroot to use a br2-external tree by setting the
|
|
|
++BR2_EXTERNAL+ make variable set to the path of the br2-external tree
|
|
|
+to use. It can be passed to any Buildroot +make+ invocation. It is
|
|
|
+automatically saved in the hidden +.br-external.mk+ 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.
|
|
|
+The path to a br2-external tree can be either absolute or relative.
|
|
|
+If it is 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:
|
|
|
|
|
@@ -37,73 +39,107 @@ Some examples:
|
|
|
buildroot/ $ make BR2_EXTERNAL=/path/to/foobar menuconfig
|
|
|
-----
|
|
|
|
|
|
-From now on, external definitions from the +/path/to/foobar+
|
|
|
-directory will be used:
|
|
|
+From now on, definitions from the +/path/to/foobar+ br2-external tree
|
|
|
+will be used:
|
|
|
|
|
|
-----
|
|
|
buildroot/ $ make
|
|
|
buildroot/ $ make legal-info
|
|
|
-----
|
|
|
|
|
|
-We can switch to another external definitions directory at any time:
|
|
|
+We can switch to another br2-external tree at any time:
|
|
|
|
|
|
-----
|
|
|
buildroot/ $ make BR2_EXTERNAL=/where/we/have/barfoo xconfig
|
|
|
-----
|
|
|
|
|
|
-Or disable the usage of external definitions:
|
|
|
+Or disable the usage of any br2-external tree:
|
|
|
|
|
|
-----
|
|
|
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.
|
|
|
+A br2-external tree must contain at least those three files:
|
|
|
+
|
|
|
++external.desc+::
|
|
|
+ That file shall contain the _name_ for the br2-external tree. That name
|
|
|
+ must only use ASCII characters in the set +[A-Za-z0-9_]+; any other
|
|
|
+ character is forbidden. The format for this file is a single line with
|
|
|
+ the keyword 'name:', followed by one or more spaces, followed by the
|
|
|
+ name.
|
|
|
+
|
|
|
-.Note
|
|
|
-Providing +Config.in+ and +external.mk+ is mandatory, but they can be
|
|
|
- empty.
|
|
|
+Buildroot sets +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.
|
|
|
++
|
|
|
+Example of an +external.desc+ file that declares the name +FOO+:
|
|
|
++
|
|
|
+----
|
|
|
+$ cat external.desc
|
|
|
+name: FOO
|
|
|
+----
|
|
|
++
|
|
|
+Examples of names and the corresponding +BR2_EXTERNAL_$(NAME)_PATH+
|
|
|
+variables:
|
|
|
++
|
|
|
+ * +FOO+ -> +BR2_EXTERNAL_FOO_PATH+
|
|
|
+ * +BAR_42+ -> +BR2_EXTERNAL_BAR_42_PATH+
|
|
|
++
|
|
|
+In the following examples, it is assumed the name to be set to +BAR_42+.
|
|
|
+
|
|
|
++Config.in+::
|
|
|
++external.mk+::
|
|
|
+ Those files (which may each be empty) can be used to define package
|
|
|
+ recipes, like for packages bundled in Buildroot itself, or other
|
|
|
+ custom configuration options.
|
|
|
+
|
|
|
+Using a br2-external tree then 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 the location (by
|
|
|
+ using the +BR2_EXTERNAL_$(NAME)_PATH+ variable). For example, you
|
|
|
+ could set the paths to a global patch directory, to a rootfs overlay
|
|
|
+ and to the kernel configuration file as follows (e.g. by running
|
|
|
+ `make menuconfig` and filling in these options):
|
|
|
++
|
|
|
+----
|
|
|
+BR2_GLOBAL_PATCH_DIR=$(BR2_EXTERNAL_BAR_42_PATH)/patches/
|
|
|
+BR2_ROOTFS_OVERLAY=$(BR2_EXTERNAL_BAR_42_PATH)/board/<boardname>/overlay/
|
|
|
+BR2_LINUX_KERNEL_CUSTOM_CONFIG_FILE=$(BR2_EXTERNAL_BAR_42_FOO)/board/<boardname>/kernel.config
|
|
|
+----
|
|
|
+
|
|
|
+ * One can store package recipes (i.e. +Config.in+ and +<packagename>.mk+),
|
|
|
+ or even custom configuration options and make logic. Buildroot
|
|
|
+ automatically includes +Config.in+ to make it appear in the top-level
|
|
|
+ configuration menu, and includes +external.mk+ with the rest of the
|
|
|
+ makefile logic.
|
|
|
+
|
|
|
-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:
|
|
|
+The main usage of this is to store package recipes. The recommended way
|
|
|
+ to do this is to write a +Config.in+ file that looks like:
|
|
|
+
|
|
|
------
|
|
|
-source "$BR2_EXTERNAL/package/package1/Config.in"
|
|
|
-source "$BR2_EXTERNAL/package/package2/Config.in"
|
|
|
+source "$BR2_EXTERNAL_BAR_42_PATH/package/package1/Config.in"
|
|
|
+source "$BR2_EXTERNAL_BAR_42_PATH/package/package2/Config.in"
|
|
|
------
|
|
|
+
|
|
|
-Then, have a +$(BR2_EXTERNAL)/external.mk+ file that looks like:
|
|
|
+Then, have an +external.mk+ file that looks like:
|
|
|
+
|
|
|
------
|
|
|
-include $(sort $(wildcard $(BR2_EXTERNAL)/package/*/*.mk))
|
|
|
+include $(sort $(wildcard $(BR2_EXTERNAL_BAR_42_PATH)/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_FOO_42_PATH)/package/package1+ and
|
|
|
+ +$(BR2_EXTERNAL_FOO_42_PATH)/package/package2+ create normal
|
|
|
+ Buildroot package recipes, as explained in xref:adding-packages[].
|
|
|
If you prefer, you can also group the packages in subdirectories
|
|
|
called <boardname> and adapt the above paths accordingly.
|
|
|
|
|
|
* One can store Buildroot defconfigs in the +configs+ subdirectory of
|
|
|
- +$(BR2_EXTERNAL)+. Buildroot will automatically show them in the
|
|
|
+ the br2-external tree. Buildroot will automatically show them in the
|
|
|
output of +make list-defconfigs+ 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 list-defconfigs' output.
|