84c825f8e8
When using a br2-external tree, it is possible (as stated in our manual) to implement whatever arbitrary extra make rules (such as flashing a board, or extracting the rootfs in an NFS export...). Some of those extra rules might be exposed to the user as new entry points that the user can call by itself. However, there is no way for the br2-external to advertise those new rules in the help text. We add the possibility to do so, by adding a new make rule, called help-custom, advertised in our own help info. It is up to the br2-external tree to provide whatever help text is deemed necessary. The format of the help is completely free-form. Note that we need to provide an empty, dummy help-custom rule, since it is always advertised (making it .PHONY does not work). Since this rule is empty, make gently reports that there is "Nothing to be done for `help-local'", which is pretty well fitting when help-local was not provided (either because there's no br2-external tree, or when the br2-external tree does not provide it. Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr> Cc: Jérôme Pouiller <jezz@sysmic.org> Cc: Arnout Vandecappelle <arnout@mind.be> Cc: Thomas Petazzoni <thomas.petazzoni@free-electrons.com> Signed-off-by: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
124 lines
4.5 KiB
Plaintext
124 lines
4.5 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. 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
|
|
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.
|
|
|
|
Some examples:
|
|
|
|
-----
|
|
buildroot/ $ make BR2_EXTERNAL=/path/to/foobar menuconfig
|
|
-----
|
|
|
|
From now on, external definitions from the +/path/to/foobar+
|
|
directory will be used:
|
|
|
|
-----
|
|
buildroot/ $ make
|
|
buildroot/ $ make legal-info
|
|
-----
|
|
|
|
We can switch to another external definitions directory at any time:
|
|
|
|
-----
|
|
buildroot/ $ make BR2_EXTERNAL=/where/we/have/barfoo xconfig
|
|
-----
|
|
|
|
Or disable the usage of external definitions:
|
|
|
|
-----
|
|
buildroot/ $ make BR2_EXTERNAL= xconfig
|
|
-----
|
|
|
|
+BR2_EXTERNAL+ 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
|
|
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).
|
|
|
|
* 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.
|
|
+
|
|
.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"
|
|
------
|
|
+
|
|
Then, have a +$(BR2_EXTERNAL)/external.mk+ file that looks like:
|
|
+
|
|
------
|
|
include $(sort $(wildcard $(BR2_EXTERNAL)/package/*/*.mk))
|
|
------
|
|
+
|
|
And then in +$(BR2_EXTERNAL)/package/package1+ and
|
|
+$(BR2_EXTERNAL)/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
|
|
+$(BR2_EXTERNAL)+. 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.
|
|
|
|
Additionally, an +external.mk+ file may define the +help-custom+ make
|
|
rule, to document custom make targets specific to this +BR2_EXTERNAL+
|
|
tree. The help is completely free-form.
|
|
|
|
------
|
|
help-custom:
|
|
@echo 'Here goes your local help, where you may'
|
|
@echo 'describe some custom rules:'
|
|
@echo ' my-rule - do something'
|
|
@echo ' my-other-rule - do something else'
|
|
@echo
|
|
@echo 'Please contact support@company.com in case of problem.'
|
|
------
|