[Buildroot] [PATCH 21/21 v2] docs/manual: document multi br2-external
Yann E. MORIN
yann.morin.1998 at free.fr
Thu Oct 22 20:34:16 UTC 2015
Signed-off-by: "Yann E. MORIN" <yann.morin.1998 at free.fr>
---
docs/manual/customize-outside-br.txt | 62 ++++++++++++++++++++++++------------
1 file changed, 41 insertions(+), 21 deletions(-)
diff --git a/docs/manual/customize-outside-br.txt b/docs/manual/customize-outside-br.txt
index afc5b78..9d5b521 100644
--- a/docs/manual/customize-outside-br.txt
+++ b/docs/manual/customize-outside-br.txt
@@ -17,19 +17,18 @@ place project-specific customizations in two locations:
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
++BR2_EXTERNAL+ is an environment variable that can be set to contain the
+paths to one or more directories 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.
+Paths in +BR2_EXTERNAL+ can be either absolute or relative paths, but it
+is important to note that relative paths are interpreted relative to the
+main Buildroot source directory, *not* to the Buildroot output directory.
Some examples:
@@ -51,6 +50,12 @@ We can switch to another external definitions directory at any time:
buildroot/ $ make BR2_EXTERNAL=/where/we/have/barfoo xconfig
-----
+We can also use multiple +BR2_EXTERNAL+ locations:
+
+----
+buildroot/ $ make BR2_EXTERNAL="/path/to/foobar /where/we/have/barfoo" menuconfig
+----
+
Or disable the usage of external definitions:
-----
@@ -60,12 +65,22 @@ buildroot/ $ make BR2_EXTERNAL= xconfig
A +BR2_EXTERNAL+ tree must contain at least those three files:
+external.id+::
- That file should contain the ID for the +BR2_EXTERNAL+ tree.
+ That file should contain the ID for that +BR2_EXTERNAL+ tree.
That ID is used to construct the +BR2_EXTERNAL_$(ID)+ variable,
available in +Config.in+ and +external.mk+ (see below), so that ID
must be a valid make and Kconfig variable. Buildroot sets
+BR2_EXTERNAL_$(ID)+ to the path of the +BR2_EXTERNAL+ tree.
+
+.Note:
+Since it is possible to use multiple +BR2_EXTERNAL+ trees at once, this
+ ID is used by Buildroot to generate variables for each of those trees.
+ That ID is used to identify your +BR2_EXTERNAL+ tree, so try to come up
+ with an ID that really describes your +BR2_EXTERNAL+ tree, in order for
+ it to be relatively unique, so that it does not clash with another ID
+ from another +BR2_EXTERNAL+ tree, especially if you are planning on
+ somehow sharing your +BR2_EXTERNAL+ tree with third parties or using
+ +BR2_EXTERNAL+ external trees from third parties.
++
Examples:
+
** +FOO+ -> +BR2_EXTERNAL_FOO+
@@ -93,22 +108,22 @@ Using +BR2_EXTERNAL+ then allows three different things:
+$(BR2_EXTERNAL_BAR_42)/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.
+ * One can store package recipes (i.e. +Config.in+ and +<packagename>.mk+),
+ or even custom configuration options and make logic. Buildroot
+ automatically includes the +Config.in+ from each paths in +BR2_EXTERNAL+
+ to make it appear in a sub-menu labelled _User-provided options_ at the
+ root of the main configuration menu, and includes the +external.mk+ from
+ each paths in +BR2_EXTERNAL+ 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:
+ way to do this is to write +Config.in+ files that look like:
+
------
source "$BR2_EXTERNAL_BAR_42/package/package1/Config.in"
source "$BR2_EXTERNAL_BAR_42/package/package2/Config.in"
------
+
-Then, have a +$(BR2_EXTERNAL)/external.mk+ file that looks like:
+Then, write +/external.mk+ files that look like:
+
------
include $(sort $(wildcard $(BR2_EXTERNAL_BAR_42)/package/*/*.mk))
@@ -121,7 +136,12 @@ And then in +$(BR2_EXTERNAL_FOO_42)/package/package1+ and
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
+ a +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.
+ +User-provided configs+ label in the 'make list-defconfigs' output.
++
+.Note
+If a defconfig file is present in more than one +BR2_EXTERNAL+ location,
+ then the last one is used. It is also possible to override a defconfig
+ bundled in Buildroot.
--
1.9.1
More information about the buildroot
mailing list