339e1c9500
Currently, it is not possible for a br2-external tree to override a
defconfig bundled in Buildroot, nor is it possible to override one from
a previous br2-external tree in the stack.
However, it is interesting that a latter br2-external tree be able to
override a defconfig:
- the ones bundled in Buildroot are minimalist, and almost always
build a toolchain, so a br2-external tree may want to provide a
"better" defconfig (better, in the sense "suited for the project");
- similarly for a defconfig from a previous br2-external tree.
But we can't do that, as the rules for the defconfigs are generated in
the order the br2-external trees are specified, all after the bundled
defconfigs. Those rule are patten-matching rules, which means that the
first one to match is used, and the following ones are ignored.
Add a new utility macro, 'reverse', inspired from GMSL, that does what
it says: reverse a list of words.
Use that macro to reverse the list of br2-external trees, so that the
latters win over the formers, and even over bundled ones.
Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
Cc: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
Cc: Arnout Vandecappelle <arnout@mind.be>
Cc: Samuel Martin <s.martin49@gmail.com>
Cc: Romain Naour <romain.naour@openwide.fr>
Cc: Julien CORJON <corjon.j@ecagroup.com>
Signed-off-by: Peter Korsgaard <peter@korsgaard.com>
175 lines
6.7 KiB
Plaintext
175 lines
6.7 KiB
Plaintext
// -*- mode:doc -*- ;
|
|
// vim: set syntax=asciidoc:
|
|
|
|
[[outside-br-custom]]
|
|
=== Keeping customizations outside of Buildroot
|
|
|
|
As already briefly mentioned in xref:customize-dir-structure[], you can
|
|
place project-specific customizations in two locations:
|
|
|
|
* directly within the Buildroot tree, typically maintaining them using
|
|
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.
|
|
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. 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 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.
|
|
|
|
.Note
|
|
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.
|
|
|
|
.Note:
|
|
If using an br2-external tree from before Buildroot 2016.11, you need to
|
|
convert it before you can use it with Buildroot 2016.11 onward. See
|
|
xref:br2-external-converting[] for help on doing so.
|
|
|
|
Some examples:
|
|
|
|
-----
|
|
buildroot/ $ make BR2_EXTERNAL=/path/to/foo menuconfig
|
|
-----
|
|
|
|
From now on, definitions from the +/path/to/foo+ br2-external tree
|
|
will be used:
|
|
|
|
-----
|
|
buildroot/ $ make
|
|
buildroot/ $ make legal-info
|
|
-----
|
|
|
|
We can switch to another br2-external tree at any time:
|
|
|
|
-----
|
|
buildroot/ $ make BR2_EXTERNAL=/where/we/have/bar xconfig
|
|
-----
|
|
|
|
We can also use multiple br2-external trees:
|
|
|
|
----
|
|
buildroot/ $ make BR2_EXTERNAL=/path/to/foo:/where/we/have/bar menuconfig
|
|
----
|
|
|
|
Or disable the usage of any br2-external tree:
|
|
|
|
-----
|
|
buildroot/ $ make BR2_EXTERNAL= xconfig
|
|
-----
|
|
|
|
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.
|
|
+
|
|
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+:
|
|
+
|
|
----
|
|
$ 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 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:
|
|
+
|
|
------
|
|
source "$BR2_EXTERNAL_BAR_42_PATH/package/package1/Config.in"
|
|
source "$BR2_EXTERNAL_BAR_42_PATH/package/package2/Config.in"
|
|
------
|
|
+
|
|
Then, have an +external.mk+ file that looks like:
|
|
+
|
|
------
|
|
include $(sort $(wildcard $(BR2_EXTERNAL_BAR_42_PATH)/package/*/*.mk))
|
|
------
|
|
+
|
|
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
|
|
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 in the
|
|
'make list-defconfigs' output, below an +External configs+ label that
|
|
contains the name of the br2-extermnal tree they are defined in.
|
|
+
|
|
.Note:
|
|
If a defconfig file is present in more than one br2-external tree, then
|
|
the one from the last br2-external tree is used. It is thus possible
|
|
to override a defconfig bundled in Buildroot or another br2-external
|
|
tree.
|