docs/manual/customize-outside-br.txt

   1 // -*- mode:doc -*- ;
   2 // vim: set syntax=asciidoc:
   3
   4 [[outside-br-custom]]
   5 === Keeping customizations outside of Buildroot
   6
   7 As already briefly mentioned in xref:customize-dir-structure[], you can
   8 place project-specific customizations in two locations:
   9
  10  * directly within the Buildroot tree, typically maintaining them using
  11    branches in a version control system so that upgrading to a newer
  12    Buildroot release is easy.
  13
  14  * outside of the Buildroot tree, using the +BR2_EXTERNAL+ mechanism.
  15    This mechanism allows to keep package recipes, board support and
  16    configuration files outside of the Buildroot tree, while still
  17    having them nicely integrated in the build logic. This section
  18    explains how to use +BR2_EXTERNAL+.
  19
  20 +BR2_EXTERNAL+ is an environment variable that can be used to point to
  21 a directory that contains Buildroot customizations. It can be passed
  22 to any Buildroot +make+ invocation. It is automatically saved in the
  23 hidden +.br-external+ file in the output directory. Thanks to this,
  24 there is no need to pass +BR2_EXTERNAL+ at every +make+ invocation. It
  25 can however be changed at any time by passing a new value, and can be
  26 removed by passing an empty value.
  27
  28 *Note:* the +BR2_EXTERNAL+ path can be either an absolute or a relative path,
  29 but if it's passed as a relative path, it is important to note that it
  30 is interpreted relative to the main Buildroot source directory, *not*
  31 to the Buildroot output directory.
  32
  33 Some examples:
  34
  35 -----
  36  buildroot/ $ make BR2_EXTERNAL=/path/to/foobar menuconfig
  37 -----
  38
  39 From now on, external definitions from the +/path/to/foobar+
  40 directory will be used:
  41
  42 -----
  43  buildroot/ $ make
  44  buildroot/ $ make legal-info
  45 -----
  46
  47 We can switch to another external definitions directory at any time:
  48
  49 -----
  50  buildroot/ $ make BR2_EXTERNAL=/where/we/have/barfoo xconfig
  51 -----
  52
  53 Or disable the usage of external definitions:
  54
  55 -----
  56  buildroot/ $ make BR2_EXTERNAL= xconfig
  57 -----
  58
  59 +BR2_EXTERNAL+ allows three different things:
  60
  61  * One can store all the board-specific configuration files there,
  62    such as the kernel configuration, the root filesystem overlay, or
  63    any other configuration file for which Buildroot allows to set its
  64    location. The +BR2_EXTERNAL+ value is available within the
  65    Buildroot configuration using +$(BR2_EXTERNAL)+. As an example, one
  66    could set the +BR2_ROOTFS_OVERLAY+ Buildroot option to
  67    +$(BR2_EXTERNAL)/board/<boardname>/overlay/+ (to specify a root
  68    filesystem overlay), or the +BR2_LINUX_KERNEL_CUSTOM_CONFIG_FILE+
  69    Buildroot option to
  70    +$(BR2_EXTERNAL)/board/<boardname>/kernel.config+ (to specify the
  71    location of the kernel configuration file).
  72
  73  * One can store package recipes (i.e. +Config.in+ and
  74    +<packagename>.mk+), or even custom configuration options and make
  75    logic. Buildroot automatically includes +$(BR2_EXTERNAL)/Config.in+ to
  76    make it appear in the top-level configuration menu, and includes
  77    +$(BR2_EXTERNAL)/external.mk+ with the rest of the makefile logic.
  78    Providing those two files is mandatory, but they can be empty.
  79 +
  80 The main usage of this is to store package recipes. The recommended
  81    way to do this is to write a +$(BR2_EXTERNAL)/Config.in+ file that
  82    looks like:
  83 +
  84 ------
  85 source "$BR2_EXTERNAL/package/package1/Config.in"
  86 source "$BR2_EXTERNAL/package/package2/Config.in"
  87 ------
  88 +
  89 Then, have a +$(BR2_EXTERNAL)/external.mk+ file that looks like:
  90 +
  91 ------
  92 include $(sort $(wildcard $(BR2_EXTERNAL)/package/*/*.mk))
  93 ------
  94 +
  95 And then in +$(BR2_EXTERNAL)/package/package1+ and
  96    +$(BR2_EXTERNAL)/package/package2+ create normal Buildroot
  97    package recipes, as explained in xref:adding-packages[].
  98    If you prefer, you can also group the packages in subdirectories
  99    called <boardname> and adapt the above paths accordingly.
 100
 101  * One can store Buildroot defconfigs in the +configs+ subdirectory of
 102    +$(BR2_EXTERNAL)+. Buildroot will automatically show them in the
 103    output of +make list-defconfigs+ and allow them to be loaded with the
 104    normal +make <name>_defconfig+ command. They will be visible under the
 105    +User-provided configs+' label in the 'make list-defconfigs' output.