[Buildroot] [PATCH 8/9 v4] docs/manual: document multi br2-external

[Yann E. MORIN]

Signed-off-by: "Yann E. MORIN" <yann.morin.1998 at free.fr>
Cc: Thomas Petazzoni <thomas.petazzoni at free-electrons.com>
Cc: Arnout Vandecappelle <arnout at mind.be>
Cc: Samuel Martin <s.martin49 at gmail.com>
Cc: Romain Naour <romain.naour at openwide.fr>
Cc: Julien CORJON <corjon.j at ecagroup.com>
---
 docs/manual/customize-outside-br.txt | 44 +++++++++++++++++++++++++++---------
 1 file changed, 33 insertions(+), 11 deletions(-)

diff --git a/docs/manual/customize-outside-br.txt b/docs/manual/customize-outside-br.txt
index f2a83a6..b0c7271 100644
--- a/docs/manual/customize-outside-br.txt
+++ b/docs/manual/customize-outside-br.txt
@@ -19,10 +19,10 @@ place project-specific customizations in two locations:
    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
+One can tell Buildroot to use one or more br2-external trees by setting
+the +BR2_EXTERNAL+ make variable set to the path(s) of the br2-external
+tree(s) 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.
@@ -36,10 +36,10 @@ the Buildroot output directory.
 Some examples:
 
 -----
-buildroot/ $ make BR2_EXTERNAL=/path/to/foobar menuconfig
+buildroot/ $ make BR2_EXTERNAL=/path/to/foo menuconfig
 -----
 
-From now on, definitions from the +/path/to/foobar+ br2-external tree
+From now on, definitions from the +/path/to/foo+ br2-external tree
 will be used:
 
 -----
@@ -50,9 +50,15 @@ buildroot/ $ make legal-info
 We can switch to another br2-external tree at any time:
 
 -----
-buildroot/ $ make BR2_EXTERNAL=/where/we/have/barfoo xconfig
+buildroot/ $ make BR2_EXTERNAL=/where/we/have/bar xconfig
 -----
 
+We can also use multiple br2-external trees:
+
+----
+buildroot/ $ make BR2_EXTERNAL=/path/to/foo:/path/to/bar menuconfig
+----
+
 Or disable the usage of any br2-external tree:
 
 -----
@@ -68,13 +74,23 @@ A br2-external tree must contain at least those three files:
    the keyword 'name:', followed by one or more spaces, followed by the
    name.
 +
-Buildroot sets +BR2_EXTERNAL_$(NAME)_PATH+ to the absolute path of the
+Buildroot sets +BR2_EXTERNAL_$(NAME)_PATH+ to the absolute path of each
    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.
 +
+.Note:
+Since it is possible to use multiple br2-external trees at once, this
+  name is used by Buildroot to generate variables for each of those trees.
+  That name is used to identify your br2-external tree, so try to come up
+  with a name that really describes your br2-external tree, in order for
+  it to be relatively unique, so that it does not clash with another name
+  from another br2-external tree, especially if you are planning on
+  somehow sharing your br2-external tree with third parties or using
+  br2-external trees from third parties.
++
 Example of an +external.desc+ file that declares the name +FOO+:
 +
 ----
@@ -114,9 +130,10 @@ BR2_LINUX_KERNEL_CUSTOM_CONFIG_FILE=$(BR2_EXTERNAL_BAR_42_FOO)/board/<boardname>
 
  * 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.
+   automatically includes the +Config.in+ from each br2-external tree to
+   make it appear in the top-level configuration menu, and includes the
+   +external.mk+ from each br2-external tree 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 +Config.in+ file that looks like:
@@ -143,3 +160,8 @@ And then in +$(BR2_EXTERNAL_FOO_42_PATH)/package/package1+ and
    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.
++
+.Note:
+If a defconfig file is present in more than one br2-external tree,
+  then the last one is used. It is also possible to override a defconfig
+  bundled in Buildroot.
-- 
2.7.4