cirros-testvm/src-cirros/buildroot-2015.05/build/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
  29 The +BR2_EXTERNAL+ path can be either an absolute or a relative path,
  30 but if it's passed as a relative path, it is important to note that it
  31 is interpreted relative to the main Buildroot source directory, *not*
  32 to the Buildroot output directory.
  33
  34 Some examples:
  35
  36 -----
  37 buildroot/ $ make BR2_EXTERNAL=/path/to/foobar menuconfig
  38 -----
  39
  40 From now on, external definitions from the +/path/to/foobar+
  41 directory will be used:
  42
  43 -----
  44 buildroot/ $ make
  45 buildroot/ $ make legal-info
  46 -----
  47
  48 We can switch to another external definitions directory at any time:
  49
  50 -----
  51 buildroot/ $ make BR2_EXTERNAL=/where/we/have/barfoo xconfig
  52 -----
  53
  54 Or disable the usage of external definitions:
  55
  56 -----
  57 buildroot/ $ make BR2_EXTERNAL= xconfig
  58 -----
  59
  60 +BR2_EXTERNAL+ allows three different things:
  61
  62  * One can store all the board-specific configuration files there,
  63    such as the kernel configuration, the root filesystem overlay, or
  64    any other configuration file for which Buildroot allows to set its
  65    location. The +BR2_EXTERNAL+ value is available within the
  66    Buildroot configuration using +$(BR2_EXTERNAL)+. As an example, one
  67    could set the +BR2_ROOTFS_OVERLAY+ Buildroot option to
  68    +$(BR2_EXTERNAL)/board/<boardname>/overlay/+ (to specify a root
  69    filesystem overlay), or the +BR2_LINUX_KERNEL_CUSTOM_CONFIG_FILE+
  70    Buildroot option to
  71    +$(BR2_EXTERNAL)/board/<boardname>/kernel.config+ (to specify the
  72    location of the kernel configuration file).
  73
  74  * One can store package recipes (i.e. +Config.in+ and
  75    +<packagename>.mk+), or even custom configuration options and make
  76    logic. Buildroot automatically includes +$(BR2_EXTERNAL)/Config.in+ to
  77    make it appear in the top-level configuration menu, and includes
  78    +$(BR2_EXTERNAL)/external.mk+ with the rest of the makefile logic.
  79 +
  80 .Note
  81 Providing +Config.in+ and +external.mk+ is mandatory, but they can be
  82    empty.
  83 +
  84 The main usage of this is to store package recipes. The recommended
  85    way to do this is to write a +$(BR2_EXTERNAL)/Config.in+ file that
  86    looks like:
  87 +
  88 ------
  89 source "$BR2_EXTERNAL/package/package1/Config.in"
  90 source "$BR2_EXTERNAL/package/package2/Config.in"
  91 ------
  92 +
  93 Then, have a +$(BR2_EXTERNAL)/external.mk+ file that looks like:
  94 +
  95 ------
  96 include $(sort $(wildcard $(BR2_EXTERNAL)/package/*/*.mk))
  97 ------
  98 +
  99 And then in +$(BR2_EXTERNAL)/package/package1+ and
 100    +$(BR2_EXTERNAL)/package/package2+ create normal Buildroot
 101    package recipes, as explained in xref:adding-packages[].
 102    If you prefer, you can also group the packages in subdirectories
 103    called <boardname> and adapt the above paths accordingly.
 104
 105  * One can store Buildroot defconfigs in the +configs+ subdirectory of
 106    +$(BR2_EXTERNAL)+. Buildroot will automatically show them in the
 107    output of +make list-defconfigs+ and allow them to be loaded with the
 108    normal +make <name>_defconfig+ command. They will be visible under the
 109    +User-provided configs+' label in the 'make list-defconfigs' output.