[Buildroot] [PATCH 16/16 v3] docs/manual: document multi br2-external
Romain Naour
romain.naour at gmail.com
Sat Aug 6 16:15:49 UTC 2016
Hi Yann,
Le 17/07/2016 à 12:34, Yann E. MORIN a écrit :
Reviewed-by: Romain Naour <romain.naour at gmail.com>
Best regards,
Romain
> 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 839d1b1..ed4a949 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,13 +65,23 @@ 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.
> The format for this file is a single line with the ID.
> +
> +.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+ trees from third parties.
> ++
> Examples of an +external.mk+ file that declares the ID +FOO+:
> +
> ----
> @@ -102,22 +117,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))
> @@ -130,7 +145,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.
>
More information about the buildroot
mailing list