[Buildroot] [PATCH 11/16 v3] docs/manual: document the br2-external ID
Romain Naour
romain.naour at gmail.com
Sat Aug 6 15:48:54 UTC 2016
Hi Yann,
Le 17/07/2016 à 12:34, Yann E. MORIN a écrit :
> Update the manual with the new external.id mandatory file.
>
> Take the opportunity to add a section listing all mandatory files,
> Config.in, external.mk and the new external.id, instead of just hinting
> about them in the external package recipes section.
>
> Change the example to use the ID-suffixed variable instead of the raw
> BR2_EXTERNAL variable. Even though it is still possible to write a
> br2-external tree that is not multi-aware, we only document it with an
> ID.
>
> Signed-off-by: "Yann E. MORIN" <yann.morin.1998 at free.fr>
> Cc: Thomas Petazzoni <thomas.petazzoni at free-electrons.com>
> Cc: Peter Korsgaard <jacmet at uclibc.org>
> Cc: Thomas De Schampheleire <patrickdepinguin at gmail.com>
> Cc: Arnout Vandecappelle <arnout at mind.be>
> Cc: Samuel Martin <s.martin49 at gmail.com>
> Cc: Jeremy Rosen <jeremy.rosen at openwide.fr>
>
> ---
> Changes v2 -> v3:
> - better document the content of the ID file (Jeremy)
> ---
> docs/manual/customize-outside-br.txt | 59 ++++++++++++++++++++++++++----------
> 1 file changed, 43 insertions(+), 16 deletions(-)
>
> diff --git a/docs/manual/customize-outside-br.txt b/docs/manual/customize-outside-br.txt
> index 9ad177d..839d1b1 100644
> --- a/docs/manual/customize-outside-br.txt
> +++ b/docs/manual/customize-outside-br.txt
> @@ -57,19 +57,50 @@ Or disable the usage of external definitions:
> buildroot/ $ make BR2_EXTERNAL= xconfig
> -----
>
> -+BR2_EXTERNAL+ allows three different things:
> +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 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.
> ++
> +Examples of an +external.mk+ file that declares the ID +FOO+:
> ++
> +----
> +$ cat external.mk
> +FOO
> +----
> ++
> +Examples of IDs and the corresponding +BR2_EXTERNAL_$(ID)+ variable:
> ++
> + * +FOO+ -> +BR2_EXTERNAL_FOO+
> + * +BAR_42+ -> +BR2_EXTERNAL_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 +BR2_EXTERNAL+ 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 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
> + location. The location of the +BR2_EXTERNAL+ tree is available in the
> + Buildroot configuration using the +BR2_EXTERNAL_$(ID)+ variable. As
> + an example, (considering the ID +BAR_42+), one could set the
> + +BR2_ROOTFS_OVERLAY+ Buildroot option to
> + +$(BR2_EXTERNAL_BAR_42)/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).
> + +$(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
> @@ -77,27 +108,23 @@ buildroot/ $ make BR2_EXTERNAL= xconfig
> make it appear in the top-level configuration menu, and includes
> +$(BR2_EXTERNAL)/external.mk+ with the rest of the makefile logic.
> +
> -.Note
> -Providing +Config.in+ and +external.mk+ is mandatory, but they can be
> - empty.
> -+
> 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:
> +
> ------
> -source "$BR2_EXTERNAL/package/package1/Config.in"
> -source "$BR2_EXTERNAL/package/package2/Config.in"
> +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:
> +
> ------
> -include $(sort $(wildcard $(BR2_EXTERNAL)/package/*/*.mk))
> +include $(sort $(wildcard $(BR2_EXTERNAL_BAR_42)/package/*/*.mk))
> ------
> +
> -And then in +$(BR2_EXTERNAL)/package/package1+ and
> - +$(BR2_EXTERNAL)/package/package2+ create normal Buildroot
> +And then in +$(BR2_EXTERNAL_FOO_42)/package/package1+ and
> + +$(BR2_EXTERNAL_FOO_42)/package/package2+ create normal Buildroot
Here BR2_EXTERNAL_FOO or BR2_EXTERNAL_BAR_42 ?
BR2_EXTERNAL_BAR_42 it seems ;-)
Best regards,
Romain
> 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.
>
More information about the buildroot
mailing list