kumquat-buildroot/docs/manual/customize-outside-br.txt

// -*- 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 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
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/foobar menuconfig
-----

From now on, definitions from the +/path/to/foobar+ 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/barfoo xconfig
-----

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 the
   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.
+
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 +Config.in+ to make it appear in the top-level
   configuration menu, and includes +external.mk+ 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 under the
   +User-provided configs+' label in the 'make list-defconfigs' output.